Files
chess-endgame-trainer/deploy

Production deployment

Phoenix release on the shared Ubuntu VPS, behind Caddy, with Postgres in Docker.

Internet
  └─ Caddy :443
       └─ Phoenix release 127.0.0.1:4100
            └─ Postgres 127.0.0.1:5432

Pinned versions

Thing Version
OS Ubuntu 24.04.5 LTS, x86_64
glibc 2.39
Erlang 28.5
Elixir 1.19.5-otp-28
Rust 1.98.1
Postgres postgres:18.0, pinned directly in the unified compose
Caddy 2.11.9
Docker 29.9.3
Docker Compose v5.7.0
GitHub runner ubuntu-24.04

The release ships its own ERTS. The host needs the runtime libraries for the 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:

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:

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

  • Port 4100 is used for Phoenix because another BEAM process already owns 4000 on this VPS.
  • Postgres runs as chesstrainer-db in the VPS's unified docker-compose.yml on 127.0.0.1:5432; that port is free. The image version is pinned directly in that file.
  • Caddy is shared and managed manually. This repo ships a reference block in deploy/Caddyfile; it is never installed automatically.
  • The Postgres volume is named chesstrainer_pgdata, so it cannot collide with other Docker projects.

Directory layout

/opt/chesstrainer/
├── releases/
│   ├── 20261109120000/
│   └── 20261109153000/
├── current -> releases/20261109153000
└── src/                 # optional checkout of this repo / deploy scripts

/etc/chesstrainer/env is the application environment file, owned by root:root with mode 0600.

/etc/chesstrainer/postgres.env holds the Postgres container credentials, also root:root and 0600.

The app runs as the dedicated chesstrainer system user. It must own /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.

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

/etc/chesstrainer/env:

SECRET_KEY_BASE=...
DATABASE_URL=ecto://chesstrainer:...@127.0.0.1:5432/chesstrainer_prod
PHX_HOST=innersquare.app
PORT=4100
POOL_SIZE=10
TRUST_FORWARDED_FOR=true

PRELAUNCH=true
MAILING_LIST_ENABLED=false

SES_REGION=eu-north-1
SES_ACCESS_KEY_ID=AKIA...
SES_SECRET_ACCESS_KEY=...

MATOMO_URL=https://analytics.owenrees.eu/
MATOMO_SITE_ID=6

# Optional:
# TABLEBASE_PATH=/path/to/syzygy
# RELEASE_COOKIE=...

The production endpoint binds to 127.0.0.1 only. Caddy is the public entry point.

Generate the two secrets:

openssl rand -base64 64   # SECRET_KEY_BASE
openssl rand -hex 32      # Postgres password

Postgres env file

/etc/chesstrainer/postgres.env:

POSTGRES_USER=chesstrainer
POSTGRES_PASSWORD=...
POSTGRES_DB=chesstrainer_prod

Postgres 18 stores data under /var/lib/postgresql/18/docker, so the Compose volume mounts the parent:

volumes:
  - chesstrainer_pgdata:/var/lib/postgresql

First-time setup

Run as root or with sudo:

useradd --system --user-group \
  --home-dir /opt/chesstrainer \
  --create-home \
  --shell /usr/sbin/nologin \
  chesstrainer

install -d -o chesstrainer -g chesstrainer /opt/chesstrainer/releases
install -d -o chesstrainer -g chesstrainer /opt/chesstrainer/src

install -d -m 755 /etc/chesstrainer
install -m 600 /dev/null /etc/chesstrainer/env
install -m 600 /dev/null /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 deploy/postgres.compose.yml to the VPS's existing unified docker-compose.yml. Do not run the reference file as a separate project.

The image is pinned directly in the unified compose:

image: postgres:18.0

For an immutable pin, replace it with the exact digest:

image: postgres:18.0@sha256:...

There is no POSTGRES_IMAGE environment variable involved.

Because postgres.env is root-owned 0600, run Compose with sudo:

sudo docker compose -f <UNIFIED_COMPOSE> config >/dev/null
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

Verify the database:

sudo docker compose -f <UNIFIED_COMPOSE> exec -T chesstrainer-db \
  psql -U chesstrainer -d chesstrainer_prod -c 'select 1;'

To change the Postgres version:

# 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:

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

On the current VPS the Caddyfile is a single file with no imports. Add the block from deploy/Caddyfile by hand:

innersquare.app {
    encode zstd gzip
    reverse_proxy 127.0.0.1:4100
}

www.innersquare.app {
    redir https://innersquare.app{uri} permanent
}

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:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Do not let a deploy overwrite the shared Caddyfile.

Building a release

Build on a machine matching Ubuntu 24.04 / glibc 2.39, or let CI do it. The release tarball is the contents of the release directory:

export MIX_ENV=prod
mix deps.get --only prod
mix assets.deploy
mix release

tar -czf chesstrainer-release.tar.gz -C _build/prod/rel/chesstrainer .

mix assets.deploy runs compile first so the generated LiveView colocated CSS exists.

First deploy and Caddy switch

Upload the tarball:

scp chesstrainer-release.tar.gz <VPS_USER>@<VPS_HOST>:/tmp/

On the VPS:

sudo /opt/chesstrainer/src/deploy/activate /tmp/chesstrainer-release.tar.gz

The script:

  1. Extracts into /opt/chesstrainer/releases/<timestamp>
  2. Fixes ownership
  3. Flips /opt/chesstrainer/current
  4. Restarts chesstrainer.service
  5. Migrations run via ExecStartPre
  6. Polls /health
  7. Rolls back to the previous release on failure
  8. Prunes old releases, keeping 5 by default

Verify locally before touching Caddy:

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:

curl -I https://innersquare.app/
curl -I https://innersquare.app/privacy
curl -I https://innersquare.app/terms-conditions

Subsequent deploys

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:

RELEASE_ID=20261109120000 \
HEALTH_URL=http://127.0.0.1:4100/health \
KEEP_RELEASES=5 \
sudo -E /opt/chesstrainer/src/deploy/activate /tmp/chesstrainer-release.tar.gz

Rollback

sudo /opt/chesstrainer/src/deploy/rollback

Or target a specific release:

sudo /opt/chesstrainer/src/deploy/rollback 20261109120000

The script flips current, restarts the service, and checks /health.

Logs and health

sudo systemctl status chesstrainer
sudo journalctl -u chesstrainer -n 100 --no-pager
curl -i http://127.0.0.1:4100/health

Backups

Take a logical backup of the production database:

sudo docker compose -f <UNIFIED_COMPOSE> \
  exec -T chesstrainer-db pg_dump -U chesstrainer chesstrainer_prod \
  | gzip > /var/backups/chesstrainer-$(date -u +%Y%m%d%H%M%S).sql.gz

Example nightly entry in root's crontab (sudo crontab -e):

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.