Immich - Self-Host.it

Immich è una piattaforma open-source per il backup e la gestione di foto e video, pensata come alternativa self-hosted a Google Photos. Il progetto è supportato da FUTO , un fondo dedicato allo sviluppo di software open-source che rispetta la privacy degli utenti. L’applicazione offre un’esperienza allineata a quella dei servizi già presenti online, ma a differenza di questi ha il vantaggio di mantenere il pieno controllo sui propri dati.

Immich organizza le foto in una timeline ed è in grado di mappare le fotografie a livello geografico, andando a leggere le coordinate GPS all’interno dei metadati delle fotografie. Il sistema è multi-utente e offre funzioni aggiuntive come il backup automatico e l’importazione delle fotografie direttamente dal mobile attraverso l’utilizzo di app dedicate per iOS e Android.

Processo di Installazione

Dopo aver installato Docker Engine e Docker Compose, è possibile procedere con l’installazione di Immich. La configurazione richiede il file docker-compose.yml per definire i tre servizi necessari (il server Immich, il database PostgreSQL e la cache Valkey) e un file .env per le variabili d’ambiente, entrambi riportati qui sotto.

Creiamo il File Docker Compose

Il file docker-compose.yml qui sotto configura l’intero stack di Immich. Il server sarà raggiungibile sulla porta 2283, ma questa può essere modificata senza problemi. Il database PostgreSQL utilizza un’immagine personalizzata fornita dal progetto Immich, che include le estensioni vettoriali necessarie per le funzionalità di ricerca intelligente.

        yaml
        
    
services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    volumes:
      - ${UPLOAD_LOCATION}:/data
    env_file:
      - .env
    ports:
      - "2283:2283"
    depends_on:
      database:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped

  redis:
    container_name: immich_redis
    image: docker.io/valkey/valkey:9
    healthcheck:
      test: valkey-cli ping || exit 1
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  database:
    container_name: immich_postgres
    image: ghcr.io/immich-app/postgres:16-vectorchord0.4.3-pgvectors0.2.0
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      POSTGRES_INITDB_ARGS: "--data-checksums"
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    healthcheck:
      test: pg_isready --dbname='${DB_DATABASE_NAME}' --username='${DB_USERNAME}' || exit 1
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    restart: unless-stopped
    command:
      [
        "postgres",
        "-c", "shared_preload_libraries=vectors.so, vchord.so",
        "-c", "search_path=\"$$user\", public, vectors",
        "-c", "shared_buffers=256MB",
        "-c", "effective_cache_size=512MB",
        "-c", "work_mem=16MB",
        "-c", "maintenance_work_mem=128MB",
        "-c", "wal_buffers=16MB",
        "-c", "max_wal_size=1GB",
      ]

Definiamo i Container della Configurazione

In questa configurazione andiamo prima di tutto a definire immich-server, che è il cuore dell’applicazione e si occupa di gestire l’interfaccia web, le API e tutta l’elaborazione dei media caricati. Il volume montato in ${UPLOAD_LOCATION} è la directory dove verranno salvate tutte le foto e i video caricati dagli utenti. Il servizio legge le variabili d’ambiente dal file .env e si avvia solo dopo che il database e la cache sono pronti, grazie alle condizioni di depends_on con relativo healthcheck.
Il servizio redis invece utilizza Valkey (che è un fork open-source di Redis), come sistema di cache, che Immich usa per gestire le code di lavoro interne, come ad esempio l’elaborazione delle miniature, la transcodifica video e i task di machine learning. L’healthcheck verifica che il servizio risponda correttamente al comando ping prima di considerarlo pronto.
Infine database fornisce lo storage persistente tramite PostgreSQL, utilizzando un’immagine creata ad-hoc per Immich che include le estensioni VectorChord e pgvectors, che attivano la ricerca vettoriale, permettendo così di trovare immagini simili tra loro o di cercare foto descrivendo il contenuto testualmente. La configurazione include alcuni parametri di ottimizzazione delle prestazioni come shared_buffers, effective_cache_size e work_mem, pensati per gestire in modo efficiente anche collezioni fotografiche molto grandi.

Creiamo il File .env

Il file .env contiene le variabili d’ambiente condivise tra i servizi. È importante personalizzare la password del database con una stringa sicura e impostare UPLOAD_LOCATION con il percorso della directory dove verranno salvate le foto caricate.

        bash
        
    
IMMICH_VERSION=v2
UPLOAD_LOCATION=/mnt/media
DB_DATA_LOCATION=./postgres
TZ=Europe/Rome
DB_PASSWORD=aduey4bd87634gd3324re3fre
DB_USERNAME=immich_user
DB_DATABASE_NAME=immich_database

Funzioni di Machine Learning

Nel caso si vogliano abilitare le funzioni avanzate di machine learning, come il riconoscimento facciale o l’identificazione dei duplicati, è possibile aggiungere il servizio immich-machine-learning al proprio stack. Per sfruttare l’accelerazione hardware è necessario disporre di una GPU compatibile e adattare la configurazione qui sotto in base al modello a disposizione. L’esempio seguente è configurato per una GPU AMD con driver ROCm, ma è consigliabile consultare la documentazione ufficiale sull’accelerazione hardware per verificare la compatibilità con la propria GPU e configurare correttamente i parametri.

        yaml
        
    
services:
  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-rocm
    volumes:
      - model-cache:/cache
    restart: always
    ports:
      - 3003:3003
    devices:
      - /dev/dri:/dev/dri
      - /dev/kfd:/dev/kfd
    group_add:
      - render
    environment:
      - HSA_OVERRIDE_GFX_VERSION=10.3.0
      - MACHINE_LEARNING_MODEL_TTL=300

volumes:
  model-cache:

Il servizio di machine learning può essere eseguito sulla stessa macchina di Immich oppure su una macchina separata senza alcun problema. In entrambi i casi sarà necessario indicare a Immich l’indirizzo del servizio (o il nome del container, se si trova sullo stesso host) per poter attivare queste funzionalità avanzate.

Troubleshooting & Consigli

Di seguito alcuni consigli utili per risolvere i problemi di configurazione più comuni:

Se le foto caricate non vengono visualizzate, verificare che il percorso indicato in UPLOAD_LOCATION nel file .env esista e che i permessi della directory permettano la scrittura.
Se il riconoscimento facciale o la ricerca intelligente non funzionano, assicurarsi che il servizio immich-machine-learning sia attivo e raggiungibile. Controllare i log con docker logs immich_machine_learning e verificare che la GPU sia correttamente configurata e visibile dal container.
Per esporre Immich su internet, configurare un reverse proxy (es. Caddy o NGINX Proxy Manager ) con HTTPS e un certificato SSL valido. Non esporre mai la porta 2283 direttamente su internet senza cifratura.
Per eseguire il backup del database, è possibile utilizzare pg_dump direttamente dal container PostgreSQL con il comando docker exec immich_postgres pg_dump -U immich_user immich_database > backup.sql. È consigliabile automatizzare questa operazione con un cron job.