Control Plane
The control plane is a small Go API, PostgreSQL 16, and a React/TypeScript UI served by unprivileged nginx. The browser only reaches nginx/backend; agent credentials are mounted into the backend as files and never enter PostgreSQL or the browser.
Docker deployment
cp .env.example .env
mkdir -p secrets
openssl rand -hex 32 > secrets/db_password
openssl rand -base64 24 > secrets/admin_password
openssl rand -hex 32 > secrets/integration_token
openssl rand -base64 24 > secrets/grafana_admin_password
openssl rand -hex 32 > secrets/grafana_secret_key
# Securely copy the exact token from one agent for bootstrap:
install -m 600 /secure/source/control-plane.token secrets/agent_token
chmod 600 secrets/*
docker compose config
docker compose up -d --build
docker compose ps
Open http://127.0.0.1:8080 through a TLS reverse proxy. With plain local HTTP
for development only, set COOKIE_SECURE=false. The default host binding is
loopback. PostgreSQL and backend ports are not published.
Set BOOTSTRAP_SERVER_NAME and BOOTSTRAP_SERVER_ENDPOINT before the first
start, or enroll a server in the UI as Administrator. Endpoints must use a
literal loopback/private IP and explicit port. credential_ref is a filename in
/run/secrets, never token material. Add another Compose secret mount for each
additional server token.
Authentication and database
On an empty database, the backend reads secrets/admin_password, hashes it with
Argon2id, and creates INITIAL_ADMIN_USERNAME. Change the bootstrap password
after adding a user-management workflow or rotate it through an audited database
administrative procedure. Sessions are stored server-side, expire after 12
hours, use Secure/HttpOnly/SameSite cookies, and require a CSRF token on writes.
Roles are Viewer (read), Operator (Fail2Ban and service actions), and Administrator (server/firewall/policy administration). Every current mutation is audited with actor, target, result, time, and source IP. Secrets are excluded.
The backend creates schema on startup. One-minute metric samples are retained 30
days (METRICS_RETENTION=720h) and agent logs seven days
(LOGS_RETENTION=168h). PostgreSQL is the only durable history store.
Grafana and Loki-compatible access
The backend is both a constrained Prometheus-compatible metrics source and a
Loki-compatible read-only log source. A separate Loki server is not required:
this is what preserves the required Grafana -> backend -> agent boundary.
Both APIs require Authorization: Bearer <integration_token> and expose no
agent endpoint or credential.
For the included provisioned instance:
docker compose --profile observability up -d --build
Open http://127.0.0.1:3000, use the admin account and the value in
secrets/grafana_admin_password. The two datasources and VPS Control Overview
dashboard are provisioned automatically.
grafana_secret_key encrypts the datasource credential stored by Grafana and
must be backed up; changing it invalidates encrypted secure data.
For an external Grafana, configure:
- Prometheus datasource URL:
https://vps-control.example/integrations/prometheus - Loki datasource URL:
https://vps-control.example/integrations/loki - Custom HTTP header on both:
Authorization: Bearer <integration_token>
The frontend proxy publishes these protected routes. Restrict them to Grafana's
source network at the outer TLS proxy when possible. Supported queries are a
deliberately small subset: direct vps_control_* metric selectors and Loki
stream matchers (= or =~) on server_id, server_name, unit, and
priority.
TLS, backup, and upgrades
Terminate TLS at Caddy, nginx, Traefik, or a managed load balancer and forward to
the loopback frontend port. Preserve the original client IP only from a trusted
proxy. Keep COOKIE_SECURE=true in production.
Back up with:
docker compose exec -T postgres pg_dump -U vps_control -Fc vps_control > vps-control.dump
Also back up .env, reverse-proxy/TLS configuration, and secret files through a
secret manager. Test restore into a separate database. For upgrades, take a
backup, pin image/source revisions, build, then docker compose up -d; check
health and Audit. Migrations are forward-only in v1, so database restore is the
rollback path.
Development
cd backend && go test ./... && go vet ./...
cd ../frontend && npm ci && npm run lint && npm run typecheck
npm test -- --run && npm run build
The frontend Vite server proxies /api to localhost:8080. Use a development
PostgreSQL and COOKIE_SECURE=false. Never point development at a production
agent credential.