Run an Immich Recovery Drill Before You Need It

Prerequisites and a safe drill boundary

A recovery drill answers one narrow question: can a known checkpoint produce a usable Immich library without touching the active instance? It is not a production restore rehearsal on the only copy of the database. Use a spare Docker host, a separate Compose project, or a temporary virtual machine with enough disk for the selected sample. Keep its network private and do not point mobile clients at it.

Before starting, record the Immich version, the UPLOAD_LOCATION, the database container name, the database name, and the database username from the deployment configuration. Use a checkpoint from the same or a compatible Immich version; Immich notes that a version mismatch can require migrations. The person running the drill needs Docker access, read access to the backup destination, and authority to start an isolated test stack.

• Keep the active server available; the drill target must use different ports and storage paths.
• Choose a small, representative checkpoint only if it includes the database dump and the corresponding asset folders.
• Treat photo assets as application-managed files. Do not edit, rename, or delete files inside the active Immich storage tree.

Capture a matched checkpoint

Immich keeps file paths and user metadata in PostgreSQL, while photos and generated assets live under UPLOAD_LOCATION. A database dump alone cannot restore the photo library, and a file-only copy loses the metadata that points to those files. The cleanest approach is to pause writes by stopping immich-server while the checkpoint is taken. When a pause is not practical, capture the database first and the filesystem second, which leaves the safer failure case: files that can be uploaded again rather than metadata pointing at absent files.

1. In the Immich web interface, open Administration > Job Queues, choose Create job, select Create Database Dump, then select Confirm. Confirm that a new dump appears in UPLOAD_LOCATION/backups.
2. Copy the required UPLOAD_LOCATION folders to the offline or remote drill destination. Include backups, encoded-video, library, profile, thumbs, and upload; retain the original directory layout.
3. If a command-line dump is required for the deployment, use the database name and username from its configuration rather than guessing defaults:

docker exec -t immich_postgres pg_dump --clean --if-exists --dbname=<DB_DATABASE_NAME> --username=<DB_USERNAME> | gzip > "/safe-backup-path/immich-drill.sql.gz"

pg_dump exports one database, so access must allow it to read the complete Immich database. Save standard error from the command and stop if it reports an error.

Build a disposable restore target

1. Create a separate directory for the drill and copy the saved UPLOAD_LOCATION content into the new target. Create a fresh Immich Compose deployment with its own ports, database-data path, and environment file. For external libraries, reproduce the original mount structure; a different container path can make the restored database refer to files that are not visible.

Start the target with docker compose up -d, then use the welcome screen option Restore from backup. Immich enters maintenance mode and checks the storage folders before offering the available dumps. Select only the copied checkpoint. The documented settings route, Administration > Maintenance > Restore database backup, is for an existing test installation; it replaces that test database.

Verify both the allowed and denied paths

A successful start is not enough. After the target completes its restore health check, sign in only to the isolated instance and test a small sample across dates, albums, search, and an original file download. Open Administration > Maintenance and inspect the integrity report. Immich classifies untracked files, missing files, and checksum mismatches separately, so record the category rather than treating every warning as identical.

The allowed result is a target instance that reads the selected sample, reports expected folder checks, and shows no new missing-file or checksum-mismatch findings for the tested assets. The denied result matters too: from a client on the normal household network, the target should not be reachable on the active production hostname or port. Also confirm that the active production instance still serves its own library unchanged.

Troubleshoot without changing evidence

If folder checks fail, compare the Compose volume mount and ownership with the copied target tree before changing any application data. Missing .immich markers can signal a missing mount or a restore that omitted a folder; do not bypass mount checks merely to make the service start. If the target reports missing files, confirm that every required folder was copied with its original relative layout. If a database dump does not match the target version, stop and select the documentation for the version that produced the backup rather than forcing a migration during the drill.

Avoid using the active library as a troubleshooting workspace. A recovery drill should leave a small written record: checkpoint time, application version, restore target path, tested asset identifiers, integrity results, and the next corrective action.

Roll back the drill cleanly

The rollback is intentionally simple because the target was isolated. Stop and remove only the drill project:

docker compose down

Remove the temporary test volumes and copied files only after retaining the drill notes and only after checking that the Compose project name and paths belong to the test target. Do not run docker compose down -v against the active Immich project. Keep the original backup set according to its retention policy; the drill validates it but does not replace the next scheduled backup.

A repeatable drill turns a backup from a stored file into evidence. Schedule the next test after any meaningful Immich, storage, or mount-layout change.