Add production release and VPS deploy artifacts (#123, #124)

This commit is contained in:
2026-11-09 22:03:54 +01:00
parent 3a849ddff0
commit b1767e5fbc
14 changed files with 526 additions and 6 deletions
+5 -1
View File
@@ -31,8 +31,12 @@ chesstrainer-*.tar
# Ignore ETS table backups # Ignore ETS table backups
/priv/static/backups/ /priv/static/backups/
# Ignore digested assets cache. # Ignore digested assets cache and generated digests.
/priv/static/cache_manifest.json /priv/static/cache_manifest.json
/priv/static/favicon-*.ico
/priv/static/fonts/*-*.woff2
/priv/static/images/*-*.svg
/priv/static/images/*.svg.gz
# In case you use Node.js/npm, you want to ignore these. # In case you use Node.js/npm, you want to ignore these.
npm-debug.log npm-debug.log
+3 -5
View File
@@ -148,11 +148,9 @@ if config_env() == :prod do
config :chesstrainer, ChesstrainerWeb.Endpoint, config :chesstrainer, ChesstrainerWeb.Endpoint,
url: [host: host, port: 443, scheme: "https"], url: [host: host, port: 443, scheme: "https"],
http: [ http: [
# Enable IPv6 and bind on all interfaces. # The release runs behind Caddy, so bind to loopback and let the proxy
# Set it to {0, 0, 0, 0, 0, 0, 0, 1} for local network only access. # handle public traffic.
# See the documentation on https://bandit.hexdocs.pm/Bandit.html#t:options/0 ip: {127, 0, 0, 1}
# for details about using IPv6 vs IPv4 and loopback vs public addresses.
ip: {0, 0, 0, 0, 0, 0, 0, 0}
], ],
secret_key_base: secret_key_base secret_key_base: secret_key_base
+15
View File
@@ -0,0 +1,15 @@
# Reference block for the shared Caddyfile.
#
# This file is not installed automatically. On the shared VPS, add this block
# to the existing Caddy config by hand, then validate and reload Caddy.
#
# The app listens on loopback only; Caddy is the public entry point.
innersquare.app {
encode zstd gzip
reverse_proxy 127.0.0.1:4100
}
www.innersquare.app {
redir https://innersquare.app{uri} permanent
}
+269
View File
@@ -0,0 +1,269 @@
# Production deployment
Phoenix release on the shared Ubuntu VPS, behind Caddy, with Postgres in Docker.
```text
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
`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
```text
/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`:
```sh
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`:
```sh
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:
```yaml
volumes:
- pgdata:/var/lib/postgresql
```
## First-time setup
Run as root or with sudo:
```sh
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.
```sh
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
image: postgres:18.0
```
For an immutable pin, replace it with the exact digest:
```yaml
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:
```sh
docker compose -f <UNIFIED_COMPOSE> pull chesstrainer-db
docker compose -f <UNIFIED_COMPOSE> up -d chesstrainer-db
```
Install the systemd unit:
```sh
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:
```caddy
innersquare.app {
encode zstd gzip
reverse_proxy 127.0.0.1:4100
}
www.innersquare.app {
redir https://innersquare.app{uri} permanent
}
```
Validate and reload:
```sh
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:
```sh
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:
```sh
sudo 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
Optional overrides:
```sh
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
```sh
sudo deploy/rollback
```
Or target a specific release:
```sh
sudo deploy/rollback 20261109120000
```
The script flips `current`, restarts the service, and checks `/health`.
## Logs and health
```sh
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:
```sh
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`.
+87
View File
@@ -0,0 +1,87 @@
#!/usr/bin/env bash
set -euo pipefail
# Activate a timestamped release on the VPS.
#
# Usage:
# sudo deploy/activate /tmp/chesstrainer-20261109.tar.gz
#
# Environment overrides:
# APP_USER, APP_ROOT, SERVICE, HEALTH_URL, KEEP_RELEASES, RELEASE_ID
if [[ "${EUID:-$(id -u)}" -ne 0 ]]; then
echo "activate: run with sudo" >&2
exit 1
fi
TARBALL="${1:-}"
if [[ -z "$TARBALL" || ! -f "$TARBALL" ]]; then
echo "usage: sudo $0 /path/to/chesstrainer-release.tar.gz" >&2
exit 1
fi
APP_USER="${APP_USER:-chesstrainer}"
APP_ROOT="${APP_ROOT:-/opt/chesstrainer}"
SERVICE="${SERVICE:-chesstrainer}"
HEALTH_URL="${HEALTH_URL:-http://127.0.0.1:4100/health}"
KEEP_RELEASES="${KEEP_RELEASES:-5}"
RELEASE_ID="${RELEASE_ID:-$(date -u +%Y%m%d%H%M%S)}"
if [[ ! "$RELEASE_ID" =~ ^[A-Za-z0-9._-]+$ ]]; then
echo "activate: RELEASE_ID may contain only letters, digits, dot, underscore and dash" >&2
exit 1
fi
if [[ ! "$KEEP_RELEASES" =~ ^[0-9]+$ ]] || [[ "$KEEP_RELEASES" -lt 1 ]]; then
echo "activate: KEEP_RELEASES must be a positive integer" >&2
exit 1
fi
health_check() {
curl --fail --silent --show-error \
--retry 10 --retry-delay 2 --retry-connrefused \
"$HEALTH_URL" >/dev/null
}
install -d -o "$APP_USER" -g "$APP_USER" "$APP_ROOT/releases"
PREVIOUS="$(readlink -f "$APP_ROOT/current" 2>/dev/null || true)"
RELEASE_DIR="$APP_ROOT/releases/$RELEASE_ID"
echo "activate: extracting $TARBALL -> $RELEASE_DIR"
install -d -o "$APP_USER" -g "$APP_USER" "$RELEASE_DIR"
tar -xzf "$TARBALL" -C "$RELEASE_DIR"
chown -R "$APP_USER:$APP_USER" "$RELEASE_DIR"
echo "activate: pointing current at $RELEASE_DIR"
ln -sfn "$RELEASE_DIR" "$APP_ROOT/current"
if systemctl restart "$SERVICE" && health_check; then
echo "activate: $RELEASE_ID is live"
if [[ "$KEEP_RELEASES" -gt 0 ]]; then
find "$APP_ROOT/releases" -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\n' \
| sort -nr \
| tail -n +"$((KEEP_RELEASES + 1))" \
| cut -d' ' -f2- \
| while read -r old_release; do
[[ -z "$old_release" ]] && continue
[[ "$old_release" == "$(readlink -f "$APP_ROOT/current")" ]] && continue
echo "activate: pruning $old_release"
rm -rf -- "$old_release"
done
fi
exit 0
fi
echo "activate: health check failed" >&2
if [[ -n "$PREVIOUS" && -d "$PREVIOUS" ]]; then
echo "activate: rolling back to $PREVIOUS" >&2
ln -sfn "$PREVIOUS" "$APP_ROOT/current"
systemctl restart "$SERVICE" || true
health_check || echo "activate: rollback health check also failed" >&2
fi
exit 1
+19
View File
@@ -0,0 +1,19 @@
[Unit]
Description=Inner Square Chess (Phoenix)
After=network.target docker.service
Wants=network.target
[Service]
Type=simple
User=chesstrainer
Group=chesstrainer
EnvironmentFile=/etc/chesstrainer/env
WorkingDirectory=/opt/chesstrainer/current
ExecStartPre=/opt/chesstrainer/current/bin/migrate
ExecStart=/opt/chesstrainer/current/bin/server
Restart=always
RestartSec=5
SyslogIdentifier=chesstrainer
[Install]
WantedBy=multi-user.target
+26
View File
@@ -0,0 +1,26 @@
# Reference only. Merge the service and volume below into the VPS's unified
# docker-compose.yml. Do not run this file as a separate Compose project.
#
# Pin the Postgres image directly in the unified file. Replace the tag with
# an exact digest if you want immutable image pinning:
# image: postgres:18.0@sha256:...
services:
chesstrainer-db:
container_name: chesstrainer-db
image: postgres:18.0
restart: unless-stopped
env_file: /etc/chesstrainer/postgres.env
ports:
- "127.0.0.1:5432:5432"
volumes:
- chesstrainer_pgdata:/var/lib/postgresql
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
interval: 5s
timeout: 5s
retries: 10
volumes:
chesstrainer_pgdata:
name: chesstrainer_pgdata
+58
View File
@@ -0,0 +1,58 @@
#!/usr/bin/env bash
set -euo pipefail
# Roll back to a previous release.
#
# Usage:
# sudo deploy/rollback # most recent previous release
# sudo deploy/rollback 20261109120000 # release id under /opt/chesstrainer/releases
# sudo deploy/rollback /opt/chesstrainer/releases/20261109120000
if [[ "${EUID:-$(id -u)}" -ne 0 ]]; then
echo "rollback: run with sudo" >&2
exit 1
fi
APP_ROOT="${APP_ROOT:-/opt/chesstrainer}"
SERVICE="${SERVICE:-chesstrainer}"
HEALTH_URL="${HEALTH_URL:-http://127.0.0.1:4100/health}"
health_check() {
curl --fail --silent --show-error \
--retry 10 --retry-delay 2 --retry-connrefused \
"$HEALTH_URL" >/dev/null
}
CURRENT="$(readlink -f "$APP_ROOT/current" 2>/dev/null || true)"
if [[ $# -gt 0 ]]; then
case "$1" in
/*) TARGET="$1" ;;
*) TARGET="$APP_ROOT/releases/$1" ;;
esac
else
TARGET="$(
find "$APP_ROOT/releases" -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\n' \
| sort -nr \
| cut -d' ' -f2- \
| while read -r release; do
if [[ "$release" != "$CURRENT" ]]; then
echo "$release"
break
fi
done
)"
fi
if [[ -z "$TARGET" || ! -d "$TARGET" ]]; then
echo "rollback: no previous release found" >&2
exit 1
fi
echo "rollback: pointing current at $TARGET"
ln -sfn "$TARGET" "$APP_ROOT/current"
systemctl restart "$SERVICE"
health_check
echo "rollback: $TARGET is live"
+30
View File
@@ -0,0 +1,30 @@
defmodule Chesstrainer.Release do
@moduledoc """
Used for executing DB release tasks when run in production without Mix
installed.
"""
@app :chesstrainer
def migrate do
load_app()
for repo <- repos() do
{:ok, _, _} = Ecto.Migrator.with_repo(repo, &Ecto.Migrator.run(&1, :up, all: true))
end
end
def rollback(repo, version) do
load_app()
{:ok, _, _} = Ecto.Migrator.with_repo(repo, &Ecto.Migrator.run(&1, :down, to: version))
end
defp repos do
Application.fetch_env!(@app, :ecto_repos)
end
defp load_app do
# Many platforms require SSL when connecting to the database
Application.ensure_all_started(:ssl)
Application.ensure_loaded(@app)
end
end
+1
View File
@@ -91,6 +91,7 @@ defmodule Chesstrainer.MixProject do
"assets.setup": ["tailwind.install --if-missing", "esbuild.install --if-missing"], "assets.setup": ["tailwind.install --if-missing", "esbuild.install --if-missing"],
"assets.build": ["compile", "tailwind chesstrainer", "esbuild chesstrainer"], "assets.build": ["compile", "tailwind chesstrainer", "esbuild chesstrainer"],
"assets.deploy": [ "assets.deploy": [
"compile",
"tailwind chesstrainer --minify", "tailwind chesstrainer --minify",
"esbuild chesstrainer --minify", "esbuild chesstrainer --minify",
"phx.digest" "phx.digest"
+5
View File
@@ -0,0 +1,5 @@
#!/bin/sh
set -eu
cd -P -- "$(dirname -- "$0")"
exec ./chesstrainer eval Chesstrainer.Release.migrate
+1
View File
@@ -0,0 +1 @@
call "%~dp0\chesstrainer" eval Chesstrainer.Release.migrate
+5
View File
@@ -0,0 +1,5 @@
#!/bin/sh
set -eu
cd -P -- "$(dirname -- "$0")"
PHX_SERVER=true exec ./chesstrainer start
+2
View File
@@ -0,0 +1,2 @@
set PHX_SERVER=true
call "%~dp0\chesstrainer" start