113 lines
4.6 KiB
Markdown
113 lines
4.6 KiB
Markdown
# Control Plane
|
|
|
|
The control plane is a small Go API, PostgreSQL 16, and a React/TypeScript UI
|
|
served by unprivileged nginx. The browser only reaches nginx/backend; agent
|
|
credentials are mounted into the backend as files and never enter PostgreSQL or
|
|
the browser.
|
|
|
|
## Docker deployment
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
mkdir -p secrets
|
|
openssl rand -hex 32 > secrets/db_password
|
|
openssl rand -base64 24 > secrets/admin_password
|
|
openssl rand -hex 32 > secrets/integration_token
|
|
openssl rand -base64 24 > secrets/grafana_admin_password
|
|
openssl rand -hex 32 > secrets/grafana_secret_key
|
|
# Securely copy the exact token from one agent for bootstrap:
|
|
install -m 600 /secure/source/control-plane.token secrets/agent_token
|
|
chmod 600 secrets/*
|
|
docker compose config
|
|
docker compose up -d --build
|
|
docker compose ps
|
|
```
|
|
|
|
Open `http://127.0.0.1:8080` through a TLS reverse proxy. With plain local HTTP
|
|
for development only, set `COOKIE_SECURE=false`. The default host binding is
|
|
loopback. PostgreSQL and backend ports are not published.
|
|
|
|
Set `BOOTSTRAP_SERVER_NAME` and `BOOTSTRAP_SERVER_ENDPOINT` before the first
|
|
start, or enroll a server in the UI as Administrator. Endpoints must use a
|
|
literal loopback/private IP and explicit port. `credential_ref` is a filename in
|
|
`/run/secrets`, never token material. Add another Compose secret mount for each
|
|
additional server token.
|
|
|
|
## Authentication and database
|
|
|
|
On an empty database, the backend reads `secrets/admin_password`, hashes it with
|
|
Argon2id, and creates `INITIAL_ADMIN_USERNAME`. Change the bootstrap password
|
|
after adding a user-management workflow or rotate it through an audited database
|
|
administrative procedure. Sessions are stored server-side, expire after 12
|
|
hours, use Secure/HttpOnly/SameSite cookies, and require a CSRF token on writes.
|
|
|
|
Roles are Viewer (read), Operator (Fail2Ban and service actions), and
|
|
Administrator (server/firewall/policy administration). Every current mutation
|
|
is audited with actor, target, result, time, and source IP. Secrets are excluded.
|
|
|
|
The backend creates schema on startup. One-minute metric samples are retained 30
|
|
days (`METRICS_RETENTION=720h`) and agent logs seven days
|
|
(`LOGS_RETENTION=168h`). PostgreSQL is the only durable history store.
|
|
|
|
## Grafana and Loki-compatible access
|
|
|
|
The backend is both a constrained Prometheus-compatible metrics source and a
|
|
Loki-compatible read-only log source. A separate Loki server is not required:
|
|
this is what preserves the required `Grafana -> backend -> agent` boundary.
|
|
Both APIs require `Authorization: Bearer <integration_token>` and expose no
|
|
agent endpoint or credential.
|
|
|
|
For the included provisioned instance:
|
|
|
|
```bash
|
|
docker compose --profile observability up -d --build
|
|
```
|
|
|
|
Open `http://127.0.0.1:3000`, use the `admin` account and the value in
|
|
`secrets/grafana_admin_password`. The two datasources and `VPS Control Overview`
|
|
dashboard are provisioned automatically.
|
|
`grafana_secret_key` encrypts the datasource credential stored by Grafana and
|
|
must be backed up; changing it invalidates encrypted secure data.
|
|
|
|
For an external Grafana, configure:
|
|
|
|
- Prometheus datasource URL: `https://vps-control.example/integrations/prometheus`
|
|
- Loki datasource URL: `https://vps-control.example/integrations/loki`
|
|
- Custom HTTP header on both: `Authorization: Bearer <integration_token>`
|
|
|
|
The frontend proxy publishes these protected routes. Restrict them to Grafana's
|
|
source network at the outer TLS proxy when possible. Supported queries are a
|
|
deliberately small subset: direct `vps_control_*` metric selectors and Loki
|
|
stream matchers (`=` or `=~`) on `server_id`, `server_name`, `unit`, and
|
|
`priority`.
|
|
|
|
## TLS, backup, and upgrades
|
|
|
|
Terminate TLS at Caddy, nginx, Traefik, or a managed load balancer and forward to
|
|
the loopback frontend port. Preserve the original client IP only from a trusted
|
|
proxy. Keep `COOKIE_SECURE=true` in production.
|
|
|
|
Back up with:
|
|
|
|
```bash
|
|
docker compose exec -T postgres pg_dump -U vps_control -Fc vps_control > vps-control.dump
|
|
```
|
|
|
|
Also back up `.env`, reverse-proxy/TLS configuration, and secret files through a
|
|
secret manager. Test restore into a separate database. For upgrades, take a
|
|
backup, pin image/source revisions, build, then `docker compose up -d`; check
|
|
health and Audit. Migrations are forward-only in v1, so database restore is the
|
|
rollback path.
|
|
|
|
## Development
|
|
|
|
```bash
|
|
cd backend && go test ./... && go vet ./...
|
|
cd ../frontend && npm ci && npm run lint && npm run typecheck
|
|
npm test -- --run && npm run build
|
|
```
|
|
|
|
The frontend Vite server proxies `/api` to `localhost:8080`. Use a development
|
|
PostgreSQL and `COOKIE_SECURE=false`. Never point development at a production
|
|
agent credential.
|