6.2 KiB
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.6, pinned directly in the unified compose |
| Caddy | 2.11.9 |
| Docker | 29.9.3 |
| Docker Compose | v5.7.0 |
The release ships its own ERTS. The host needs the runtime libraries for the
Rust NIF (libstdc++6), OpenSSL, and CA certificates.
Shared-host choices
- Port 4100 is used for Phoenix because another BEAM process already owns
4000on this VPS. - Postgres runs as
chesstrainer-dbin the VPS's unifieddocker-compose.ymlon127.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
/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.
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.innersquare.app/
MATOMO_SITE_ID=1
# Optional:
# TABLEBASE_PATH=/path/to/syzygy
# RELEASE_COOKIE=...
The production endpoint binds to 127.0.0.1 only. Caddy is the public
entry point.
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:
- 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
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.
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:
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. To change the
Postgres version, edit the image: line in the unified compose, then:
docker compose -f <UNIFIED_COMPOSE> pull chesstrainer-db
docker compose -f <UNIFIED_COMPOSE> up -d chesstrainer-db
Install the systemd unit:
install -o root -g root -m 644 deploy/chesstrainer.service /etc/systemd/system/chesstrainer.service
systemctl daemon-reload
systemctl enable chesstrainer
Do not start the service until a release is in /opt/chesstrainer/current.
Caddy
This VPS uses a single /etc/caddy/Caddyfile 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
}
Validate and reload:
caddy validate --config /etc/caddy/Caddyfile
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.
Deploying a release
Copy the tarball to the VPS, then:
sudo deploy/activate /tmp/chesstrainer-release.tar.gz
The script:
- Extracts into
/opt/chesstrainer/releases/<timestamp> - Fixes ownership
- Flips
/opt/chesstrainer/current - Restarts
chesstrainer.service - Migrations run via
ExecStartPre - Polls
/health - Rolls back to the previous release on failure
- Prunes old releases, keeping 5 by default
Optional overrides:
RELEASE_ID=20261109120000 \
HEALTH_URL=http://127.0.0.1:4100/health \
KEEP_RELEASES=5 \
sudo -E deploy/activate /tmp/chesstrainer-release.tar.gz
Rollback
sudo deploy/rollback
Or target a specific release:
sudo deploy/rollback 20261109120000
The script flips current, restarts the service, and checks /health.
Logs and health
systemctl status chesstrainer
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:
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
Keep the backup directory outside /opt/chesstrainer/releases.