From b1767e5fbc9fd8c0bd99935b080f275f3cbd6c4a Mon Sep 17 00:00:00 2001 From: Owen Date: Mon, 9 Nov 2026 22:03:54 +0100 Subject: [PATCH] Add production release and VPS deploy artifacts (#123, #124) --- .gitignore | 6 +- config/runtime.exs | 8 +- deploy/Caddyfile | 15 ++ deploy/README.md | 269 +++++++++++++++++++++++++++++++++++ deploy/activate | 87 +++++++++++ deploy/chesstrainer.service | 19 +++ deploy/postgres.compose.yml | 26 ++++ deploy/rollback | 58 ++++++++ lib/chesstrainer/release.ex | 30 ++++ mix.exs | 1 + rel/overlays/bin/migrate | 5 + rel/overlays/bin/migrate.bat | 1 + rel/overlays/bin/server | 5 + rel/overlays/bin/server.bat | 2 + 14 files changed, 526 insertions(+), 6 deletions(-) create mode 100644 deploy/Caddyfile create mode 100644 deploy/README.md create mode 100755 deploy/activate create mode 100644 deploy/chesstrainer.service create mode 100644 deploy/postgres.compose.yml create mode 100755 deploy/rollback create mode 100644 lib/chesstrainer/release.ex create mode 100755 rel/overlays/bin/migrate create mode 100755 rel/overlays/bin/migrate.bat create mode 100755 rel/overlays/bin/server create mode 100755 rel/overlays/bin/server.bat diff --git a/.gitignore b/.gitignore index 39d3677..be5f9b2 100644 --- a/.gitignore +++ b/.gitignore @@ -31,8 +31,12 @@ chesstrainer-*.tar # Ignore ETS table backups /priv/static/backups/ -# Ignore digested assets cache. +# Ignore digested assets cache and generated digests. /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. npm-debug.log diff --git a/config/runtime.exs b/config/runtime.exs index 464887c..1462895 100644 --- a/config/runtime.exs +++ b/config/runtime.exs @@ -148,11 +148,9 @@ if config_env() == :prod do config :chesstrainer, ChesstrainerWeb.Endpoint, url: [host: host, port: 443, scheme: "https"], http: [ - # Enable IPv6 and bind on all interfaces. - # Set it to {0, 0, 0, 0, 0, 0, 0, 1} for local network only access. - # See the documentation on https://bandit.hexdocs.pm/Bandit.html#t:options/0 - # for details about using IPv6 vs IPv4 and loopback vs public addresses. - ip: {0, 0, 0, 0, 0, 0, 0, 0} + # The release runs behind Caddy, so bind to loopback and let the proxy + # handle public traffic. + ip: {127, 0, 0, 1} ], secret_key_base: secret_key_base diff --git a/deploy/Caddyfile b/deploy/Caddyfile new file mode 100644 index 0000000..2d0ff03 --- /dev/null +++ b/deploy/Caddyfile @@ -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 +} diff --git a/deploy/README.md b/deploy/README.md new file mode 100644 index 0000000..f8c6860 --- /dev/null +++ b/deploy/README.md @@ -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 up -d chesstrainer-db +docker compose -f 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 pull chesstrainer-db +docker compose -f 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/` +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 \ + 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`. diff --git a/deploy/activate b/deploy/activate new file mode 100755 index 0000000..ef71ff0 --- /dev/null +++ b/deploy/activate @@ -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 diff --git a/deploy/chesstrainer.service b/deploy/chesstrainer.service new file mode 100644 index 0000000..173be2a --- /dev/null +++ b/deploy/chesstrainer.service @@ -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 diff --git a/deploy/postgres.compose.yml b/deploy/postgres.compose.yml new file mode 100644 index 0000000..c82f481 --- /dev/null +++ b/deploy/postgres.compose.yml @@ -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 diff --git a/deploy/rollback b/deploy/rollback new file mode 100755 index 0000000..ab8b10d --- /dev/null +++ b/deploy/rollback @@ -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" diff --git a/lib/chesstrainer/release.ex b/lib/chesstrainer/release.ex new file mode 100644 index 0000000..ee96518 --- /dev/null +++ b/lib/chesstrainer/release.ex @@ -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 diff --git a/mix.exs b/mix.exs index 434aff8..b5f6379 100644 --- a/mix.exs +++ b/mix.exs @@ -91,6 +91,7 @@ defmodule Chesstrainer.MixProject do "assets.setup": ["tailwind.install --if-missing", "esbuild.install --if-missing"], "assets.build": ["compile", "tailwind chesstrainer", "esbuild chesstrainer"], "assets.deploy": [ + "compile", "tailwind chesstrainer --minify", "esbuild chesstrainer --minify", "phx.digest" diff --git a/rel/overlays/bin/migrate b/rel/overlays/bin/migrate new file mode 100755 index 0000000..133ca33 --- /dev/null +++ b/rel/overlays/bin/migrate @@ -0,0 +1,5 @@ +#!/bin/sh +set -eu + +cd -P -- "$(dirname -- "$0")" +exec ./chesstrainer eval Chesstrainer.Release.migrate diff --git a/rel/overlays/bin/migrate.bat b/rel/overlays/bin/migrate.bat new file mode 100755 index 0000000..3f7ef47 --- /dev/null +++ b/rel/overlays/bin/migrate.bat @@ -0,0 +1 @@ +call "%~dp0\chesstrainer" eval Chesstrainer.Release.migrate diff --git a/rel/overlays/bin/server b/rel/overlays/bin/server new file mode 100755 index 0000000..92510e1 --- /dev/null +++ b/rel/overlays/bin/server @@ -0,0 +1,5 @@ +#!/bin/sh +set -eu + +cd -P -- "$(dirname -- "$0")" +PHX_SERVER=true exec ./chesstrainer start diff --git a/rel/overlays/bin/server.bat b/rel/overlays/bin/server.bat new file mode 100755 index 0000000..3b25ce5 --- /dev/null +++ b/rel/overlays/bin/server.bat @@ -0,0 +1,2 @@ +set PHX_SERVER=true +call "%~dp0\chesstrainer" start