GitBlixt
Docs Navigation

Upgrading

GitBlixt upgrades are designed to be safe and fast. Database migrations run automatically on startup.

Standard Upgrade

    docker service update --image willc0de4food/gitblixt:latest gitblixt

Swarm starts the new task alongside the old one and switches over once it is healthy. The database keeps running. Migrations run automatically on startup.

Upgrading to a Specific Version

docker service update --image willc0de4food/gitblixt:1.2.0 gitblixt

Before Upgrading

  1. Read the release notes for the version you're upgrading to — especially any breaking changes or manual migration steps.
  2. Take a backup before every upgrade. See Backup & Restore.

Rollback

If something goes wrong after an upgrade:

  1. Stop the current container
  2. Start the previous image version (you'll need the old image tag)
  3. Restore your database from the pre-upgrade backup

Upgrading the Bundled Postgres (major version)

New installs run Postgres 18. A major version bump (e.g. 16 → 18) is NOT a plain image update — Postgres refuses to start on a data directory created by an older major version. You must dump on the old version and restore into a fresh new one. (Minor updates within the same major are safe.)

Postgres runs as the gitblixt_postgres service of the gitblixt Swarm stack (check with docker service ls --filter label=com.docker.stack.namespace=gitblixt), so it is managed with docker service and docker stack deploy, not docker compose.

docker stack deploy applies exactly the docker-compose.yml on disk and reverts anything changed live with docker service update. Before deploying, diff /opt/gitblixt/docker-compose.yml against the current one — a stale copy loses the PGDATA pin (Postgres then initializes an empty cluster outside your data dir) and the POSTGRES_MAX_CONNECTIONS/POSTGRES_SHARED_BUFFERS/POSTGRES_CPUS/POSTGRES_MEMORY_LIMIT settings.

Take a backup first, then, on the host where GitBlixt is installed:

    cd /opt/gitblixt
set -a; . ./.env; set +a    # docker stack deploy doesn't read .env itself
pg() { docker ps -q -f label=com.docker.swarm.service.name=gitblixt_postgres; }

# 1. stop GitBlixt AND every managed app, so nothing writes during the dump.
#    Record replica counts first so step 7 can restore them.
docker service scale gitblixt=0
docker service ls --filter label=gitblixt.managed=true --format '{{.Name}} {{.Replicas}}' > app-services.txt
docker ps -q --filter label=gitblixt.managed=true > app-containers.txt
cut -d' ' -f1 app-services.txt | xargs -r -I{} docker service scale -d {}=0
xargs -r docker stop < app-containers.txt

# 2. dump ALL databases + roles with the OLD server's own pg_dumpall.
#    Managed app databases and their roles live in this same cluster, so a
#    single-database pg_dump would silently leave them behind.
docker exec "$(pg)" pg_dumpall -U gitblixt > /opt/gitblixt/pg-upgrade.sql

# 3. stop postgres and set its data dir aside (don't delete yet)
docker service scale gitblixt_postgres=0
sudo mv /opt/gitblixt/data/postgres /opt/gitblixt/data/postgres-old.bak

# 4. bump the postgres image tag in docker-compose.yml, then redeploy the
#    stack — the new major initializes a fresh cluster in data/postgres
docker stack deploy -c docker-compose.yml gitblixt
until docker exec "$(pg)" pg_isready -U gitblixt; do sleep 2; done

# 5. restore every database + role, then rebuild planner statistics
docker exec -i "$(pg)" psql -U gitblixt -d postgres < /opt/gitblixt/pg-upgrade.sql
docker exec "$(pg)" vacuumdb -U gitblixt --all --analyze-in-stages

# 6. tell GitBlixt the new major is intended (see Boot guard below), then
#    bring it back; migrations run on boot
echo 18 | sudo tee /opt/gitblixt/data/config/postgres_major
docker service scale gitblixt=1
docker service ps gitblixt

# 7. bring the managed apps back at their recorded replica counts
while read -r name replicas; do docker service scale -d "$name=${replicas#*/}"; done < app-services.txt
xargs -r docker start < app-containers.txt

Verify the app and a few managed apps work on the new version, then clean up: shred -u /opt/gitblixt/pg-upgrade.sql and sudo rm -rf /opt/gitblixt/data/postgres-old.bak. Keep the .bak until you're confident — it's your rollback.

Boot guard

Before migrating, GitBlixt checks the database it connected to and refuses to start when Postgres reports a different major version than the one it last migrated (recorded in /data/config/postgres_major, or pinned with the POSTGRES_MAJOR env var), or when the database has no GitBlixt schema while /data/repos already holds repositories — the signature of a freshly initialized cluster mounted in place of the real one. Fix the mount or restore the data; set GITBLIXT_SKIP_DB_GUARD=true on the gitblixt service only if you are certain the database is right.