immich: v3.2.2 -> v3.2.4 with immich-postgres 512M -> 768M (R-732)

The ONLY image move in this commit; the limit rides it (09 decision 39's precedent), because the step
itself re-runs immich's geodata import (228 294 -> 228 571 places) — the load that killed the database.
Cause, measured on the bench (audits/immich-first-start-2026-09-30/A-cause.md): the first-start import
runs up to 9 concurrent 5000-row INSERTs; the database then needs ~400 MB anon + ~170 MB touched
shared_buffers (the image's own postgresql.conf fixes 512MB). At 512M with no swap: 61 kills; with 512 MB
swap: 0 (swapped ~70 MB) — why 9202 passed; shared_buffers 128MB alone: still killed; 1024M: 0; 768M: 0.
Proof at the new definition, fresh install from birth, no swap: bench x2 (anon 409/412 MB = 53 %, 0 kills,
import 8.1 s) and box 9202 (anon 368 MB = 48 %, 0 kills, swap.peak 0).
Step, written by upgrade-test.py --write-ladder: bench (harness v4) proven, 10-min watch 0 kills 0
restarts, anon peak 51.1 %; box 9202 through the guarded Update: done 58.5 s, album read back, the running
database limit 805306368 after. The step carries `files_may_change` (the harness saw only immich's six
13-byte `.immich` folder markers rewritten at start) — the night leg takes it only with a whole copy.
Per-box cost: +256 MB on immich-postgres; `mem_limit` 4096M -> 4480M (the old figure was already 128 MB
under the sum of the four limits). Header comment corrected (it said postgres 256M).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS

templates/immich/.felhom.yml

@@ -15,12 +15,12 @@ subdomain: "photos"
 slug: "immich"
 # catalog_since: the date THIS repo last changed this app's pinned images. Any commit that
 # changes an image: line must set this to the same day (see CLAUDE.md).
-catalog_since: "2026-09-23"
+catalog_since: "2026-09-30"
 
 # --- Resource hints (displayed on deploy screen) ---
 resources:
   mem_request: "2048M"
-  mem_limit: "4096M"
+  mem_limit: "4480M"
   pi_compatible: false
   needs_hdd: true
 
@@ -161,3 +161,4 @@ i18n:
 update_ladder:
   - {"from": {"immich-server": "ghcr.io/immich-app/immich-server:v3.0.3", "immich-machine-learning": "ghcr.io/immich-app/immich-machine-learning:v3.0.3", "immich-postgres": "ghcr.io/immich-app/postgres:16-vectorchord0.4.3-pgvectors0.2.0", "immich-redis": "redis:7-alpine"}, "to": {"immich-server": "ghcr.io/immich-app/immich-server:v3.2.2", "immich-machine-learning": "ghcr.io/immich-app/immich-machine-learning:v3.0.3", "immich-postgres": "ghcr.io/immich-app/postgres:16-vectorchord0.4.3-pgvectors0.2.0", "immich-redis": "redis:7-alpine"}, "digest": {"immich-machine-learning": "sha256:d76fe88b69282c09a97eac4f82dafa82cfd77bce274bc742591cde974f87dacb", "immich-postgres": "sha256:1a078b237c1d9b420b0ee59147386b4aa60d3a07a8e6a402fc84a57e41b043a4", "immich-redis": "sha256:858f009f9709ce576febc734aa78b8f6d624b82571f9ddb6bda4377c833b3499", "immich-server": "sha256:79cc1623323d5894922686d8743b4780181428f98eecbfb58ce12c41ef02d1ea"}, "verdict": "proven", "tested_at": "2026-09-22T12:12:19.159912+00:00", "harness_version": 1, "evidence": "felhom.eu/documentation/audits/the-28-2026-09-22/apps/immich/verdict.json", "memory_peak_pct": null, "marks": {"files_may_change": false, "needs_person": null, "memory_tight": false}, "backfilled": "2026-09-23", "note": "backfilled from catalog commit 12c1270; box walk only (harness v1, no memory watch); digest = what the registry served on 2026-09-23, not a measurement of the tested image"}
   - {"from": {"immich-server": "ghcr.io/immich-app/immich-server:v3.2.2", "immich-machine-learning": "ghcr.io/immich-app/immich-machine-learning:v3.0.3", "immich-postgres": "ghcr.io/immich-app/postgres:16-vectorchord0.4.3-pgvectors0.2.0", "immich-redis": "redis:7-alpine"}, "to": {"immich-server": "ghcr.io/immich-app/immich-server:v3.2.2", "immich-machine-learning": "ghcr.io/immich-app/immich-machine-learning:v3.2.2", "immich-postgres": "ghcr.io/immich-app/postgres:16-vectorchord0.4.3-pgvectors0.2.0", "immich-redis": "redis:7-alpine"}, "digest": {"immich-machine-learning": "sha256:60dfcf266a9ef3b7376f5678e8c980d4fb61db5fc48c078fe8a326ab1535d60d", "immich-postgres": "sha256:1a078b237c1d9b420b0ee59147386b4aa60d3a07a8e6a402fc84a57e41b043a4", "immich-redis": "sha256:858f009f9709ce576febc734aa78b8f6d624b82571f9ddb6bda4377c833b3499", "immich-server": "sha256:79cc1623323d5894922686d8743b4780181428f98eecbfb58ce12c41ef02d1ea"}, "verdict": "proven", "tested_at": "2026-09-23T19:58:59Z", "harness_version": 3, "evidence": "felhom.eu/documentation/audits/night-2026-09-23/apps/immich/bench/evidence/MV-immich/verdict.json", "box_evidence": "felhom.eu/documentation/audits/night-2026-09-23/apps/immich/verdict.json", "memory_peak_pct": 51.4, "marks": {"files_may_change": false, "needs_person": null, "memory_tight": false}, "memory_basis": "anon", "memory_cgroup_peak_pct": 100.1}
+  - {"from": {"immich-server": "ghcr.io/immich-app/immich-server:v3.2.2", "immich-machine-learning": "ghcr.io/immich-app/immich-machine-learning:v3.2.2", "immich-postgres": "ghcr.io/immich-app/postgres:16-vectorchord0.4.3-pgvectors0.2.0", "immich-redis": "redis:7-alpine"}, "to": {"immich-server": "ghcr.io/immich-app/immich-server:v3.2.4", "immich-machine-learning": "ghcr.io/immich-app/immich-machine-learning:v3.2.4", "immich-postgres": "ghcr.io/immich-app/postgres:16-vectorchord0.4.3-pgvectors0.2.0", "immich-redis": "redis:7-alpine"}, "digest": {"immich-machine-learning": "sha256:e16c2f166a8174901959fdf85e2e4c7bd1ebc4b37e0b6655de97c41408a260c4", "immich-postgres": "sha256:1a078b237c1d9b420b0ee59147386b4aa60d3a07a8e6a402fc84a57e41b043a4", "immich-redis": "sha256:858f009f9709ce576febc734aa78b8f6d624b82571f9ddb6bda4377c833b3499", "immich-server": "sha256:d317916b28090c33eb36b308464ea391f8b7df1d850fcfea227a39ec879718c2"}, "verdict": "proven", "tested_at": "2026-09-30T14:09:09Z", "harness_version": 4, "evidence": "felhom.eu/documentation/audits/immich-first-start-2026-09-30/bench/apps/immich/bench/evidence/MV-immich/verdict.json", "box_evidence": "felhom.eu/documentation/audits/immich-first-start-2026-09-30/box/immich/box-verdict-immich.json", "memory_peak_pct": 51.1, "marks": {"files_may_change": true, "needs_person": null, "memory_tight": false}, "memory_basis": "anon", "memory_cgroup_peak_pct": 100.0}

templates/immich/docker-compose.yml

@@ -1,7 +1,7 @@
 # Immich - Self-hosted Photo & Video Management
 # Domain: ${SUBDOMAIN}.${DOMAIN}
 # Database: PostgreSQL (with VectorChord) + Redis
-# RAM: ~4GB minimum (mem_limit: 4096M total — server 2048M + ML 1536M + postgres 256M + redis 128M) | Pi-compatible: No (ML too heavy)
+# RAM: ~4GB minimum (mem_limit: 4480M total — server 2048M + ML 1536M + postgres 768M + redis 128M) | Pi-compatible: No (ML too heavy)
 #
 # Environment variables:
 #   DOMAIN          - Your domain (e.g., demo-felhom.eu)
@@ -27,7 +27,7 @@
 
 services:
   immich-server:
-    image: ghcr.io/immich-app/immich-server:v3.2.2
+    image: ghcr.io/immich-app/immich-server:v3.2.4
     container_name: immich-server
     restart: unless-stopped
     depends_on:
@@ -68,7 +68,7 @@ services:
       - "traefik.http.services.immich.loadbalancer.server.port=2283"
 
   immich-machine-learning:
-    image: ghcr.io/immich-app/immich-machine-learning:v3.2.2
+    image: ghcr.io/immich-app/immich-machine-learning:v3.2.4
     container_name: immich-machine-learning
     restart: unless-stopped
     environment:
@@ -103,10 +103,15 @@ services:
       - immich_postgres_data:/var/lib/postgresql/data
     networks:
       - immich-internal
+    # 768M, not 512M (R-732, measured 2026-09-30): immich's FIRST start imports ~228 000 geodata places in up to
+    # 9 concurrent 5000-row INSERTs, and the database then needs ~400 MB of its own memory + ~170 MB of touched
+    # shared_buffers (the image's own postgresql.conf sets 512MB). At 512M it was OOM-killed 61 times on a box with
+    # no swap and survived on a box with swap only by swapping ~70-110 MB out. At 768M, no swap: 0 kills, peak
+    # anon 412 MB (54 %). Lowering shared_buffers to 128MB alone did NOT stop the kills (measured).
     deploy:
       resources:
         limits:
-          memory: 512M
+          memory: 768M
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U immich -d immich"]
       interval: 10s

templates/immich/steps/a1bfe9d95485f8d0.felhom.yml

@@ -0,0 +1,156 @@
+# =============================================================================
+# .felhom.yml — App metadata for felhom-controller
+# =============================================================================
+# Place alongside docker-compose.yml in each stack directory:
+#   /opt/docker/stacks/immich/.felhom.yml
+# =============================================================================
+
+# --- Display info (shown on dashboard) ---
+display_name: "Immich"
+description: "Fotók és videók kezelése (Google Photos alternatíva)"
+category: "media"
+subdomain: "photos"
+
+# --- Asset slug ---
+slug: "immich"
+# catalog_since: the date THIS repo last changed this app's pinned images. Any commit that
+# changes an image: line must set this to the same day (see CLAUDE.md).
+catalog_since: "2026-09-23"
+
+# --- Resource hints (displayed on deploy screen) ---
+resources:
+  mem_request: "2048M"
+  mem_limit: "4480M"
+  pi_compatible: false
+  needs_hdd: true
+
+# --- Backup classification (referential coupling; see felhom.eu documentation/audits/SPIKE-backup-classification-2026-07-14.md) ---
+backup:
+  hdd:
+    - path: appdata/immich
+      class: mandatory        # managed upload library — DB-referenced (SQ3: restore-without = broken)
+  userdata:
+    - path: media/photos
+      class: optional          # external library, :ro — precious but re-scanned (explicit overrides ro-default)
+
+# --- Deploy fields ---
+deploy_fields:
+  - env_var: DOMAIN
+    label: "Domain"
+    type: domain
+    description: "A szerver domain neve"
+    locked_after_deploy: true
+
+  - env_var: SUBDOMAIN
+    label: "Aldomain"
+    type: subdomain
+    default: "photos"
+    required: true
+    locked_after_deploy: true
+    description: "Az alkalmazás aldomainje"
+
+  - env_var: DB_PASSWORD
+    label: "Adatbázis jelszó"
+    type: secret
+    generate: "password:24"
+    locked_after_deploy: true
+
+  - env_var: HDD_PATH
+    label: "Adattárolási útvonal"
+    type: path
+    required: true
+    placeholder: "/mnt/felhom-drives/hdd_1"
+    description: "A külső merevlemez elérési útja, ahol a fotók és videók tárolódnak"
+    locked_after_deploy: true
+
+
+# --- The setup gate (controller >= 0.280.0, `09` §3 decision 46) ---
+# The first visitor would create the admin. So a fresh install is closed to everyone but the household (a browser
+# signed in to the dashboard) until the first setup is done; immich's own status says so (measured on 9202 2026-09-29:
+# isInitialized false -> true once the admin exists).
+setup_gate: true
+# measured on 9202 2026-09-29: isInitialized false -> true after the admin sign-up (audits/login-gate-2026-09-29/C).
+setup_done_probe:
+  url: http://immich-server:2283/api/server/config
+  field: isInitialized
+  done: "true"
+
+# --- App info (info page content) ---
+app_info:
+  tagline: 'Google Photos alternatíva - automatikus fotó mentés és rendszerezés'
+  docs_url: 'https://immich.app/docs/overview/introduction'
+
+  use_cases:
+    - 'Fotók és videók automatikus mentése telefonról'
+    - 'Arc- és tárgyfelismerés gépi tanulással'
+    - 'Térképes megjelenítés helyszín alapján'
+    - 'Emlékek és visszatekintések automatikus generálása'
+    - 'Albumok létrehozása és megosztása családtagokkal'
+
+  first_steps:
+    - 'Nyisd meg a photos.DOMAIN címet a böngészőben'
+    - 'Hozd létre az admin fiókot'
+    - 'Telepítsd az Immich alkalmazást a telefonodra (Android/iOS)'
+    - 'Állítsd be az automatikus feltöltést az alkalmazásban'
+    - 'Hívd meg a családtagokat külön fiókokkal'
+    # MOUNT-READY, REGISTRATION PENDING: a megosztott média/photos mappa be van csatolva
+    # /external/photos néven (csak olvasható), de az Immich CSAK akkor látja, ha az
+    # adminfelületen (Administration → External Libraries) regisztrálod a /external/photos
+    # útvonalat. Compose ezt NEM teszi meg automatikusan — ez egy telepítés utáni lépés.
+    - 'Külső könyvtár (opcionális): Administration → External Libraries → add /external/photos'
+
+  prerequisites:
+    - 'Külső HDD szükséges a fotók és videók tárolásához'
+    - 'Legalább 4 GB szabad RAM ajánlott (gépi tanulás funkciókhoz)'
+    - 'x86 processzor szükséges (nem fut Raspberry Pi-n)'
+
+# --- Controller-side health probe ---
+healthcheck:
+  # container: no exact match and FOUR `immich-*` containers, so the old prefix rule picked whichever the
+  # container list happened to yield first — it could have been `immich-postgres` (R-630)
+  container: immich-server
+  checks:
+    - type: api
+      port: 2283
+      path: "/api/server/ping"
+      expect:
+        status: 200
+
+# --- English copy (localisation slice 5, R-560) --------------------------------------------
+# The Hungarian above is UNCHANGED. A box on English reads this block field by field; a missing
+# field shows the Hungarian one; a controller older than 0.257.0 ignores the block entirely.
+i18n:
+  en:
+    description: 'Photos and videos in one place (a Google Photos alternative)'
+    app_info:
+      tagline: 'A Google Photos alternative - your photos back themselves up and sort themselves'
+      use_cases:
+        - 'Photos and videos back themselves up from your phone'
+        - 'It recognises faces and objects on its own'
+        - 'See where a photo was taken, on a map'
+        - 'Memories and look-backs, put together for you'
+        - 'Build albums and share them with the household'
+      first_steps:
+        - 'Open photos.DOMAIN in your browser'
+        - 'Create the admin account'
+        - 'Install the Immich app on your phone (Android/iOS)'
+        - 'Turn on automatic upload in the app'
+        - 'Invite the household, each with their own account'
+        - 'An external library (optional): Administration -> External Libraries -> add /external/photos'
+      prerequisites:
+        - 'An external hard drive is needed to keep the photos and videos on'
+        - 'At least 4 GB of free RAM is recommended (for the machine learning features)'
+        - 'An x86 processor is needed (it does not run on a Raspberry Pi)'
+    deploy_fields:
+      - env_var: DOMAIN
+        label: 'Domain'
+        description: 'The server domain name'
+      - env_var: SUBDOMAIN
+        label: 'Subdomain'
+        description: 'The subdomain this app answers on'
+      - env_var: DB_PASSWORD
+        label: 'Database password'
+      - env_var: HDD_PATH
+        label: 'Data storage path'
+        description: 'The path to the external hard drive where the photos and videos are kept'
+        placeholder: '/mnt/felhom-drives/hdd_1'

templates/immich/steps/a1bfe9d95485f8d0.yml

@@ -0,0 +1,151 @@
+# Immich - Self-hosted Photo & Video Management
+# Domain: ${SUBDOMAIN}.${DOMAIN}
+# Database: PostgreSQL (with VectorChord) + Redis
+# RAM: ~4GB minimum (mem_limit: 4480M total — server 2048M + ML 1536M + postgres 768M + redis 128M) | Pi-compatible: No (ML too heavy)
+#
+# Environment variables:
+#   DOMAIN          - Your domain (e.g., demo-felhom.eu)
+#   HDD_PATH        - Drive namespace root (managed upload lives under appdata)
+#   USERDATA_PATH   - Ügyfél-tartalom gyökér (<namespace>/userdata)
+#   DB_PASSWORD     - PostgreSQL password (auto-generated)
+#
+# Storage layout (felhom userdata convention):
+#   Managed upload (Immich-owned) → ${HDD_PATH}/appdata/immich   (HDD, host path — app-managed)
+#   External photo library (RO)   → ${USERDATA_PATH}/media/photos → /external/photos
+#   PostgreSQL data    → immich_postgres_data   (named volume, NVMe)
+#   ML model cache     → immich_ml_cache         (named volume, NVMe)
+#   Redis data         → immich_redis_data       (named volume, NVMe)
+#
+# ⚠ EXTERNAL LIBRARY IS NOT WIRED BY COMPOSE: mounting /external/photos only makes the files
+#   visible to the container. To actually surface them in Immich you MUST register an External
+#   Library pointing at /external/photos in the Immich admin UI (Administration → External
+#   Libraries) or via the API — a POST-DEPLOY step. Until then photos sharing is "mount ready,
+#   registration pending". See .felhom.yml first_steps + REPORT.
+#
+# First-time setup:
+#   Create admin account on first visit, then register the External Library (see above).
+
+services:
+  immich-server:
+    image: ghcr.io/immich-app/immich-server:v3.2.2
+    container_name: immich-server
+    restart: unless-stopped
+    depends_on:
+      immich-postgres:
+        condition: service_healthy
+      immich-redis:
+        condition: service_healthy
+    environment:
+      - DB_PASSWORD=${DB_PASSWORD}
+      - DB_HOSTNAME=immich-postgres
+      - DB_USERNAME=immich
+      - DB_DATABASE_NAME=immich
+      - REDIS_HOSTNAME=immich-redis
+      - IMMICH_MACHINE_LEARNING_URL=http://immich-machine-learning:3003
+      - TZ=Europe/Budapest
+    volumes:
+      - ${HDD_PATH}/appdata/immich:/usr/src/app/upload
+      - ${USERDATA_PATH}/media/photos:/external/photos:ro
+    networks:
+      - traefik-public
+      - immich-internal
+    deploy:
+      resources:
+        limits:
+          memory: 2048M
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "http://127.0.0.1:2283/api/server/ping"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.immich.rule=Host(`${SUBDOMAIN}.${DOMAIN}`)"
+      - "traefik.http.routers.immich.entrypoints=websecure"
+      - "traefik.http.routers.immich.tls=true"
+      - "traefik.http.routers.immich.tls.certresolver=letsencrypt"
+      - "traefik.http.services.immich.loadbalancer.server.port=2283"
+
+  immich-machine-learning:
+    image: ghcr.io/immich-app/immich-machine-learning:v3.2.2
+    container_name: immich-machine-learning
+    restart: unless-stopped
+    environment:
+      - TZ=Europe/Budapest
+      - TRANSFORMERS_CACHE=/cache
+    volumes:
+      - immich_ml_cache:/cache
+    networks:
+      - immich-internal
+    deploy:
+      resources:
+        limits:
+          memory: 1536M
+    healthcheck:
+      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:3003/ping')"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 120s
+
+  immich-postgres:
+    image: ghcr.io/immich-app/postgres:16-vectorchord0.4.3-pgvectors0.2.0
+    container_name: immich-postgres
+    restart: unless-stopped
+    environment:
+      - POSTGRES_USER=immich
+      - POSTGRES_PASSWORD=${DB_PASSWORD}
+      - POSTGRES_DB=immich
+      - POSTGRES_INITDB_ARGS=--data-checksums
+      - TZ=Europe/Budapest
+    volumes:
+      - immich_postgres_data:/var/lib/postgresql/data
+    networks:
+      - immich-internal
+    # 768M, not 512M (R-732, measured 2026-09-30): immich's FIRST start imports ~228 000 geodata places in up to
+    # 9 concurrent 5000-row INSERTs, and the database then needs ~400 MB of its own memory + ~170 MB of touched
+    # shared_buffers (the image's own postgresql.conf sets 512MB). At 512M it was OOM-killed 61 times on a box with
+    # no swap and survived on a box with swap only by swapping ~70-110 MB out. At 768M, no swap: 0 kills, peak
+    # anon 412 MB (54 %). Lowering shared_buffers to 128MB alone did NOT stop the kills (measured).
+    deploy:
+      resources:
+        limits:
+          memory: 768M
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U immich -d immich"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+
+  immich-redis:
+    image: redis:7-alpine
+    container_name: immich-redis
+    restart: unless-stopped
+    command: redis-server --appendonly yes
+    environment:
+      - TZ=Europe/Budapest
+    volumes:
+      - immich_redis_data:/data
+    networks:
+      - immich-internal
+    deploy:
+      resources:
+        limits:
+          memory: 128M
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+
+volumes:
+  immich_ml_cache:
+  immich_postgres_data:
+  immich_redis_data:
+
+networks:
+  traefik-public:
+    external: true
+  immich-internal: