Upgrades

Before upgrading

• Read the target release notes and confirm that the installed release has a supported path to it.
• Create and verify a PostgreSQL, uploads, and configuration backup.
• Record the installed source revision and confirm enough disk space is available for rebuilt images and the backup.
• Confirm the existing deployment is stable enough that new upgrade failures can be distinguished from earlier problems.

Select the release

Obtain a documented source release and review its release notes before replacing application source or deployment files. Keep `.env`, backups, and persistent volumes outside the source replacement.

Build and apply the release

Build the selected source release, then let Docker Compose recreate services whose image changed. Named volumes remain attached when the Compose project name is unchanged. This procedure does not promise zero downtime.

docker compose -f docker-compose.prod.yml up -d --build

Database migrations

Pending database migrations are applied before the API starts accepting traffic. Back up before upgrading, allow the startup migration to complete once, and inspect the first migration error instead of repeatedly forcing migration commands.

Verify the upgrade

• Open the application and confirm sign-in and the main authenticated workspace.
• Confirm realtime features connect and uploaded files remain available.
• Confirm background jobs run and send a test email when email delivery is configured.
• Review release-specific workflows called out in the release notes.

docker compose ps

If the upgrade fails

Check service status and the latest logs, then use Troubleshooting to isolate startup, migration, storage, or configuration failures. Do not repeatedly restart a migration failure without preserving and understanding the first error.

docker compose ps
docker compose logs --tail=100

Rollback

Do not assume that restoring earlier source is a complete rollback. Consult the release notes. When the upgraded database is incompatible with the earlier release, restore the pre-upgrade PostgreSQL and uploads backup and run the matching application revision.

Keep the Compose project name unchanged throughout upgrade and recovery; Docker Compose is the authoritative guide to project identity and persistent resources.