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

116 lines
4.3 KiB
Markdown

# 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`.