Updating Orimora

Orimora ships as a single container image, ghcr.io/orimora-app/orimora:<version>, versioned 0.1.0-beta.N during the pre-1.0 beta. Upgrading an instance means pulling a newer image and letting it migrate the database on startup. This guide covers the safe upgrade path and how to roll back.

Note

Database migrations run automatically and fail-closed on container start (see below) — you do not run them by hand. The only manual steps are reading the release notes and taking a backup first.

1. Read the release notes

Every release is documented in CHANGELOG.md and on the GitHub Releases page.

Before upgrading, scan the target version’s entry — in particular the Migration notes section, which calls out anything a self-hoster must know: new or changed environment variables, behavioural default changes, and the migrations that will run. Skipping several versions at once is supported (migrations are cumulative), but read every intermediate entry’s migration notes.

2. Back up the database first

A schema migration is hard to undo without a backup. Take one before every upgrade:

• If you use the built-in backup service, trigger a manual backup (see Backup & Restore).
• Otherwise, pg_dump the database yourself.

Orimora also takes an automatic pre-migration snapshot when BACKUP_PRE_MIGRATION=1 (recommended in production) — but an explicit backup you control is the safety net. See Disaster Recovery for the full restore procedure.

3. Pull the new version and restart

1. Point at the new image tag. Pin a specific version (recommended) rather than a floating tag, so upgrades are deliberate:

   docker-compose.prod.yml

   services:
       app:
           image: ghcr.io/orimora-app/orimora:0.1.0-beta.22

2. Pull and recreate the app container:

   docker compose -f docker-compose.prod.yml pull app
   docker compose -f docker-compose.prod.yml up -d app

4. Migrations run automatically (fail-closed)

On start, the container’s entrypoint runs the database migrations (node run-migrations.mjs) before the server accepts traffic, and it is fail-closed: if a migration fails, the container exits non-zero and the server does not start with an un-migrated or half-migrated database. With BACKUP_PRE_MIGRATION=1, a verified snapshot is taken before the migration runs.

You do not need to run yarn db:migrate manually against a deployed instance — that command is for local development only.

5. Coolify

On Coolify, an upgrade is a redeploy of the app service after the image tag changes:

• After changing the image tag or any environment variable, use Force Rebuild (not just Restart) so the new configuration is picked up.
• The database and Redis are separate Coolify resources and are not touched by an app redeploy.
• On redeploy, Docker waits up to ~70 s for in-flight jobs (emails, webhooks) to finish before replacing the container.

See Coolify Setup for the full deployment model.

6. Verify the upgrade

• Readiness: curl -f https://<your-host>/api/ready should return 200 (it checks the database and Redis). /api/live is a pure liveness check that ignores dependencies.
• Version: confirm the running version matches what you deployed (the footer / About, or the image tag).
• Smoke test: sign in, open a document, run a search.

Caution

If /api/ready stays unhealthy after an upgrade, check the container logs first. A migration failure stops startup by design (fail-closed); the logs will show the failing migration, and the pre-migration snapshot lets you restore.

7. Rolling back

1. Application: redeploy the previous image tag (this is why pinning an exact tag matters).
2. Database: if the failed upgrade had already applied a migration, restore the pre-migration snapshot or your manual backup — a newer schema is generally not compatible with an older app version. See Disaster Recovery.

Tip

Test upgrades against a staging copy of production data before applying them to your live instance, especially across several versions at once.