How to upgrade a self-hosted Openfuse deployment to a new version, including backup procedures, the upgrade process, and rollback steps.

Openfuse upgrades are designed to be straightforward. Database migrations run automatically on API startup, and Keycloak realm configuration is re-imported by the Config Importer.

Before you upgrade

Check the release notes for breaking changes or special migration instructions.
Back up both databases — migrations are not reversible without a backup.

Backup

Bundled PostgreSQL:

docker compose exec db pg_dump -U openfuse -d openfuse > openfuse-$(date +%Y%m%d).sql
docker compose exec db pg_dump -U openfuse -d keycloak > keycloak-$(date +%Y%m%d).sql

Managed database (RDS, Cloud SQL, etc.):

pg_dump -h <host> -U <user> -d openfuse > openfuse-$(date +%Y%m%d).sql
pg_dump -h <host> -U <user> -d keycloak > keycloak-$(date +%Y%m%d).sql

For managed databases, also consider taking a provider-level snapshot through your cloud console before upgrading.

Upgrade

Using the upgrade script

bash scripts/upgrade.sh 1.2.0

This updates OPENFUSE_VERSION in your .env, pulls the new images, and restarts all services.

Manual upgrade

# 1. Update version in .env
sed -i 's/^OPENFUSE_VERSION=.*/OPENFUSE_VERSION=1.2.0/' .env

# 2. Pull new images
docker compose pull api keycloak keycloak-config-importer ui

# 3. Restart services
docker compose up -d

What happens during an upgrade

Database migrations run automatically when the API starts. An advisory lock prevents concurrent migrations if you run multiple replicas. No manual migration step needed.
Keycloak realm config is re-imported by the Config Importer service. Updated realm settings are applied automatically.
UI static assets are replaced with the new version. The config.js runtime injection means your domain configuration persists across upgrades.

Rollback

If an upgrade fails or causes issues:

# 1. Revert version in .env
sed -i 's/^OPENFUSE_VERSION=.*/OPENFUSE_VERSION=1.1.0/' .env

# 2. Pull previous images
docker compose pull api keycloak keycloak-config-importer ui

# 3. Restart
docker compose up -d

If database migrations need reverting, restore from your backup:

psql -h <host> -U <user> -d openfuse < openfuse-YYYYMMDD.sql
psql -h <host> -U <user> -d keycloak < keycloak-YYYYMMDD.sql

Restoring a database backup reverts all data changes made since the backup — not just schema changes. Time the backup as close to the upgrade as possible.

Version pinning

Always pin to a specific version in production:

OPENFUSE_VERSION=1.2.0

This ensures reproducible deployments and makes rollbacks straightforward. Never use latest in production — it can pull breaking changes unexpectedly.

Orchestrated deployments

For Kubernetes, ECS, or Cloud Run, the upgrade process is:

Update the image tag in your deployment manifests or task definitions
Run the Config Importer as a one-time task (K8s Job, ECS RunTask, Cloud Run Job)
Roll out the new API and UI versions

Database migrations run automatically. The advisory lock ensures safe concurrent startup of multiple API replicas.

See the platform-specific guides: Kubernetes, AWS ECS, Cloud Run, or Azure Container Apps.

Upgrading