Skip to content

Upgrades, rollback and recovery

Before upgrading, review the release’s compatibility and migration notes, confirm access to both new and rollback images, and test a recoverable backup. Use immutable image tags. For multi-instance deployments, coordinate and drain other server instances before a release that might roll back; the supplied script controls only its local Compose services.

Terminal window
deploy/deploy.sh status
deploy/deploy.sh release RELEASE_TAG
deploy/deploy.sh rollback
deploy/deploy.sh rollback-to PREVIOUS_TAG

Replace the tag placeholders with authorized tags. rollback needs a recorded previous release; use rollback-to for an explicitly selected older tag. Use the current deployment script, not an older deployment workflow. The script checks image availability and rollback maintenance compatibility before replacing an existing release. If a new release fails health checks, it attempts rollback when a target is available; success is not guaranteed.

Rollback disables replay sharing and attempts durable grant revocation before starting the older release. If maintenance or revocation fails, do not bypass the pending state or start an older image manually. Keep sharing disabled, isolate and drain all writers, and resolve the failure using the supported recovery procedure. A legacy release must not serve or create replay shares unless all sharing endpoints are independently isolated.

Choose a private, encrypted backup destination and test restores regularly. Preserve configuration and required secrets separately in a protected secret store.

  • File store: back up the complete server data volume, including media and state. Stop the server for a consistent copy or use a consistent filesystem snapshot.
  • Bundled PostgreSQL: back up the database, including media. The supplied deploy/backup.sh uses a custom-format database dump when the bundled database is running; it does not back up the server data volume in this mode. Protect the volume separately, including any spill journal.
  • External PostgreSQL: use the database provider’s backups or snapshots; the supplied script skips an external database. Also protect any persistent spill journal in the server data directory.

The backup script supports S3 or Google Cloud Storage destinations via BACKUP_URI; it needs the appropriate provider CLI and authorized credentials. Configure and verify destination access controls and encryption independently. Its database-mode detection reads BUGFENCE_DATABASE_URL from .env, not a process environment override; ensure the backup configuration reflects the running server’s storage mode. For file-store backups, BACKUP_STOP_SERVER=true stops the server during the copy. The script defaults to deleting backups older than 30 days; configure BACKUP_RETENTION_DAYS deliberately, or use 0 to disable script deletion and manage retention with your storage policy. Do not assume a running-file copy is consistent.

Stop and drain all server instances before restoring a consistent file-store backup or database backup. Restore to a compatible release and retain the original BUGFENCE_INTEGRATIONS_SECRET so encrypted integration credentials can be read. Validate the restored data and application health in an isolated environment before reopening traffic.

An older backup can restore old replay grants and sharing state. Keep sharing off and writers stopped before restoration; use the supported maintenance procedure to revoke grants on the restored backend before exposing it. Do not re-enable sharing until revocation and isolation are verified and all servers enforce the current sharing controls. If the required compatible maintenance image or recovery procedure is unavailable, keep sharing disabled and seek deployment support.