CitadelUpgrade and rollback
Update Citadel while keeping a way to recover your accounts and settings.
These steps update an installation using published Citadel images.
Before an upgrade
- Read the target release notes.
- Back up PostgreSQL and
citadel_datatogether. Check that you can retrieve the backup. - Record the current complete Core and Agent image addresses, including their versions or digests.
- Confirm the current installation is healthy.
Upgrade
If CITADEL_IMAGE is blank, pulling selects the currently published latest
image tag. Confirm that this is the version you intend to install.
If you pinned a version, change it to the complete image address for your chosen
release, for example ghcr.io/citadel-p/citadel:VERSION with VERSION replaced.
Keep your existing Compose project name and volumes. Downloading a fresh .env
or changing COMPOSE_PROJECT_NAME can start a separate installation instead of
upgrading the existing one. Apply any Compose changes required by the release
notes to your existing files.
From your installation directory, run:
docker compose pull
docker compose up -d
docker compose psInclude your TLS overlay in these commands if you use it. Citadel updates its database during startup. Check sign-in, Platform connectivity, and a normal application operation before removing the old backup. Update Agents using the new generated setup command when the release notes require it.
Rollback
Changing the image back does not undo database changes. Use an earlier image
without restoring data only when the release notes confirm it is compatible.
Otherwise stop Core and restore the matched pre-upgrade PostgreSQL and
citadel_data backup before starting the previous image. Follow
control-plane recovery.
Use exact patch versions or digests when you need a repeatable installation.
Core releases publish latest alongside patch, minor, and major aliases.