Immich 3.3 con Docker Compose: il server fotografico di casa al posto di Google Foto

Immich è il server fotografico open source che più si avvicina a Google Foto: backup automatico dallo smartphone, ricerca per contenuto, riconoscimento dei volti, album condivisi, tutto su un disco vostro. Dai primi di luglio 2026 (la 3.0.0 è del 2 luglio) è alla serie 3.x e la versione stabile al momento in cui scriviamo è la 3.3.6 del 4 novembre 2026. Le guide italiane in circolazione, ferme alla serie 1.1xx, usano ancora docker-compose e l’estensione pgvecto.rs, due cose che Immich 3 non supporta più: qui rifacciamo il percorso da zero sulla documentazione ufficiale, dai due file di configurazione fino a backup e aggiornamenti.

In breve

  • Tempo: 60–90 minuti, più il tempo di caricamento della libreria.
  • Difficoltà: media.
  • Cosa serve: un PC o mini PC con Linux a 64 bit (Ubuntu o Debian vanno benissimo), almeno 6 GB di RAM e 2 core, Docker Engine con il plugin Compose, un disco con spazio per le foto e un SSD locale per il database.
  • Risultato: Immich raggiungibile sulla porta 2283 della rete di casa, con l’app Android o iOS che carica le foto da sola.

Versioni: Immich v3.3.6 (stabile del 4 novembre 2026), Docker Engine 25 o successivo con il plugin Compose, immich-go v0.32.0. La procedura segue la documentazione ufficiale di Immich (docs.immich.app) e le note di rilascio su GitHub, verificate il 9 novembre 2026. Le release 3.4.0-rc sono versioni candidate e non vanno usate su un server domestico.

Prima di iniziare: requisiti e dove mettere i dati

La pagina dei requisiti di Immich è più esigente di quanto si pensi. Il minimo è 6 GB di RAM (8 consigliati) e 2 core (4 consigliati); con soli 4 GB il server parte solo disattivando il machine learning, quindi senza ricerca intelligente e senza volti. Dalla versione 3 il container di machine learning su amd64 richiede una CPU di livello x86-64-v2: secondo la documentazione la maggior parte dei processori dal 2012 circa lo supporta; i processori più vecchi, che spesso finiscono a fare da server di casa, restano fuori. Per arm64 la documentazione non indica questo requisito.

Due regole sul disco che la documentazione sottolinea:

  • Le foto (UPLOAD_LOCATION) vanno su un filesystem compatibile Unix con permessi e proprietari, come ext4 o ZFS. Mettete in conto il 10–20% di spazio in più rispetto alla libreria, perché Immich genera miniature e versioni transcodificate dei video.
  • Il database (DB_DATA_LOCATION) deve stare su un SSD locale e mai su una condivisione di rete di alcun tipo. Occupa in genere 1–3 GB e, se usate limiti di risorse in Docker, gli servono almeno 2 GB di RAM.

Sul software, Immich richiede il comando docker compose (con lo spazio): il vecchio docker-compose con il trattino è deprecato e la documentazione dice esplicitamente che non è più supportato. Se Docker non c’è ancora, installatelo dal repository ufficiale come spieghiamo in https://hardwarfare.it/ai-software/linux/installare-docker-compose-ubuntu-debian/, non dai pacchetti della distribuzione.

Attenzione: Immich è pensato per Linux. La documentazione sconsiglia fortemente i sistemi non Linux (Windows e macOS con Docker Desktop), e su WSL il database non funziona nelle cartelle montate dall’host (sotto /mnt). Anche Docker dentro un container LXC, tipico su Proxmox, non è raccomandato: meglio una macchina virtuale.

Passo 1: controllare Docker e il disco

Collegatevi al server via SSH e verificate Docker, il plugin Compose e il filesystem della cartella che ospiterà le foto, per esempio /srv/foto:

docker compose version
df -Th /srv/foto

Verifica: il primo comando deve rispondere Docker Compose version v2.x; se dice “command not found”, il plugin manca. La colonna Type di df deve indicare ext4, zfs, btrfs o xfs: con ntfs, exfat, cifs o nfs il database non partirà.

Passo 2: scaricare i due file ufficiali

Immich si installa con due soli file, da prendere dall’ultima release su GitHub e non da guide di terzi:

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

Il docker-compose.yml della 3.3.6 definisce quattro servizi: immich-server, immich-machine-learning, redis (in realtà l’immagine Valkey 9) e database, basato su ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0, il PostgreSQL con l’estensione VectorChord che ha sostituito pgvecto.rs. Se avete un vecchio file con tensorchord/pgvecto-rs, buttatelo e ripartite da questo.

Verifica: ls -la deve mostrare entrambi i file (.env è nascosto). Se li avete scaricati dal browser, rinominate example.env in .env.

Passo 3: compilare il file .env

Aprite .env con nano .env. Il file ufficiale contiene poche righe e solo quattro vanno toccate:

VariabileValore predefinitoCosa mettere
UPLOAD_LOCATION./libraryCartella delle foto, per esempio /srv/foto
DB_DATA_LOCATION./postgresCartella del database su SSD locale, per esempio /srv/immich-db
TZcommentataTogliete il # e scrivete TZ=Europe/Rome
DB_PASSWORDpostgresUna password casuale con soli caratteri A-Za-z0-9

Il limite sui caratteri della password non è un vezzo: la documentazione avverte che simboli e spazi possono creare problemi all’interpretazione del file da parte di Docker. La riga IMMICH_VERSION=v3 va lasciata così: il tag v3 segue la versione maggiore corrente e salta le release candidate. Le altre variabili non vanno toccate. Create le due cartelle prima di avviare con sudo mkdir -p /srv/foto /srv/immich-db.

Verifica: grep -v '^#' .env | grep . stampa solo le righe attive: devono comparire i vostri percorsi, TZ=Europe/Rome e una password diversa da postgres.

Passo 4: avviare i container

Dalla cartella immich-app lanciate:

docker compose up -d

Il primo avvio scarica quattro immagini e il modello di machine learning, quindi richiede qualche minuto. Poi controllate lo stato:

docker compose ps

Verifica: i quattro container devono essere Up e (healthy). Se immich_server resta a lungo in starting, leggete docker compose logs -f immich-server: al primo avvio esegue le migrazioni del database ed è normale che impieghi un po’.

Aprite dal PC http://IP-DEL-SERVER:2283 e fate clic su Getting Started: il primo utente registrato diventa amministratore e crea gli altri account da Administration > Users. In Administration > Settings > Storage Template si decide come organizzare i file sul disco: fatelo subito, perché le modifiche si applicano ai file già caricati solo lanciando il job Storage Template Migration dalla pagina dei job.

Passo 5: l’app sul telefono e il backup automatico

Installate l’app Immich da Google Play o dall’App Store e inserite l’indirizzo del server con la porta, per esempio http://192.168.1.50:2283. Nella sezione Backup scegliete gli album del telefono da caricare (di solito Camera e Screenshots) e attivate il backup in background con i permessi che l’app chiede. Immich raccomanda di aggiornare le app prima del server: l’app è compatibile con la versione maggiore corrente e quella precedente, il server solo con la propria.

Verifica: fate una foto e, con il telefono in Wi-Fi, aspettate qualche secondo: deve comparire nella timeline web. Se non parte, controllate che la cartella sia selezionata per il backup e che il risparmio energetico non blocchi l’app.

Passo 6: importare l’archivio di Google Foto

Il trasloco passa da Google Takeout: richiedete l’esportazione dei soli dati di Google Foto in archivi ZIP e non estraeteli (la documentazione di immich-go li legge così come sono; solo gli archivi .tgz vanno estratti prima). Per importarli mantenendo date, descrizioni e album lo strumento di riferimento è immich-go, un eseguibile a riga di comando per Linux, Windows, macOS e FreeBSD che si scarica dalle release su GitHub: la v0.32.0 del 25 giugno 2026 ha introdotto la compatibilità con Immich 3, quindi non usate versioni precedenti. Create una chiave API dal vostro profilo in Immich (Account Settings > API Keys) e lanciate l’importazione da una macchina che vede sia gli archivi sia il server, con la sintassi degli esempi della documentazione di immich-go:

./immich-go upload from-google-photos --server=http://192.168.1.50:2283 --api-key=LA-VOSTRA-CHIAVE /percorso/takeout-*.zip

Il programma legge i file JSON di Google per ricostruire data di scatto e album e salta i duplicati già sul server. Per librerie da centinaia di gigabyte lanciatelo in una sessione tmux.

Verifica: aprite in Immich un album che esisteva su Google Foto e controllate date e numero di elementi; da Administration > Job Queues guardate che le code di miniature e metadati si svuotino. Finché il machine learning non ha finito, la ricerca per contenuto è parziale.

Passo 7: il backup, che non è opzionale

La documentazione lo dice senza giri di parole: Immich conserva percorsi e metadati nel database e non scansiona la cartella delle foto, quindi senza database le foto ci sono ma l’archivio è perduto. Servono due cose, salvate insieme.

Il database. Immich crea da solo un dump giornaliero alle 2:00 e ne conserva gli ultimi 14 in UPLOAD_LOCATION/backups; frequenza e numero si regolano in Administration > Settings > Database Dump Settings. Potete anche farne uno manuale da Administration > Job Queues > Create job > Create Database Dump. Chi preferisce lo script, con il nome del container e i valori di DB_DATABASE_NAME e DB_USERNAME del file .env ufficiale:

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

I file. Tutta la cartella UPLOAD_LOCATION, sottocartella backups compresa, va copiata su un altro disco e idealmente fuori casa, con la regola 3-2-1 descritta in https://hardwarfare.it/ai-software/linux/backup-automatici-server-restic-regola-3-2-1/. Il dump del database da solo non contiene nemmeno una foto.

Il ripristino si fa dall’interfaccia: su un’installazione nuova, dopo aver rimesso le cartelle al loro posto, la schermata di benvenuto offre Restore from backup e lascia scegliere il file .sql.gz; su un’installazione esistente la stessa funzione è in Administration > Maintenance.

Verifica: ls -lh /srv/foto/backups deve mostrare almeno un file .sql.gz. Un backup mai provato in ripristino non è un backup: una volta l’anno fatelo su una macchina virtuale.

Passo 8: aggiornare senza rompere nulla

Immich segue il versionamento semantico e riserva le modifiche incompatibili alle versioni maggiori, ma la documentazione chiede di leggere sempre le note di rilascio prima di aggiornare e rimanda a un elenco su GitHub, filtrato con l’etichetta changelog:breaking-change, delle versioni con modifiche incompatibili. Poi, dalla cartella immich-app:

docker compose pull && docker compose up -d

e, per liberare lo spazio delle immagini vecchie:

docker image prune

Tre avvertenze dalla documentazione. Il tag v3 vi porterà alle 3.x successive ma non a una futura 4.0: il passaggio di versione maggiore andrà fatto a mano cambiando IMMICH_VERSION, dopo aver letto le note di rilascio. Tornare a una versione precedente non è supportato, nemmeno nella stessa serie minore: ecco perché il dump del database va fatto prima di ogni aggiornamento. E non esistono patch per le versioni vecchie: la 3.3.6 è uscita proprio per spegnere la telemetria che la libreria onnxruntime aveva acceso nel container di machine learning delle 3.3.x precedenti, inviando metriche anonime a Microsoft.

Verifica: dopo l’aggiornamento la versione del server mostrata nell’interfaccia di amministrazione deve corrispondere all’ultima release stabile su GitHub.

Passo 9: raggiungere Immich da fuori casa

La porta 2283 non va mai aperta sul router così com’è: il traffico passerebbe in chiaro, password comprese. Le due strade ragionevoli sono un reverse proxy con certificato HTTPS, come in https://hardwarfare.it/ai-software/linux/reverse-proxy-nginx-proxy-manager-caddy/, oppure Tailscale, che evita di esporre il server e funziona anche dietro CGNAT, il caso di molte connessioni FTTH e 5G italiane trattato in https://hardwarfare.it/guide-tecniche/guide-reti/cgnat-ip-pubblico-ddns-tailscale-cloudflare/. La pagina della documentazione sul reverse proxy ricorda di alzare il limite di dimensione dei caricamenti e i timeout (l’esempio per nginx usa client_max_body_size 50000M e 600 secondi), altrimenti i video lunghi del telefono si interrompono.

Se qualcosa va storto

unknown shorthand flag: 'd' in -d oppure permission denied sul file .env

Secondo la documentazione, state usando una versione sbagliata di Docker, tipicamente il pacchetto docker.io di Ubuntu. Rimuovete i pacchetti della distribuzione e installate dal repository ufficiale di Docker. Se invece avete digitato docker-compose con il trattino, l’errore è diverso: The Compose file './docker-compose.yml' is invalid because: 'name' does not match any of the regexes. La cura è la stessa.

can't set healthcheck.start_interval as feature require Docker Engine v25 or later

Il Docker installato è troppo vecchio. La documentazione suggerisce come ripiego di commentare la riga start_interval nella sezione del database, ma la soluzione vera è aggiornare Docker Engine almeno alla 25.

Il container di machine learning si riavvia in continuazione

Se docker compose ps mostra immich_machine_learning in Restarting su hardware datato, la causa più probabile è una CPU sotto il livello x86-64-v2 richiesto dalla v3. Secondo la documentazione l’ultima versione compatibile è la 2.7.5, che però non riceve più aggiornamenti e richiede un server della stessa versione: meglio cambiare macchina o rinunciare al machine learning.

Il database non parte

Quasi sempre DB_DATA_LOCATION punta a un filesystem non supportato: NTFS, exFAT, una condivisione SMB o NFS, oppure una cartella sotto /mnt in WSL. La documentazione indica come alternativa un volume Docker: nel file .env impostate DB_DATA_LOCATION=pgdata e in fondo al docker-compose.yml, sotto volumes:, aggiungete la riga pgdata: accanto a model-cache:.

Come tornare indietro

Per fermare Immich senza perdere nulla basta docker compose down dalla cartella immich-app: foto e database restano nelle cartelle indicate nel file .env e un successivo docker compose up -d ritrova tutto. Le foto sul telefono non vengono toccate finché non le cancellate voi dall’app: in caso di ripensamenti resta la copia sul dispositivo e, se lo avete conservato, l’archivio Takeout.

Guide collegate

  • https://hardwarfare.it/ai-software/linux/installare-docker-compose-ubuntu-debian/: il prerequisito di questa guida.
  • https://hardwarfare.it/ai-software/linux/installare-nextcloud-docker-aio-https/: l’alternativa per chi vuole anche documenti e calendario.
  • https://hardwarfare.it/ai-software/linux/backup-automatici-server-restic-regola-3-2-1/: portare fuori casa foto e dump del database.

La nostra indicazione: Immich 3 è maturo quanto basta per diventare l’archivio fotografico di famiglia, a patto di rispettare le tre regole che la documentazione ripete in continuazione: database su SSD locale, backup di file e database insieme, note di rilascio lette prima di ogni aggiornamento. Chi le salta non ha un server fotografico, ha un singolo punto di guasto con una bella interfaccia.

Articolo redatto con il supporto di strumenti di intelligenza artificiale e verificato dalla redazione. Come usiamo l'AI · Come lavoriamo

Redazione HardWarfare
Redazione HardWarfarehttps://hardwarfare.it/chi-siamo/
La redazione di HardWarfare segue hardware PC, gaming, smartphone, sicurezza informatica e mercato tech. Ogni articolo parte da fonti primarie linkate in calce, viene verificato da un revisore diverso da chi lo scrive e si aggiorna quando i fatti cambiano. Scriveteci da Contatti per segnalazioni e correzioni.

Da non perdere

Articoli correlati

LASCIA UN COMMENTO

Scrivi il tuo commento!
Inserisci il tuo nome