Blocks · Media

media/immich

Immich photo and video library. Immich with its uploads, Postgres database and job queue on a replicated volume behind a VIP.

Overview

Runs Immich, a photo and video library with mobile backup, albums, sharing and, with machine learning, smart search and face recognition. The block is a singleton that runs where its volume's primary is, behind a VIP. It runs Immich's whole stack itself, with every piece's state on the one volume: a private Postgres 18 with the VectorChord extension, reachable only over a Unix socket; Redis for Immich's job queue; the optional machine-learning service on loopback; and the Immich server. The volume holds the uploads, thumbnails and transcoded videos, the database, the job queue and the downloaded models.

Its Postgres is the same build db/postgres uses, with pgvector and VectorChord added, so one copy serves both types on a node.

Open http://<VIP>/ right after deploying: until the administrator account is created, anyone who reaches Immich can create it.

Shape
Singleton on a replicated volume
Reached at
VIP on HTTP
Node package
pkgs.immich, pkgs.immich.machine-learning, pkgs.redis and Postgres 18 with VectorChord

Fetched on demand: the first time a block of this type is placed on a node, its agent fetches pkgs.immich, pkgs.immich.machine-learning, pkgs.redis and Postgres 18 with VectorChord, built from the node's own nixpkgs so the NixOS binary cache serves it. That first placement needs network access (or a binary cache on the LAN) and waits for the download; later placements on that node start at once.

Example

immich.yaml
apiVersion: expanse.io/v1
kind: Block
metadata:
  name: photos
  namespace: default
spec:
  type: media/immich
  replicas: 1
  strategy:
    kind: SINGLETON
  resources:
    requests:
      cpu: "2"
      memory: 4Gi
  storage:
    - name: immich-data
      size: 500Gi
      replication: 3
      mountPath: /var/lib/immich
  network:
    ports:
      - name: http
        port: 80
        target_port: 2283
        protocol: tcp
        expose: EXPOSE_VIP
    health_check:
      readiness:
        type: PROBE_TCP
        port: 2283
        period_seconds: 2

Size the volume for the library: the originals, plus thumbnails and transcoded videos (roughly a further 10 to 20 percent), plus the database.

$ expanse ctl block apply -f immich.yaml --dry-run   # validate only
$ expanse ctl block apply -f immich.yaml

Configuration

Everything else (users, libraries, storage template, job settings) is set in Immich's web UI and kept in its database on the volume.

Keys go under spec.config and are checked against the type's JSON Schema when the block is applied. A default is what the block uses when the key is unset.

KeyDefaultMeaning
port2283Immich's HTTP port, the target_port of 80.
machineLearningtrueRun Immich's machine-learning service for smart search, face recognition and OCR, on 127.0.0.1:3003.

Using it

Point a name at the block's VIP (expanse ctl block get photos) and create the administrator. The mobile apps want HTTPS: put a web/caddy block in front and point it at this block's VIP.

On first start, Immich imports its reverse-geocoding data into the database before it runs any job; that took 140 seconds in Expanse's VM test. Uploads are accepted meanwhile and processed afterwards.

The machine-learning service downloads its models from Hugging Face the first time each is used and keeps them on the volume, so nodes need internet access for it. With machineLearning: false, also turn machine learning off in Administration → Settings → Machine Learning, or every new photo logs a failed job.

When a node fails

When the serving node dies, the block, its volume's primary and its VIP move together to a survivor, and Immich starts there on the same volume. Uploads and browsing pause until it is back; the address stays the same, and the apps stay signed in, because sessions are in the database.

Nothing Immich acknowledged is lost. Immich syncs each upload before the database records it, and the block starts Postgres with fsync, synchronous_commit and full_page_writes on its command line, so a stray setting cannot turn them off. Thumbnails, metadata, transcoding and machine learning run as jobs queued in Redis, which the block runs with appendfsync always: a job queued before an upload was acknowledged runs on the survivor. In Expanse's three-node VM test, with 20 uploads' jobs still queued when the serving node was killed, Immich answered on a survivor about two minutes later with all 21 photos byte for byte, and every queued job ran.

Limits

  • One Immich at a time: it keeps its state in one database on one volume.
  • No external database or Redis: the block always runs its own, on its volume.
  • No hardware-accelerated transcoding or machine learning: no GPU is passed to the block.
  • External libraries on other storage do not fail over with the block; only what is on the volume does.
  • No HTTPS inside the block; use web/caddy in front.
  • Failover with machine learning running is untested: the VM test runs without it.
  • Backups are separate: back up the volume with util/restic-backup.

Source

All block types · Fields every block shares