Skip to content

Updating

Jump to bottom
Doug edited this page Jun 24, 2026 · 6 revisions

Updating

How to move a running instance to a newer version safely. Migrations run automatically on boot; the thing that protects you is the pre-update database snapshot — keep it.

Knowing an update exists

Admins see a version badge on the System Admin page: it shows the running APP_VERSION and a "update available → x.y.z" tag when a newer GitHub release exists (GET /api/admin/update-check compares against the latest release).

Path A — published image (recommended for self-host)

If you run the published image via the self-host overlay (see the README's Self-hosting section), upgrading is one script:

# pin the target release in .env (or leave APP_VERSION unset to track :latest)
echo 'APP_VERSION=1.1.0' >> .env

./gdx_dispatch/docker/update.sh
# or pin inline:  APP_VERSION=1.1.0 ./gdx_dispatch/docker/update.sh

update.sh does, in order:

  1. Snapshot the database → backups/gdx-pre-update-<ts>.sql.gz.
  2. Pull the new images.
  3. Start app alone first — only the app runs migrations (workers skip them), so exactly one container migrates, no race.
  4. Wait for /health (up to HEALTH_TIMEOUT, default 600s — a real DDL migration can take minutes).
  5. Once healthy, start the workers.

If health doesn't come up, the script tells you whether the app is still migrating (don't roll back yet — watch the logs) or has crashed (safe to roll back, with the exact restore commands printed).

Rolling back

# 1. pin the previous release in .env:  APP_VERSION=<old>
# 2. restore the pre-update snapshot:
gunzip -c backups/gdx-pre-update-<ts>.sql.gz | \
  docker compose -p gdx --env-file ./.env \
    -f gdx_dispatch/docker/docker-compose.yml \
    -f gdx_dispatch/docker/docker-compose.selfhost.yml exec -T db psql -U gdx gdx
# 3. bring it back up:
docker compose -p gdx ... up -d

Path B — build from source

If you run the plain dev compose (up --build, no published image):

docker compose -f gdx_dispatch/docker/docker-compose.yml exec -T db \
  pg_dump -U gdx gdx | gzip > "pre-update_$(date +%F).sql.gz"   # snapshot first!

git pull
docker compose -f gdx_dispatch/docker/docker-compose.yml up -d --build

The app container re-runs migrations on boot.

Notes

  • Always snapshot first. Path A does it for you; Path B you do manually (above).
  • Updating plugins is separate from updating the core app — see Using Plugins.
  • Publishing releases (so Path A has images to pull) is a maintainer step: push a vX.Y.Z tag → CI builds, smoke-tests, and pushes the image to GHCR.

See also

Clone this wiki locally