# 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: ```bash 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: ```toml [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 ```bash 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: ```toml [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: ```bash 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`.