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/AAAAforinnersquare.appandwwwpoint at the VPS.- Do not remove the existing mail records:
- root MX records for
support@innersquare.app - SES DKIM CNAMEs
- the
mail.innersquare.appcustom MAIL FROM MX/TXT records - DMARC at
_dmarc.innersquare.app
- root MX records for
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
└── 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:
- 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
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
/health returns JSON with status, db, tablebase, and process.
It returns 200 for ok/degraded and 503 for down. A missing local tablebase
reports degraded but still 200 because Lichess fallback is available.
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
- Ubuntu 24.04, DNS pointed at the VPS, firewall allows 22/80/443.
- Docker, Compose, Caddy, and runtime libraries installed.
chesstraineruser,/opt/chesstrainerlayout, root-owned env files.chesstrainer-dbmerged into the unified compose and healthy.- systemd unit installed and enabled;
ConditionPathExistskeeps it skipped until a release exists. - Release built on a matching Ubuntu runner and activated.
/healthand/verified on127.0.0.1:4100.- Caddy block added, validated, reloaded.
- Public
/,/privacy,/terms-conditions, and/healthverified. - Backups scheduled and tested.