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.redisand 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
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.
| Key | Default | Meaning |
|---|---|---|
port | 2283 | Immich's HTTP port, the target_port of 80. |
machineLearning | true | Run 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/caddyin 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
- docs/IMMICH.md: the Expanse guide this page follows.
- nix/blocks/media/immich: the type's identity and JSON Schema.