Document VPS provisioning and guard the service before first release (#125)

This commit is contained in:
2026-11-09 22:19:20 +01:00
parent b1767e5fbc
commit 4c39f231f1
2 changed files with 176 additions and 33 deletions
+175 -33
View File
@@ -18,14 +18,56 @@ Internet
| Erlang | 28.5 | | Erlang | 28.5 |
| Elixir | 1.19.5-otp-28 | | Elixir | 1.19.5-otp-28 |
| Rust | 1.98.1 | | Rust | 1.98.1 |
| Postgres | `postgres:18.6`, pinned directly in the unified compose | | Postgres | `postgres:18.0`, pinned directly in the unified compose |
| Caddy | 2.11.9 | | Caddy | 2.11.9 |
| Docker | 29.9.3 | | Docker | 29.9.3 |
| Docker Compose | v5.7.0 | | Docker Compose | v5.7.0 |
| GitHub runner | `ubuntu-24.04` |
The release ships its own ERTS. The host needs the runtime libraries for the The release ships its own ERTS. The host needs the runtime libraries for the
Rust NIF (`libstdc++6`), OpenSSL, and CA certificates. Rust NIF (`libstdc++6`), OpenSSL, and CA certificates.
## Host prerequisites
A new Ubuntu 24.04 VPS needs:
- Docker Engine and the Compose plugin
- Caddy
- `curl`, `ca-certificates`, `libstdc++6`, `openssl`
- DNS and TLS for the domain
- A non-root deploy user with SSH access
Install the host libraries:
```sh
sudo apt update
sudo apt install -y curl ca-certificates libstdc++6 openssl
```
Install Docker and Caddy from their official repositories. The Caddy install
commands already used for the static site are in `deploy/static/README.md`.
Firewall:
```sh
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
```
Do **not** open `4100` or `5432`. Phoenix binds to loopback, and Postgres is
published only on `127.0.0.1`.
DNS:
- `A`/`AAAA` for `innersquare.app` and `www` point at the VPS.
- Do not remove the existing mail records:
- root MX records for `support@innersquare.app`
- SES DKIM CNAMEs
- the `mail.innersquare.app` custom MAIL FROM MX/TXT records
- DMARC at `_dmarc.innersquare.app`
## Shared-host choices ## Shared-host choices
- **Port 4100** is used for Phoenix because another BEAM process already owns - **Port 4100** is used for Phoenix because another BEAM process already owns
@@ -45,7 +87,8 @@ Rust NIF (`libstdc++6`), OpenSSL, and CA certificates.
├── releases/ ├── releases/
│ ├── 20261109120000/ │ ├── 20261109120000/
│ └── 20261109153000/ │ └── 20261109153000/
└── current -> releases/20261109153000 ├── current -> releases/20261109153000
└── src/ # optional checkout of this repo / deploy scripts
``` ```
`/etc/chesstrainer/env` is the application environment file, owned by `/etc/chesstrainer/env` is the application environment file, owned by
@@ -57,6 +100,19 @@ also `root:root` and `0600`.
The app runs as the dedicated `chesstrainer` system user. It must own The app runs as the dedicated `chesstrainer` system user. It must own
`/opt/chesstrainer` so it can write `priv/static/backups`. `/opt/chesstrainer` so it can write `priv/static/backups`.
## Copy the deploy artifacts
Run these commands from a checkout of this repo on the VPS, or copy the
`deploy/` directory to `/opt/chesstrainer/src/deploy`.
```sh
sudo install -d -o root -g root /opt/chesstrainer/src/deploy
sudo cp -a deploy/. /opt/chesstrainer/src/deploy/
```
If you prefer to keep the checkout elsewhere, use that path in the commands
below.
## Application env file ## Application env file
`/etc/chesstrainer/env`: `/etc/chesstrainer/env`:
@@ -76,8 +132,8 @@ SES_REGION=eu-north-1
SES_ACCESS_KEY_ID=AKIA... SES_ACCESS_KEY_ID=AKIA...
SES_SECRET_ACCESS_KEY=... SES_SECRET_ACCESS_KEY=...
MATOMO_URL=https://analytics.innersquare.app/ MATOMO_URL=https://analytics.owenrees.eu/
MATOMO_SITE_ID=1 MATOMO_SITE_ID=6
# Optional: # Optional:
# TABLEBASE_PATH=/path/to/syzygy # TABLEBASE_PATH=/path/to/syzygy
@@ -87,6 +143,13 @@ MATOMO_SITE_ID=1
The production endpoint binds to `127.0.0.1` only. Caddy is the public The production endpoint binds to `127.0.0.1` only. Caddy is the public
entry point. entry point.
Generate the two secrets:
```sh
openssl rand -base64 64 # SECRET_KEY_BASE
openssl rand -hex 32 # Postgres password
```
## Postgres env file ## Postgres env file
`/etc/chesstrainer/postgres.env`: `/etc/chesstrainer/postgres.env`:
@@ -102,7 +165,7 @@ Compose volume mounts the parent:
```yaml ```yaml
volumes: volumes:
- pgdata:/var/lib/postgresql - chesstrainer_pgdata:/var/lib/postgresql
``` ```
## First-time setup ## First-time setup
@@ -125,16 +188,16 @@ install -m 600 /dev/null /etc/chesstrainer/postgres.env
chown root:root /etc/chesstrainer/env /etc/chesstrainer/postgres.env chown root:root /etc/chesstrainer/env /etc/chesstrainer/postgres.env
``` ```
Edit both files with `sudoedit` and set the generated secrets and
`DATABASE_URL`.
## Unified Compose: add Postgres
Add the `chesstrainer-db` service and `chesstrainer_pgdata` volume from Add the `chesstrainer-db` service and `chesstrainer_pgdata` volume from
`deploy/postgres.compose.yml` to the VPS's existing unified `deploy/postgres.compose.yml` to the VPS's existing unified
`docker-compose.yml`. Do not run the reference file as a separate project. `docker-compose.yml`. Do not run the reference file as a separate project.
```sh The image is pinned directly in the unified compose:
docker compose -f <UNIFIED_COMPOSE> up -d chesstrainer-db
docker compose -f <UNIFIED_COMPOSE> ps chesstrainer-db
```
The Postgres image is pinned directly in the unified compose:
```yaml ```yaml
image: postgres:18.0 image: postgres:18.0
@@ -146,27 +209,50 @@ For an immutable pin, replace it with the exact digest:
image: postgres:18.0@sha256:... image: postgres:18.0@sha256:...
``` ```
There is no `POSTGRES_IMAGE` environment variable involved. To change the There is no `POSTGRES_IMAGE` environment variable involved.
Postgres version, edit the `image:` line in the unified compose, then:
Because `postgres.env` is root-owned `0600`, run Compose with `sudo`:
```sh ```sh
docker compose -f <UNIFIED_COMPOSE> pull chesstrainer-db sudo docker compose -f <UNIFIED_COMPOSE> config >/dev/null
docker compose -f <UNIFIED_COMPOSE> up -d chesstrainer-db sudo docker compose -f <UNIFIED_COMPOSE> up -d chesstrainer-db
sudo docker compose -f <UNIFIED_COMPOSE> ps chesstrainer-db
sudo docker compose -f <UNIFIED_COMPOSE> logs --tail=50 chesstrainer-db
``` ```
Install the systemd unit: Verify the database:
```sh ```sh
install -o root -g root -m 644 deploy/chesstrainer.service /etc/systemd/system/chesstrainer.service sudo docker compose -f <UNIFIED_COMPOSE> exec -T chesstrainer-db \
systemctl daemon-reload psql -U chesstrainer -d chesstrainer_prod -c 'select 1;'
systemctl enable chesstrainer
``` ```
Do not start the service until a release is in `/opt/chesstrainer/current`. To change the Postgres version:
```sh
# edit the image: line in the unified compose
sudo docker compose -f <UNIFIED_COMPOSE> pull chesstrainer-db
sudo docker compose -f <UNIFIED_COMPOSE> up -d chesstrainer-db
```
## systemd unit
From the deploy artifact copy:
```sh
sudo install -o root -g root -m 644 /opt/chesstrainer/src/deploy/chesstrainer.service \
/etc/systemd/system/chesstrainer.service
sudo systemctl daemon-reload
sudo systemctl enable chesstrainer
```
The unit includes `ConditionPathExists=/opt/chesstrainer/current/bin/server`, so
it is safe to enable before the first release. systemd skips it until a release
is in place.
## Caddy ## Caddy
This VPS uses a single `/etc/caddy/Caddyfile` with no imports. Add the block On the current VPS the Caddyfile is a single file with no imports. Add the block
from `deploy/Caddyfile` by hand: from `deploy/Caddyfile` by hand:
```caddy ```caddy
@@ -180,11 +266,16 @@ www.innersquare.app {
} }
``` ```
If a new VPS uses imports, put the block in its own site file instead.
Do **not** switch Caddy until a release is running and verified on
`127.0.0.1:4100`. Before that, keep the static coming-soon site live.
Validate and reload: Validate and reload:
```sh ```sh
caddy validate --config /etc/caddy/Caddyfile sudo caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy sudo systemctl reload caddy
``` ```
Do not let a deploy overwrite the shared Caddyfile. Do not let a deploy overwrite the shared Caddyfile.
@@ -206,12 +297,18 @@ tar -czf chesstrainer-release.tar.gz -C _build/prod/rel/chesstrainer .
`mix assets.deploy` runs `compile` first so the generated LiveView colocated `mix assets.deploy` runs `compile` first so the generated LiveView colocated
CSS exists. CSS exists.
## Deploying a release ## First deploy and Caddy switch
Copy the tarball to the VPS, then: Upload the tarball:
```sh ```sh
sudo deploy/activate /tmp/chesstrainer-release.tar.gz scp chesstrainer-release.tar.gz <VPS_USER>@<VPS_HOST>:/tmp/
```
On the VPS:
```sh
sudo /opt/chesstrainer/src/deploy/activate /tmp/chesstrainer-release.tar.gz
``` ```
The script: The script:
@@ -225,25 +322,49 @@ The script:
7. Rolls back to the previous release on failure 7. Rolls back to the previous release on failure
8. Prunes old releases, keeping 5 by default 8. Prunes old releases, keeping 5 by default
Verify locally before touching Caddy:
```sh
curl -i http://127.0.0.1:4100/health
curl -i http://127.0.0.1:4100/
sudo journalctl -u chesstrainer -n 100 --no-pager
```
Then add the Caddy block and reload. Verify publicly:
```sh
curl -I https://innersquare.app/
curl -I https://innersquare.app/privacy
curl -I https://innersquare.app/terms-conditions
```
## Subsequent deploys
```sh
scp chesstrainer-release.tar.gz <VPS_USER>@<VPS_HOST>:/tmp/
ssh <VPS_USER>@<VPS_HOST>
sudo /opt/chesstrainer/src/deploy/activate /tmp/chesstrainer-release.tar.gz
```
Optional overrides: Optional overrides:
```sh ```sh
RELEASE_ID=20261109120000 \ RELEASE_ID=20261109120000 \
HEALTH_URL=http://127.0.0.1:4100/health \ HEALTH_URL=http://127.0.0.1:4100/health \
KEEP_RELEASES=5 \ KEEP_RELEASES=5 \
sudo -E deploy/activate /tmp/chesstrainer-release.tar.gz sudo -E /opt/chesstrainer/src/deploy/activate /tmp/chesstrainer-release.tar.gz
``` ```
## Rollback ## Rollback
```sh ```sh
sudo deploy/rollback sudo /opt/chesstrainer/src/deploy/rollback
``` ```
Or target a specific release: Or target a specific release:
```sh ```sh
sudo deploy/rollback 20261109120000 sudo /opt/chesstrainer/src/deploy/rollback 20261109120000
``` ```
The script flips `current`, restarts the service, and checks `/health`. The script flips `current`, restarts the service, and checks `/health`.
@@ -251,8 +372,8 @@ The script flips `current`, restarts the service, and checks `/health`.
## Logs and health ## Logs and health
```sh ```sh
systemctl status chesstrainer sudo systemctl status chesstrainer
journalctl -u chesstrainer -n 100 --no-pager sudo journalctl -u chesstrainer -n 100 --no-pager
curl -i http://127.0.0.1:4100/health curl -i http://127.0.0.1:4100/health
``` ```
@@ -261,9 +382,30 @@ curl -i http://127.0.0.1:4100/health
Take a logical backup of the production database: Take a logical backup of the production database:
```sh ```sh
docker compose -f <UNIFIED_COMPOSE> \ sudo docker compose -f <UNIFIED_COMPOSE> \
exec -T chesstrainer-db pg_dump -U chesstrainer chesstrainer_prod \ exec -T chesstrainer-db pg_dump -U chesstrainer chesstrainer_prod \
| gzip > /var/backups/chesstrainer-$(date -u +%Y%m%d%H%M%S).sql.gz | gzip > /var/backups/chesstrainer-$(date -u +%Y%m%d%H%M%S).sql.gz
``` ```
Keep the backup directory outside `/opt/chesstrainer/releases`. Example nightly entry in root's crontab (`sudo crontab -e`):
```cron
15 3 * * * docker compose -f /home/owen/docker-compose.yml exec -T chesstrainer-db pg_dump -U chesstrainer chesstrainer_prod | gzip > /var/backups/chesstrainer-$(date +\%Y\%m\%d).sql.gz
```
Keep `/var/backups` outside `/opt/chesstrainer/releases` and copy backups off
the VPS regularly.
## New VPS checklist
1. Ubuntu 24.04, DNS pointed at the VPS, firewall allows 22/80/443.
2. Docker, Compose, Caddy, and runtime libraries installed.
3. `chesstrainer` user, `/opt/chesstrainer` layout, root-owned env files.
4. `chesstrainer-db` merged into the unified compose and healthy.
5. systemd unit installed and enabled; `ConditionPathExists` keeps it skipped
until a release exists.
6. Release built on a matching Ubuntu runner and activated.
7. `/health` and `/` verified on `127.0.0.1:4100`.
8. Caddy block added, validated, reloaded.
9. Public `/`, `/privacy`, `/terms-conditions`, and `/health` verified.
10. Backups scheduled and tested.
+1
View File
@@ -2,6 +2,7 @@
Description=Inner Square Chess (Phoenix) Description=Inner Square Chess (Phoenix)
After=network.target docker.service After=network.target docker.service
Wants=network.target Wants=network.target
ConditionPathExists=/opt/chesstrainer/current/bin/server
[Service] [Service]
Type=simple Type=simple