From 0527e045ba2a4222a6210c6e22c67633fc990188 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=94=D0=BC=D0=B8=D1=82=D1=80=D0=B8=D0=B9?= Date: Tue, 6 Oct 2026 06:40:50 +0500 Subject: [PATCH] docs: VPS infrastructure baseline (Phase -1) Record how the OVHcloud VPS used for the future registry/relay was set up: hardening, firewall policy, Docker layout, health check, recovery path. No IP addresses, keys or credentials are stored. Co-Authored-By: Claude Sonnet 5.5 --- docs/INFRASTRUCTURE.md | 152 +++++++++++++++++++++++++++++++++++++++++ docs/VPS_BASELINE.md | 105 ++++++++++++++++++++++++++++ 2 files changed, 257 insertions(+) create mode 100644 docs/INFRASTRUCTURE.md create mode 100644 docs/VPS_BASELINE.md diff --git a/docs/INFRASTRUCTURE.md b/docs/INFRASTRUCTURE.md new file mode 100644 index 0000000..5d8bbdd --- /dev/null +++ b/docs/INFRASTRUCTURE.md @@ -0,0 +1,152 @@ +# Infrastructure + +Operating notes for the CoA infrastructure node. Current measured state: [VPS_BASELINE.md](VPS_BASELINE.md). +This file never contains private keys, passwords, DB credentials, transfer PINs, API secrets or raw tokens. +`` stands for the public IPv4, which is intentionally not stored in git. + +## Role + +`coa-infra-01` (OVHcloud VPS, Ubuntu 24.04 LTS) is the shared infrastructure node for the planned services: + +``` +Registry API Relay Coordinator PostgreSQL Caddy (ingress) monitoring +``` + +Phase -1 only prepared the host. No Registry, Relay, Coordinator or schema is deployed. The VPS is not the source of +truth for any player data. + +No domain is registered. Until one exists, services are addressed by IP, and Caddy serves plain HTTP on :80. +The design keeps client protocols independent of hostnames so the relay can later be moved to separate nodes and +DNS names (`api.`, `relay.`) added without changing the client protocol. + +## Service architecture + +``` +Internet + | + 22/tcp -> sshd + 80,443/tcp + v + Caddy (container, network coa-ingress) + | + +--> Registry API (future, coa-ingress) + | + +--> PostgreSQL (future, network coa-db, --internal, no published port) +``` + +Rules: + +- PostgreSQL must never be internet-exposed: no `ports:` entry, only on the `coa-db` internal network, no UFW rule for 5432. +- Caddy is the only container allowed to publish ports (80, 443/tcp). A new inbound port needs a specific protocol and + a threat model first, then a UFW rule and a note here. +- No admin dashboards or the Docker API on public interfaces. Caddy's admin API is disabled. + +## Public ports + +| Port | Proto | Service | +|---|---|---| +| 22 | tcp | SSH, key only | +| 80 | tcp | Caddy | +| 443 | tcp | Caddy | + +## Filesystem layout + +``` +/opt/coa/ +├── bin/ helper scripts (health.sh) +├── caddy/ compose.yaml, Caddyfile +├── postgres/ compose.yaml (prepared, not started) +├── registry/ (empty) +├── relay/ (empty) +├── coordinator/ (empty) +├── monitoring/ (empty) +├── backups/ 0700, logical dumps and config archives +├── logs/ +└── secrets/ 0700 root:root, never in git +``` + +Config under `/opt/coa/*` is owned by `ubuntu`. Secrets live only in `/opt/coa/secrets` and are referenced from +compose files as Docker secrets/files, never inline. + +## SSH procedure + +```bash +ssh ubuntu@ +``` + +- ED25519 key only; root login and password authentication are disabled (`/etc/ssh/sshd_config.d/00-coa-hardening.conf`). +- To change SSH settings: edit the drop-in, run `sudo sshd -t`, `sudo systemctl reload ssh`, and **test from a second + terminal before closing the first one**. +- Lost key: use the OVH KVM console (or reinstall the VPS with a new key in the OVH reinstall dialog; this wipes data). + +## Firewall policy + +UFW, default deny incoming. Currently allowed: OpenSSH, 80/tcp, 443/tcp. + +```bash +sudo ufw status verbose +``` + +Docker-published ports bypass UFW (see VPS_BASELINE.md). Check `sudo docker ps` and `sudo ss -tulnH` after every +deployment; the only public listeners must be 22, 80, 443. + +fail2ban protects SSH (default `sshd` jail): + +```bash +sudo fail2ban-client status sshd +``` + +## Update procedure + +- Security updates install automatically (unattended-upgrades); no automatic reboot and no release upgrades. +- Manual full update (monthly, or after security advisories): + + ```bash + sudo apt update && sudo apt full-upgrade -y + test -f /var/run/reboot-required && echo "reboot needed" + ``` + + Reboot with `sudo systemctl reboot` and verify with `/opt/coa/bin/health.sh`. +- Containers: pin image tags, then `cd /opt/coa/ && sudo docker compose pull && sudo docker compose up -d`. +- Docker Engine updates come through the normal apt repository. + +## Health check + +```bash +/opt/coa/bin/health.sh +``` + +Shows uptime/load, disk, RAM, listening sockets, failed systemd units, UFW rules, fail2ban SSH bans and running +containers. No monitoring stack is installed on purpose (no Grafana/Prometheus until there is a real need). + +## Deployment commands + +```bash +# Caddy (running) +cd /opt/coa/caddy && sudo docker compose up -d +sudo docker compose logs --tail 50 + +# PostgreSQL (prepared; do NOT start until a password file exists and the schema phase begins) +sudo install -m 600 /dev/null /opt/coa/secrets/postgres_password # then write the password into it (as root) +cd /opt/coa/postgres && sudo docker compose up -d +``` + +## Backups + +- Provider backup is not a substitute for application-level backups. What OVH actually includes for this plan + (automatic backup, snapshot, KVM/rescue) still has to be confirmed in the Control Panel. +- Planned (not implemented yet): + 1. PostgreSQL logical backup: `pg_dump` to `/opt/coa/backups`, copied off the node. + 2. Infrastructure config backup: `/opt/coa` except `secrets/` and volumes. + 3. Secrets are backed up separately and never together with the config archive. +- Portable Characters are not backed up here: the VPS is not their source of truth. + +## Recovery + +| Situation | Path | +|---|---| +| SSH lockout / bad firewall | OVH Control Panel -> VPS -> KVM console, log in locally, fix `ufw`/sshd drop-in | +| Broken OS | OVH rescue mode, or Reinstall (Ubuntu 24.04 + pre-installed ED25519 key), then re-apply this document | +| Lost VPS | New VPS, follow VPS_BASELINE.md "What was configured", restore config archive and PostgreSQL dump | + +Reinstall destroys all data on the VPS. diff --git a/docs/VPS_BASELINE.md b/docs/VPS_BASELINE.md new file mode 100644 index 0000000..142c435 --- /dev/null +++ b/docs/VPS_BASELINE.md @@ -0,0 +1,105 @@ +# VPS baseline (Phase -1) + +Snapshot of the infrastructure node as configured at the end of Phase -1. No secrets, no IP addresses +(the public IP is `` throughout; it is kept out of git on purpose). + +Date configured: 2026-10-06 (UTC) + +## Inventory + +| Item | Value | +|---|---| +| Provider | OVHcloud VPS | +| Hostname | `coa-infra-01` | +| Datacenter / region | _TODO: fill from OVH Control Panel (not visible from inside the VM)_ | +| Plan / service ID | _TODO: from OVH Control Panel_ | +| OS | Ubuntu 24.04.5 LTS (noble), kernel 6.8.0-146-generic | +| CPU | 2 vCPU, Intel Haswell-class (KVM guest) | +| RAM | 3.7 GiB | +| Disk | 38 GB root (`/dev/sda1`), ~2.9 GB used after setup | +| IPv4 | 1 public address, `` | +| IPv6 | 1 public /128 address on `ens3` | +| Timezone | UTC | +| Network limit | _TODO: from OVH plan_ | +| Provider backup | _TODO: see "Open items"_ | + +## What was configured + +- OS fully upgraded (`apt full-upgrade`), rebooted onto the new kernel. +- Base packages: curl, wget, git, ca-certificates, gnupg, jq, unzip, htop, ufw, fail2ban, unattended-upgrades. +- Hostname `coa-infra-01`, timezone UTC. +- SSH: key-only, no root login (details below). +- UFW: default deny incoming, allow outgoing; only 22/tcp, 80/tcp, 443/tcp allowed. +- fail2ban: default `sshd` jail only. +- unattended-upgrades: enabled for the `-security` pockets (Ubuntu, ESM apps, ESM infra); no automatic reboot, + no release upgrades. +- Docker Engine from the official Docker apt repository (docker-ce, docker-ce-cli, containerd.io, + docker-buildx-plugin, docker-compose-plugin). +- `/opt/coa` layout, Caddy running as the future ingress, PostgreSQL definition prepared but not started. + +## Public ports (verified from an external machine) + +| Port | Proto | Service | +|---|---|---| +| 22 | tcp | sshd (key only) | +| 80 | tcp | Caddy (answers `/healthz` with `ok`, everything else 404) | +| 443 | tcp | Caddy (published, no certificate/site yet) | + +Everything else is closed, including 5432, 3306/3307, 2375/2376 (Docker API), 2019 (Caddy admin; admin API is disabled). + +## SSH + +- Login: `ssh ubuntu@` with an ED25519 key. The key is pre-installed via the OVH reinstall dialog. +- OVH sets the `ubuntu` password as expired on first install; it had to be changed once interactively + (the emailed one-time password). The password is only used for `sudo` fallback; `ubuntu` also has passwordless sudo + from the cloud image. +- Hardening drop-in: `/etc/ssh/sshd_config.d/00-coa-hardening.conf`: + + ``` + PermitRootLogin no + PasswordAuthentication no + KbdInteractiveAuthentication no + PubkeyAuthentication yes + ``` + + **The file is `00-` and not `99-` on purpose.** sshd uses the first value it finds, and the cloud image ships + `50-cloud-init.conf` with `PasswordAuthentication yes`; a `99-` file would be silently ignored. +- Ubuntu 24.04 starts sshd via socket activation (`ssh.socket`); that is expected. +- The SSH port is unchanged (22). +- Gate checked from a fresh session: key login works, `sudo` works, `root` and password login are refused. + +## Firewall + +``` +Default: deny (incoming), allow (outgoing) +22/tcp OpenSSH ALLOW IN (v4+v6) +80/tcp ALLOW IN (v4+v6) +443/tcp ALLOW IN (v4+v6) +``` + +**Docker caveat:** ports published by Docker (`ports:` in a compose file) are inserted into iptables ahead of UFW and +are reachable from the internet even if UFW has no rule for them. Rule for this host: never publish a port other than +Caddy's 80/443; services talk to each other over Docker networks, and anything that must be reachable only locally is +published as `127.0.0.1::`. + +## Docker + +- Docker Engine 29.8.2, Compose v5.6.0. +- The `ubuntu` user is **not** in the `docker` group; use `sudo docker ...`. (Membership in `docker` is + root-equivalent, so it is deliberately not granted.) +- The Docker socket is not published anywhere; no TCP daemon listener. +- Networks: + - `coa-ingress` (bridge): Caddy and future Registry API/Relay-facing HTTP services. + - `coa-db` (`--internal`): PostgreSQL only; has no route to or from the outside. + +## Resource baseline (right after setup, Caddy running) + +- Load average ~0.6 shortly after boot, then idle. +- RAM: ~0.5 GiB used of 3.7 GiB (3.2 GiB available). +- Disk: 2.9 GB of 38 GB used. + +## Open items + +- Fill in region, plan/service ID, network limit from the OVH Control Panel. +- Find out what OVH backup/snapshot is actually enabled for this plan (see INFRASTRUCTURE.md, Backups). +- Decide on the public hostname/TLS strategy (no domain yet; Caddy serves plain HTTP on :80).