Upgrading

An upgrade is a new image tag. Database migrations run automatically when the new version starts, before it serves any traffic.

Upgrade

Run these in the directory that holds docker-compose.yml.

1. Back up the database. See Backups.

   docker compose exec -T postgres pg_dump -U jangka -Fc jangka > jangka-before-upgrade.dump

2. Set the new version in .env. A separate worker reads the same variable. Use an exact version, not latest, so you always know what's running. Read the release notes first: they list new variables and any manual steps.

   JANGKA_VERSION=1.0.0-rc.1

3. Pull and restart.

   docker compose pull
   docker compose up -d

4. Check that it's healthy.

   docker compose ps
   docker compose logs app

   The app is healthy once migrations are done and it's serving traffic.

If a migration fails

The app logs migrations failed with the cause and exits without serving traffic. All pending migrations run in one transaction, so a failure leaves the database as it was before the upgrade. See Troubleshooting.

To go back to the previous version, set its JANGKA_VERSION again, restore the backup from step 1, and start the app:

docker compose stop app
docker compose exec -T postgres pg_restore -U jangka -d jangka --clean --if-exists < jangka-before-upgrade.dump
docker compose up -d

Postgres

The compose file pins Postgres to major version 18. docker compose pull picks up 18.x patch releases. A move to a new major version is a separate job: Postgres can't open data from an older major version in place, so it needs a dump and restore. Jangka doesn't require it.