When something breaks

An upgrade went wrong#

Rolling back is restoring, because migrations only run forward. There are no down migrations, on purpose: a half-reversed schema is worse than a restore from ten minutes ago. harbor upgrade takes a backup immediately before it pulls, and that is the one you want.

harbor config                  # set HARBOR_IMAGE_TAG back to the release you were on
harbor start                   # bring that version up

If the older code cannot read the newer schema, harbor logs api will say so. Then restore the pre-upgrade snapshot as in Restore from a backup, choosing it by timestamp from restic snapshots.

Only the database is gone#

The disk is fine and Postgres is not, after a bad upgrade or a wrong rm. With the dc alias from the restore page:

dc stop api web worker mailfetch suggester backup
dc exec postgres psql -U harbor -c 'DROP DATABASE harbor' -c 'CREATE DATABASE harbor' postgres
dc run --rm backup pg_restore --no-owner --exit-on-error \
  --dbname=postgres://harbor:harbor@postgres:5432/harbor /data/dumps/harbor.dump
dc up -d

/data/dumps/harbor.dump is last night's. For an older one, restore just that file from the snapshot you want first.

The vault will not start after a reboot#

The data volume is still locked. harbor unlock, type the passphrase, and the containers start on their own. While the volume is locked the mount point is write-protected, so nothing has written to the wrong disk in the meantime.

A scan failed#

The Inbox card says so and offers Retry. A failed scan degrades to "filed but not searchable", never to lost paperwork: the original bytes were stored before anything else happened. harbor logs worker shows every scan with its engine, pages and time.

A mail connection stopped#

A broken connection is never a silent one: Settings, Email shows its status and a banner says why. Credentials get revoked and providers rate-limit; reconnecting is the fix.