🖥️ ServerControl

A lightweight Docker management API powering the Server Control Centre — real-time container control and system metrics for The Forest Den home lab.

Overview

ServerControl is a FastAPI backend that exposes Docker container management and system metrics via a REST API. It is consumed by CloudControl's Server Control Centre, enabling real-time start, stop, and restart of containers from a web UI with JWT-authenticated access.

Features

• Container Management — Start, stop, restart any Docker container via API
• Container Listing — Live status, image, ports, and creation time for all containers
• System Metrics — CPU, memory, disk usage and server uptime
• Container Logs — Fetch last N log lines from any container
• JWT Authentication — All endpoints protected
• Audit Logging — All container actions are logged

Tech Stack

Layer	Technology
Language	Python
Framework	FastAPI
Docker Interface	Docker SDK for Python
Auth	JWT
Container	Docker + Docker Compose
CI/CD	GitHub Actions (self-hosted runner)

API Endpoints

GET  /containers              — List all containers with status
POST /containers/{name}/start   — Start a container
POST /containers/{name}/stop    — Stop a container
POST /containers/{name}/restart — Restart a container
GET  /containers/{name}/logs  — Fetch container logs
GET  /system                  — CPU, memory, disk, uptime

Running Locally

git clone https://github.com/Nathan-Forest/ServerControl.git
cd ServerControl
pip install -r requirements.txt
uvicorn main:app --reload

Note: Requires Docker to be running and the user to have Docker socket access. Requires a .env file with JWT_SECRET.

Deployment

Deployed on a self-hosted Ubuntu Server via Docker Compose with access to the Docker socket (/var/run/docker.sock). Auto-deployed via GitHub Actions self-hosted runner on push to main.

Part of The Forest Den

ServerControl is the infrastructure backbone of The Forest Den, consumed by CloudControl's Server Control Centre.