Immich zelf hosten: RAM en upgrades

Wat u bouwt

Immich is een self-hosted service voor het backuppen van foto's en video's — een echt alternatief voor Google Photos. De software bevat een mobiele app die uw camera-roll op de achtergrond uploadt. Het biedt een tijdlijn, albums, gezichtsherkenning en machine-learning zoekfuncties die termen als "beach" of personen vinden zonder dat u handmatig tags hoeft toe te voegen. U draait de software op een eigen VPS, de originele bestanden blijven op uw schijf staan en niemand scant uw bestanden voor marketingdoeleinden.

De installatie bestaat uit vier containers via het Docker Compose-bestand van het project. Dit deel duurt tien minuten. De rest van deze handleiding behandelt de complexe onderdelen: de machine-learning container verbruikt veel geheugen op kleine systemen, originele bestanden vullen de schijf snel, de mobiele app accepteert geen HTTP-verbindingen zonder beveiliging, en Immich brengt regelmatig wijzigingen door die de compatibiliteit verbreken. Een onvoorzichtige docker compose pull kan ervoor zorgen dat uw database niet meer start. Als u deze vier punten serieus neemt, is Immich zeer stabiel. Negeert u ze, dan verliest u een heel weekend aan probleemoplossing.

Vereisten en belangrijke aandachtspunten

• RAM: de officiële documentatie adviseert minimaal 6 GB en aanbevolen 8 GB — beschouw 4 GB plus swap als het absolute minimum. De immich-server en Postgres containers verbruiken weinig geheugen. De immich-machine-learning container is de grootste verbruiker; deze laadt CLIP en face-recognition modellen in het RAM om zoekindexen op te bouwen. Op een systeem met slechts 2 GB zal de kernel het proces beëindigen. Voeg swap toe, zelfs als u 4 GB heeft.
• Disk: reken op de grootte van uw volledige bibliotheek, plus extra ruimte. Uw originele bestanden worden volledig gekopieerd. Daarnaast genereert Immich thumbnails en preview-afbeeldingen (ongeveer 10–20% extra). Een fotocollectie van 200 GB vereist een volume van 300 GB. Postgres is klein in vergelijking hiermee.
• CPU: elke moderne KVM VPS is geschikt, maar machine learning op de CPU is traag. De smart-search indexering van een grote import kan urenlang op de achtergrond draaien. Dit is normaal; een GPU is niet vereist.
• Een domeinnaam die naar de VPS wijst. De mobiele app werkt het best via een HTTPS-endpoint en het gebruik van een reverse proxy wordt aangeraden. Dit is een vergelijkbare configuratie als een self-hosted Nextcloud instance met Docker, TLS en backups — Immich is de tegenhanger voor foto's van die fileserver.
• Docker en de Compose plugin geïnstalleerd — Docker Engine plus de Compose v2 plugin uit de officiële Docker apt-repository, zoals beschreven in onze Docker Compose basisgids.

Stap 1: Voeg swap toe voordat u iets anders doet

De meest voorkomende fout bij Immich op een kleine VPS is dat de ML container wordt afgesloten door het OOM-mechanisme. Zorg eerst voor extra geheugenruimte voor de kernel.

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -h

free -h moet nu een Swap: regel van 4.0Gi tonen. Dit maakt ML niet sneller, maar het voorkomt dat de container vastloopt tijdens het indexeren op een machine met 4 GB geheugen.

Stap 2: Download de officiële compose en env — gebruik de originele bestanden, niet een kopie

Immich legt de versies van de services en de database-image vast in de meegeleverde bestanden. Gebruik geen compose-file van een blog (inclusief deze) als bron. Download de release assets:

sudo mkdir -p /opt/immich && cd /opt/immich
sudo wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
sudo wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

Deze bestanden komen uit de getagde release, waardoor de image-referenties correct zijn. Het compose-file definieert vier services. Het is belangrijk om te weten wat elke service doet voordat u actie onderneemt:

• immich-server (ghcr.io/immich-app/immich-server, container immich_server) — de API en web UI, luisterend op port 2283. Deze mount uw uploads op /data.
• immich-machine-learning (ghcr.io/immich-app/immich-machine-learning, container immich_machine_learning) — CLIP-zoekopdrachten en gezichtsherkenning. Deze cachet gedownloade modellen in een model-cache volume. Deze service verbruikt veel geheugen.
• database (container immich_postgres) — Postgres met de VectorChord vector-extensie voor similarity search. De image-tag is vastgelegd via een digest in het compose-file, bijvoorbeeld ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:.... Oudere installaties gebruikten pgvecto.rs; de ondersteuning hiervoor is verwijderd in Immich v3.0. Alle huidige installaties gebruiken VectorChord. Wijzig deze tag nooit handmatig.
• redis (container immich_redis) — een Valkey/Redis-instantie voor job queues.

Stap 3: Configureer .env — waar uw foto's en database worden opgeslagen

Open .env en stel vier zaken in. Alles onder de gemarkeerde lijn blijft ongewijzigd.

# Where original uploads are stored on the host
UPLOAD_LOCATION=/opt/immich/library

# Where the Postgres data lives. NEVER put this on an NFS/network share.
DB_DATA_LOCATION=/opt/immich/postgres

# "v3" is a floating tag that tracks the latest v3.x. Pin a full tag like
# v3.0.2 instead — then you upgrade on purpose, not by surprise.
IMMICH_VERSION=v3.0.2

# Change this to a long random string. Letters and digits only.
DB_PASSWORD=REPLACE_WITH_A_LONG_RANDOM_STRING

# Set your timezone so timestamps and "on this day" line up
TZ=Europe/London

###################################################################################
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

Twee regels om problemen te voorkomen. UPLOAD_LOCATION moet naar uw grote schijf verwijzen — als u later een datavolume koppelt, stel dit dan direct in op het mountpad, omdat het verplaatsen achteraf betekent dat u thumbnails en asset-paden moet aanpassen. En DB_DATA_LOCATION moet op een lokale schijf staan: Postgres raakt corrupt op een NFS- of SMB-share, zoals de documentatie expliciet vermeldt. Als u alleen letters en cijfers gebruikt in DB_PASSWORD, voorkomt u een klasse van bugs gerelateerd aan het escapen van connection-strings.

Stap 4: Eerste uitvoering en aanmaken van de admin-gebruiker

cd /opt/immich
sudo docker compose up -d
sudo docker compose ps

Een correct resultaat bestaat uit vier containers, allebei running en uiteindelijk healthy:

NAME                      STATUS
immich_machine_learning   Up (healthy)
immich_postgres           Up (healthy)
immich_redis              Up (healthy)
immich_server             Up (healthy)

De eerste up downloadt meerdere gigabytes aan images; houd rekening met de benodigde tijd. Monitor de voortgang met sudo docker compose logs -f immich-server; de server logt dat deze luistert op port 2283 zodra deze gereed is. Open nu http://YOUR_SERVER_IP:2283 in een browser. Bij het eerste bezoek verschijnt een Getting Started wizard — het eerste account dat u aanmaakt, is de admin. Gebruik een sterk wachtwoord; dit account beheert de serverinstellingen, het gebruikersbeheer en de ML-configuratie die u later nodig heeft.

Stap 5: De mobiele app en achtergrondback-up

Installeer "Immich" via de App Store of Play Store. Op het inlogscherm wordt gevraagd om een Server Endpoint URL. Voer de volledige URL inclusief het schema in, bijvoorbeeld https://photos.example.com (de app voegt /api zelf toe). Log in met het account dat u zojuist heeft aangemaakt. Ga naar het scherm Backup in de app, selecteer de albums die u wilt beschermen (meestal Camera en Screenshots) en schakel Background backup in. De achtergrondback-up op iOS wordt beperkt door het besturingssysteem — uploads in de voorgrond werken altijd, achtergronduploads vinden plaats wanneer het OS dit toestaat.

Dit is de plek waar gebruikers vaak problemen ervaren. Lees Stap 6 voordat u probeert de app op te lossen.

Stap 6: HTTPS via een reverse proxy — en de full-URL regel

De mobiele app vereist HTTPS. Plaats een reverse proxy voor poort 2283 en beëindig de TLS-verbinding daar. Als u al meerdere containers gebruikt, is Traefik met automatische TLS voor meerdere Docker-apps de meest overzichtelijke optie — één label-blok routeert photos.example.com naar de immich-server container en regelt het certificaat voor u. Als u de voorkeur geeft aan nginx, dan biedt de handleiding Let's Encrypt met Certbot en nginx een certificaat en een proxy_pass http://127.0.0.1:2283; blok. Eén proxy-instelling is cruciaal voor Immich: verhoog de limiet voor de uploadgrootte, omdat video's van telefoons groot zijn. In nginx is dit client_max_body_size 50000M; binnen het server-blok — de standaardwaarde van 1 MB zorgt ervoor dat video-uploads worden geweigerd met 413 Request Entity Too Large.

De regel die de app afdwingt: de endpoint moet bereikbaar zijn en in de praktijk HTTPS gebruiken. http:// endpoints, of een direct IP zonder poort, zijn de oorzaak van de foutmelding "the app cannot reach the server" — dit wordt hieronder behandeld als een specifieke fout.

Stap 7: Externe bibliotheken vs uploads — een bestaande fotostructuur importeren

Er zijn twee manieren waarop foto's in Immich terechtkomen. Deze methoden zijn verschillend.

• Uploads zijn assets die eigendom zijn van Immich. De app of de web-uploader kopieert het bestand naar UPLOAD_LOCATION. Immich kan deze bestanden hernoemen, verplaatsen en verwijderen.
• Externe bibliotheken zijn read-only imports van bestanden die al in een map op uw server staan — bijvoorbeeld een oude Pictures structuur of een NAS-export. Immich indexeert deze bestanden op de huidige locatie en toont ze in de tijdlijn, maar wijzigt of verwijdert de originele bestanden nooit.

Om een bestaande structuur te importeren, moet u deze read-only mounten in de servercontainer. Pas docker-compose.yml aan onder immich-server: en voeg een volume toe:

  immich-server:
    volumes:
      - ${UPLOAD_LOCATION}:/data
      - /etc/localtime:/etc/localtime:ro
      - /srv/photos:/mnt/media/photos:ro

De :ro garandeert dat Immich de originele bestanden nooit kan wijzigen. Maak de container opnieuw aan met sudo docker compose up -d. Ga vervolgens in de web UI naar uw avatar → Administration → External Libraries → Create Library, selecteer de eigenaar, klik op Add onder Folders, en voer het pad van de container in — /mnt/media/photos, niet het pad van de host /srv/photos. Klik op Scan. Het gebruik van het host-pad in plaats van het container-pad is de meest voorkomende fout bij externe bibliotheken; de scan vindt dan niets en rapporteert nul assets.

Stap 8: De upgrade-discipline die Immich vereist

Dit onderdeel bepaalt het verschil tussen een werkende Immich-installatie en een defecte installatie. Immich brengt updates snel uit en biedt geen backports voor fixes of ondersteuning voor downgrades. Het blindelings volgen van de floating v3 tag zal uiteindelijk uw database beschadigen. De discipline:

1. Leg een versie vast. Houd IMMICH_VERSION ingesteld op een specifieke tag zoals v3.0.2, en niet op de floating v3 die altijd de nieuwste v3.x ophaalt.
2. Lees elke keer de release notes voordat u upgrade uitvoert. Breaking changes — vooral wijzigingen in de database of vector-extensies — worden hierin vermeld. De v3.0 release is een duidelijk voorbeeld: deze verwijderde pgvecto.rs volledig. Gebruikers met de oude extensie moesten eerst de VectorChord migratie (geïntroduceerd in v1.133) voltooien voordat zij konden upgraden.
3. Maak eerst een back-up van de database (Stap 9). Altijd, maar extra belangrijk wanneer de release notes de database vermelden.
4. Download ook het nieuwe compose file. IMMICH_VERSION legt alleen de server en ML images vast. De Postgres image is vastgelegd via digest binnen docker-compose.yml. Een versie die een nieuwere database extensie vereist, wordt geleverd met een nieuw compose file. Download beide release assets opnieuw, pas uw .env waarden opnieuw toe en voer de upgrade uit.
5. Update uw mobiele clients rond dezelfde tijd. De server ondersteunt alleen de bijbehorende major versie, en de app ondersteunt de huidige en de vorige major versie. Een server die een versie hoger is dan de app geeft Your app major version is not compatible with the server! op de telefoon tot u de app heeft bijgewerkt. Het is daarom het veiligst om eerst de app te updaten.

De daadwerkelijke commando's, zodra de nieuwe bestanden aanwezig zijn:

cd /opt/immich
sudo docker compose pull
sudo docker compose up -d
sudo docker image prune

Stap 9: Backups — een database dump PLUS de originelen, en test deze

Een backup van Immich bestaat uit twee onderdelen. Eén van de twee is onvoldoende. De database bevat de albumstructuur, gezichten, zoekindexen en de koppeling tussen assets en bestanden. De originals directory bevat de daadwerkelijke foto's. Als u één onderdeel herstelt zonder het andere, krijgt u ofwel foto's zonder organisatie, ofwel een lege structuur die naar ontbrekende bestanden verwijst.

Maak een dump van de database met pg_dump vanuit de Postgres container — specifiek de immich database, niet de volledige cluster:

sudo docker exec -t immich_postgres pg_dump --clean --if-exists \
  --dbname=immich --username=postgres | gzip > /opt/immich/immich-db-$(date +%F).sql.gz

Maak vervolgens UPLOAD_LOCATION veilig — de volledige /opt/immich/library boom, en in het bijzonder de submappen library/, upload/ en profile/ — met restic, rsync of borg naar een andere machine of object storage. Voer eerst de database-backup uit en daarna de bestanden. Zo verwijst de dump nooit naar een foto die nog niet is gekopieerd in de bestandsbackup. Externe bibliotheken moet u apart op de originele locatie backuppen; Immich beheert deze niet.

Nu het onderdeel dat iedereen overslaat: test het herstel. Een herstel moet worden uitgevoerd op een nieuwe stack waarvan de server nog nooit is gestart. Gebruik een Postgres image waarvan de vector extension compatibel is met de dump — dit is de reden waarom u de DB image tag nooit willekeurig mag kiezen. Gebruik een schone machine met dezelfde compose en .env, verwijder alle oude gegevens, start alleen de database op en laad de dump:

cd /opt/immich
sudo docker compose down -v
sudo docker compose pull
sudo docker compose create
sudo docker start immich_postgres
sleep 10
gunzip --stdout immich-db-2026-07-15.sql.gz |
  sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" |
  sudo docker exec -i immich_postgres psql --dbname=immich --username=postgres --single-transaction --set ON_ERROR_STOP=on
sudo docker compose up -d

De sed herschrijving van search_path is verplicht bij een VectorChord database — laat u dit weg, dan breekt het herstel halverwege af. Wanneer de stack weer online komt met uw originelen, opent u de web UI: als uw foto's en albums aanwezig zijn, werkt uw backup. Als u dit nog nooit heeft uitgevoerd, heeft u geen backup — u heeft hoop.

Foutmodi, met de strings die u zult zien

De ML container wordt OOM-killed. sudo docker compose logs immich-machine-learning stopt abrupt, docker compose ps geeft aan dat dit gebeurt via Restarting, en de exit code is 137. sudo dmesg | grep -i oom bevestigt dit: Out of memory: Killed process ... (python3). Search en face jobs blijven hangen. De oorzaak is onvoldoende RAM voor de modellen. Oplossingen, in volgorde: voeg swap toe (Stap 1); geef de VPS meer RAM; of, als dit echt niet mogelijk is, schakel ML uit via Administration → Settings → Machine Learning Settings door Smart Search en Facial Recognition uit te schakelen — u behoudt backups en albums, maar verliest de zoekfunctie op inhoud. Het verwijderen van de immich-machine-learning service uit het compose file heeft hetzelfde effect.

Postgres weigert te starten na een upgrade. Het serverlog herhaalt een regel zoals The database currently has VectorChord 0.5.3 activated, but the Postgres instance only has 0.4.2 available. This most likely means the extension was downgraded. — of, bij oudere stacks, The pgvecto.rs extension is not available in this Postgres instance.. De oorzaak is een database image waarvan de extensieversie ouder is dan de versie waarnaar uw data is geüpgraded. Dit gebeurt bijna altijd door het handmatig wijzigen van de image tag of door een nieuwere dump te herstellen op een oudere image. De oplossing is het gebruiken van de Postgres image die overeenkomt — gebruik het compose file van de release die bij uw database past, degradeer niet, en herstel alleen op een compatibele image.

De mobiele app kan de server niet bereiken. Het inlogscherm toont een verbindingsfout / Server is not reachable nadat u de URL heeft ingevoerd. Drie oorzaken: u heeft http:// ingevoerd terwijl de proxy alleen https:// serveert; u bent direct verbonden met de backend maar bent de poort vergeten, waardoor er een poging wordt gedaan tot example.com (poort 443) in plaats van example.com:2283; of de reverse proxy stuurt /api niet door. Los dit op door de volledige https://photos.example.com URL in te voeren en eerst te controleren of deze laadt in een browser op een telefoon. Als de browser wel werkt maar de app niet, dan verwijdert de proxy het pad of is het certificaat zelfgetekend — de app weigert niet-vertrouwde certificaten.

Disk vol tijdens import. Uploaden mislukt, thumbnails worden leeg en de logs tonen ENOSPC: no space left on device of, vanuit Postgres, could not extend file ... No space left on device. df -h laat zien dat het UPLOAD_LOCATION volume op 100% staat. Dit is de reden waarom u de disk moet dimensioneren voordat u een grote bibliotheek importeert. Herstel door een groter volume te koppelen, de stack te stoppen, UPLOAD_LOCATION naar het nieuwe volume te verplaatsen, .env bij te werken en opnieuw te starten — of breid de bestaande disk uit als uw provider dit toestaat. Postgres kan vastlopen als de disk vol raakt; maak eerst ruimte vrij en herstart de database container voordat u uitgaat van corruptie.

FAQ

Hoeveel RAM en schijfruimte heeft Immich nodig?

De officiële vereisten voor Immich zijn minimaal 6 GB RAM en 8 GB aanbevolen. Voor een kleine bibliotheek is 4 GB met swap de praktische ondergrens. Configureer in ieder geval swap, omdat de machine-learning container pieken in het verbruik veroorzaakt. Houd voor de schijfruimte de volledige grootte van uw bibliotheek plus ongeveer 10–20% extra rekening voor gegenereerde thumbnails en previews op lokale opslag. Plaats de Postgres data directory nooit op een netwerkschijf. Als u nog twijfelt over andere software, dan vergelijkt de gids voor zelf hosten in 2026 de voetafdruk van Immich met andere services.

Kan ik Immich zonder GPU draaien?

Ja. De machine-learning container werkt goed op een CPU. Een GPU versnelt alleen de indexing voor smart-search en, bij de juiste image variant, video transcoding. Op een CPU kan de initiële indexering van een grote bibliotheek uren op de achtergrond duren, maar dit blokkeert de backups of het browsen niet. Als uw systeem te zwak is voor ML, kunt u Smart Search en Facial Recognition uitschakelen in de admin settings en de rest behouden.

Hoe upgrade ik Immich veilig?

Pin IMMICH_VERSION naar een specifieke tag zoals v3.0.2, lees de release notes voor elke upgrade en maak eerst een backup van de database. Omdat de Postgres image binnen docker-compose.yml is vastgelegd in plaats van via IMMICH_VERSION, moet u zowel het compose file als example.env van de doelversie opnieuw downloaden en uw waarden opnieuw toepassen, en vervolgens docker compose pull && docker compose up -d uitvoeren. Laat de versie nooit onbeheerd zweven; Immich bevat breaking changes en ondersteunt geen downgrades.

Wat moet ik precies backuppen?

Twee zaken samen: een pg_dump van de immich database en de volledige UPLOAD_LOCATION originals directory. De database bevat albums, gezichten en de asset-to-file mapping; de directory bevat de daadwerkelijke foto's. Een restore vereist beide plus een database image met een compatibele vector extension. Voer eerst de database dump uit en daarna de bestandskopie. Test de restore minimaal één keer op een testmachine; een niet-geteste backup is geen backup.

Hoe importeer ik mijn bestaande fotomap?

Mount de map als een extra volume (bijvoorbeeld - /srv/photos:/mnt/media/photos:ro) als read-only in de immich-server container, maak de container opnieuw aan, en maak vervolgens in Administration → External Libraries een library aan met het container pad /mnt/media/photos. Immich indexeert de bestanden op de huidige locatie en wijzigt of verwijdert deze nooit. De meest voorkomende fout is het invoeren van het host pad in plaats van het container pad, waardoor de scan niets vindt.