Immich Self-Hosting: Architecture, Setup, and Backups

Immich self-hosting gives households and small teams a private photo and video library that can run on a home server instead of a hosted photo service. It combines mobile uploads, albums, search, sharing, and background processing, but it is still a multi-service application that needs deliberate storage, updates, and backups. This guide explains what Immich is, how its architecture fits together, and how to deploy it safely with Docker Compose.

What Is Immich?

Immich is a self-hosted photo and video management system. Its user-facing application resembles a modern cloud photo library, while the underlying deployment is a set of services that store original media, create thumbnails, index metadata, and expose the web and mobile interfaces. The project is open source and designed to run on infrastructure you control.

Immich is not just a folder browser. It maintains application metadata for users, albums, assets, sharing, facial recognition, search, and upload state. The original files remain the most valuable part of the system, but the database and generated media are also important for a complete, usable restore. The official quick-start documentation provides the current installation flow and version-specific configuration details.

Self-hosting changes the responsibility model. You control where photos are stored and who can access them, but you also control disk failures, TLS, remote access, upgrades, monitoring, and recovery. Immich can simplify photo management without removing those infrastructure responsibilities.

The Problem Immich Solves

Phone cameras produce large libraries faster than most people can organize them. A typical collection includes original photos, edited exports, videos, screenshots, and files copied from older devices. A basic network share can store these files, but it does not automatically upload from phones, generate previews, search by metadata, or present albums consistently across devices.

Hosted photo services solve the interface and synchronization problems, but they require recurring subscriptions and place the library, account model, and service availability partly outside the owner’s control. Some users also need local processing for privacy, a home-lab workload for learning, or an archive that remains accessible if a provider changes its pricing or features.

Immich addresses the management layer while leaving the storage decision to the operator. A small server can receive phone uploads over a local network, and a larger system can serve multiple users with separate libraries. The trade-off is that the operator must design a reliable system rather than treating a single disk or container as a backup.

How Immich Works

An Immich deployment is best understood as a pipeline:

1. A mobile or web client authenticates and uploads an asset.
2. The server records the asset and places the original in the configured upload library.
3. Background workers extract metadata and create thumbnails or video derivatives.
4. The database stores users, albums, permissions, asset records, and search-related state.
5. The web and mobile clients request originals or derivatives through the server.

The deployment normally includes these logical components:

The exact service names and environment variables can change between releases, so use the project’s current Compose file and documentation rather than copying an old tutorial. The Immich project repository is the authoritative place to inspect release assets and deployment changes.

Originals, derivatives, and metadata

Immich generally needs more than the original media directory to reproduce the experience users expect. Original files are the irreplaceable assets. Thumbnails and encoded video derivatives can often be regenerated, although regenerating a large library takes time and compute. The database is not a substitute for the originals, but losing it can remove album structure, users, sharing data, and much of the application’s organization.

Treat these layers differently in a backup plan:

• Original library: back up with the highest priority and preserve file attributes where practical.
• Database: back up on a schedule that matches upload activity and test that a dump can be restored.
• Generated files: back up if fast recovery matters; otherwise document how to regenerate them.
• Configuration and secrets: retain the Compose file, environment settings, encryption keys, and reverse-proxy configuration securely.

Machine learning and resource usage

Machine-learning features can identify faces and improve search, but initial indexing is often much heavier than normal browsing or upload traffic. CPU-only processing may be adequate for a modest library but slow for tens of thousands of assets. A compatible GPU can accelerate some workloads, but it adds driver, runtime, power, and upgrade complexity.

Plan background processing as a workload with a queue. Avoid judging the server only by how quickly it serves a web page. During an initial scan, thumbnail generation, video transcoding, and recognition can compete for CPU, memory, disk I/O, and database capacity. Schedule imports and indexing during quieter periods if the server also runs file shares or other services.

Storage and Network Design

Immich does not make a single disk reliable. Start by estimating the current library, annual growth, video sizes, derivative overhead, and working space for imports and maintenance. Keep free capacity available; a nearly full filesystem makes upgrades, database maintenance, and recovery harder.

A practical home deployment separates application state from the media library when the host allows it. For example, a fast SSD can hold the database and container state, while a larger HDD pool stores originals. This is not mandatory, but it makes capacity planning and replacement clearer. The database should not be placed on a slow or unreliable removable drive merely because the photos are there.

Local access is usually straightforward: expose Immich on a trusted LAN address and use the mobile application to upload over Wi-Fi. Remote access requires more care. Put the service behind a reverse proxy with HTTPS, use a domain name or controlled VPN path, update the host, and avoid exposing the database or Redis ports. Firewall rules should permit only the traffic required by the proxy and internal services.

If a NAS hosts Immich, consider the application and storage policies together. TrueNAS SCALE can provide datasets, snapshots, and replication, but its storage protection does not replace an independent backup. A custom server can also work well; the NAS building guide covers drive, network, and power decisions that affect an Immich host.

Getting Started with Docker Compose

The official deployment method uses a Compose project. Download the current Compose file and environment template from the project documentation or release repository rather than relying on an old blog copy. The following is a minimal shape showing the important storage boundary; use the exact image versions and service definitions supplied by the current release:

services:
  immich-server:
    image: ghcr.io/immich-app/immich-server:release
    depends_on:
      - redis
      - database
    env_file:
      - .env
    volumes:
      - ${UPLOAD_LOCATION}:/data
    ports:
      - "2283:2283"

  redis:
    image: docker.io/redis:6.2-alpine

  database:
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
    env_file:
      - .env
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data

This example is intentionally not a complete production file: Immich releases may add or change services, health checks, and image requirements. The Docker Compose documentation explains how Compose loads environment variables, creates a project network, and manages service lifecycle. Follow the current Immich quick start for the complete file.

Create dedicated host directories with permissions appropriate for the container runtime. Keep the database path on storage with reliable low-latency I/O, and keep the upload path on the volume intended for the library. Before opening the application to users:

docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 immich-server

Open the server through the LAN address, create the administrator account, and configure the mobile application. Upload a small test set containing a photo, a video, and a file with useful metadata. Confirm that the original exists on the expected volume, that thumbnails appear, and that a second client can view the asset according to the intended permissions.

For an upgrade, read the release notes, make a fresh database backup, pull the approved images, and start the project again:

docker compose exec database pg_dump -U "$DB_USERNAME" "$DB_DATABASE_NAME" > immich-database.sql
docker compose pull
docker compose up -d
docker compose ps

Do not remove volumes as part of routine upgrades. A Compose project can be recreated while persistent volumes remain intact; deleting those volumes is a data-destruction operation.

Backups and Recovery

A sound Immich backup has at least two independent parts: the original media library and the database. Include the configuration and secrets needed to interpret the deployment. A snapshot on the same pool is useful for quick rollback, but it is not protection against theft, fire, host failure, or ransomware.

Use a policy such as:

• Copy originals to a separate backup system on a defined schedule.
• Export or dump the database before upgrades and at regular intervals.
• Keep at least one off-host or offline copy according to the value of the library.
• Encrypt backup destinations and restrict access to the backup account.
• Perform a restore exercise: recover a sample original and restore a database copy in an isolated test deployment.

The backup strategy guide explains how retention, recovery point objectives, and restore testing fit together. For Immich specifically, document whether thumbnails and encoded videos are included. Omitting derivatives may save space, but recovery will require reprocessing and may temporarily change the user experience.

If a user deletes a photo accidentally, a snapshot or versioned backup may recover it. If the database is lost while originals remain, the library may be recoverable but albums and application metadata can require substantial reconstruction. If originals are lost while the database survives, the records do not recreate the photos. Test both failure modes instead of assuming that a successful container restart proves recoverability.

Common Misconceptions

“Immich is a backup.”

Immich is a photo management and synchronization system. A phone upload can provide another copy, but it is not automatically an independent, versioned backup of every original. Protect the server library with a separate backup plan.

“RAID protects the photo library from everything.”

RAID or a redundant filesystem can reduce downtime after a disk failure. It does not prevent accidental deletion, malicious changes, application mistakes, or site-level loss. Use redundancy for availability and backups for recovery.

“The database is optional because the files are on disk.”

The media files matter most, but the database contains the organization and access model that make the library useful. Back up both and keep the database backup process aligned with uploads and upgrades.

Related Articles

• Build Your First NAS covers hardware and storage planning for a home server.
• TrueNAS SCALE Explained explains pools, datasets, snapshots, and applications on a storage-focused host.
• TrueNAS vs Unraid System Architecture compares two common platforms for hosting storage and containers.
• Backup Strategy Best Practices covers retention, off-site copies, and restore testing.

Immich is a strong fit when private photo management, local control, and a capable home server matter more than eliminating operational work. Keep the deployment versioned, separate originals from disposable derivatives, restrict remote access, and prove that both media and database backups can be restored before treating the system as a primary library.