116 lines
4.3 KiB
Markdown
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`.
|