Files
vps-control/docs/deployment.md
2026-09-22 23:37:05 +03:00

4.3 KiB

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.

Agent write features

On Debian/Ubuntu install the firewall userspace and persistence provider before enabling managed writes:

sudo apt-get update
sudo apt-get install -y iptables iptables-persistent fail2ban
sudo systemctl enable --now netfilter-persistent vps-agent-helper.socket

Then edit /etc/vps-agent/config.toml. All write targets must be explicitly allow-listed; use the real tunnel interface, management network and service ports for the host:

[services]
allowed = ["nginx.service", "fail2ban.service"]
inventory_limit = 512
install_enabled = true
install_timeout_seconds = 300
packages = { "nginx.service" = "nginx", "fail2ban.service" = "fail2ban" }

[firewall]
management_enabled = true
persistence_enabled = true
allowed_interfaces = ["wg0"]
allowed_sources = ["192.168.50.0/24"]
allowed_ports = [22, 80, 443, 9105]
rollback_timeout_seconds = 60
max_snapshots = 5

[fail2ban]
management_enabled = true
allowed_jails = ["sshd", "nginx-http-auth"]

Restart the daemon after editing. The UI shows every iptables rule but only rules in VPS_CONTROL_INPUT and VPS_CONTROL_RATE can be deleted. Successful changes are saved through netfilter-persistent; failed changes restore the last snapshot. Keep the control-panel port and source network in the allow-list before adding restrictive rules.

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 and connection samples are retained for 30 days and collected logs and Fail2Ban history 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.