vps-control/docs/deployment.md

Deployment

Network

Place each agent and the backend in a WireGuard network. Bind the agent to its WireGuard address only and allow TCP/9105 solely from the control-plane peer. Alternatively bind to loopback and expose it through an authenticated tunnel. TLS termination at the agent is supported when certificate paths are configured.

Control plane

cp control-plane/.env.example control-plane/.env
mkdir -p control-plane/secrets
openssl rand -hex 32 > control-plane/secrets/db_password
openssl rand -base64 24 > control-plane/secrets/admin_password
openssl rand -hex 32 > control-plane/secrets/integration_token
openssl rand -base64 24 > control-plane/secrets/grafana_admin_password
openssl rand -hex 32 > control-plane/secrets/grafana_secret_key
# Securely copy the exact token installed on the agent:
install -m 600 /secure/source/control-plane.token control-plane/secrets/agent_token
chmod 600 control-plane/secrets/*
docker compose -f control-plane/docker-compose.yml up -d --build
docker compose -f control-plane/docker-compose.yml ps

Terminate public TLS at a maintained reverse proxy and forward only to the frontend container. Set COOKIE_SECURE=true. Restrict PostgreSQL to its Compose network; it has no published host port.

Backups and upgrades

Back up PostgreSQL with pg_dump -Fc, the .env file via a secret manager, TLS key material, and Docker secret files. Test restores periodically. Agent backup needs only /etc/vps-agent/. For upgrades, pin image tags, back up, pull/build, run docker compose up -d, then inspect health and audit events. Database migrations are forward-only; restore the database backup for rollback.

Metric samples are retained for 30 days and collected logs for seven days by the backend cleanup loop. METRICS_RETENTION and LOGS_RETENTION control these windows; log retention is constrained to one hour through 90 days. Configure database-level backups independently of retention.

Grafana and journald collection

Enable log collection explicitly on each agent:

[logs]
enabled = true
allowed_units = ["vps-agent.service", "nginx.service", "ssh.service"]
max_entries_per_request = 200
max_message_bytes = 16384

The service user also needs read access to journald. On Debian/Ubuntu this is usually granted with sudo usermod -aG systemd-journal vps-agent, followed by an agent restart. Membership permits the process to read the host journal even though the API returns only configured units, so enable it only after the host security review. The installer deliberately does not grant this access.

Start the provisioned Grafana profile with:

docker compose -f control-plane/docker-compose.yml --profile observability up -d --build

Grafana is bound to 127.0.0.1:3000, requires the password from secrets/grafana_admin_password, and comes with Prometheus/Loki datasources plus a starter dashboard. For public access, place it behind TLS, set GRAFANA_ROOT_URL, and set GRAFANA_COOKIE_SECURE=true.