Overview
This series explains how Immich turns uploads into a usable self-hosted archive: clients and APIs accept content, workers build derived layers, Postgres and the filesystem preserve different kinds of state, and search, face recognition, sharing, and restore depend on those boundaries. It follows one asset from capture through processing and recovery, while showing that learned indexes are provisional and durability requires coordinated backups, scoped access, and tested restoration.
Learning outcomes
- Immich is a coordinated archive system, not merely a gallery: the API, queues, workers, database, filesystem, and ML service own different responsibilities.
- An uploaded original can be present before metadata, previews, contextual search, video playback, or face groupings are ready; queue state distinguishes delay from data loss.
- A complete recovery set pairs Postgres state with original media and the storage or mount assumptions it depends on; a database dump alone is insufficient.
- Search and facial recognition add useful but model-dependent indexes, while sharing requires explicit choices about audience, metadata, mutability, and revocation.
Keywords
Preview every chapter · Unlock full text, audio, and video from chapter 4
PlansFAQ
What makes Immich more than a photo gallery?
Immich is more than a gallery because it coordinates client ingestion, durable records, media files, queued processing, learned indexes, sharing, and recovery as one archive system. The visible timeline is only the result; each layer has different ownership and failure conditions.
What must be backed up for an Immich archive to be recoverable?
A recoverable Immich archive needs both the original media and the Postgres database state, plus compatible storage paths, external-library mounts, and version assumptions. Generated previews and encoded video may be rebuilt, but rebuilding costs time; a restore test is needed to verify the pieces agree.
Why can an Immich upload appear before search or face results?
An upload can appear first because the original and core asset record arrive before queued metadata, thumbnail, smart-search, OCR, or face-processing jobs finish. The API accepting a file and the archive becoming fully indexed are separate milestones, so queue status is more informative than a fixed completion time.
How should an Immich operator choose sharing modes?
Choose a shared album for a bounded collaboration among known instance users, partner sharing for deliberate library-scale visibility, and a public link for recipients without accounts. Compare each mode’s audience, actions, metadata exposure, and ability to expire or revoke access before enabling it.