Updating SummitPSA to a new version

SummitPSA has no in-app “update” button. You update by pointing your Docker Compose at a new image tag and bringing the app back up. The container auto-migrates the database on boot: the entrypoint runs alembic upgrade head before starting the web server, so the schema is brought current automatically, before any traffic is served.

Before you start

Always take a database backup first — the migration runs in place. See Backing up your database and files.

ts=$(date +%Y%m%d-%H%M%S)
sudo docker compose -f /opt/summitpsa/docker-compose.yml exec -T db \
  sh -c 'exec mariadb-dump -uroot -p"$MARIADB_ROOT_PASSWORD" --single-transaction \
         --routines --triggers "$MARIADB_DATABASE"' \
  | gzip > /opt/summitpsa/backups/pre-update-$ts.sql.gz

Update steps

1. Make the new image available. Keep the current image locally for rollback — do not delete it.
2. Bump the pinned tag in your compose file (replace the old version with the new one):

   sudo sed -i 's#ghcr.io/summitpsa/app:OLD#ghcr.io/summitpsa/app:NEW#' \
     /opt/summitpsa/docker-compose.yml

3. Bring up the app. The old container is replaced by the new one, which migrates the DB then serves — expect a brief restart blip:

   sudo docker compose -f /opt/summitpsa/docker-compose.yml up -d app

4. Watch the migration and confirm the head revision:

   sudo docker compose -f /opt/summitpsa/docker-compose.yml logs --tail=40 app
   sudo docker compose -f /opt/summitpsa/docker-compose.yml exec -T app alembic current

Because the old container is replaced before the new schema exists, the previous version never runs against a newer database. If anything goes wrong, see Rolling back an update — rollback requires downgrading the database first.