Come installare Immich su Ubuntu 22.04

Installare Immich su Ubuntu 22.04: scelta architetturale e prerequisiti

Immich va trattato come un servizio applicativo composto da più componenti: database PostgreSQL, Redis, API server, machine learning worker, storage persistente e, quasi sempre, un reverse proxy davanti. Su Ubuntu 22.04 la strada più pulita è Docker Compose: riduce il rischio di conflitti con pacchetti di sistema, rende i rollback semplici e separa bene i dati dal runtime.

Prima di partire, chiarisco lo stato atteso: dopo l’installazione devi avere un’istanza Immich raggiungibile via browser, con upload funzionante, database persistente, e una directory dedicata per i dati. Lo stato osservato tipico, quando qualcosa è fatto male, è uno di questi: container che non partono, pagina bianca, errori 5xx dal reverse proxy, permessi errati sulle directory, oppure problemi di storage dopo il primo riavvio.

Le ipotesi più probabili, in ordine, sono: 1) configurazione Docker incompleta o vecchia rispetto alla release di Immich; 2) storage o permessi sbagliati; 3) reverse proxy o DNS non corretti. Le falsifichi in pochi minuti con i log dei container, il controllo dei bind mount e una richiesta HTTP locale verso il servizio.

Prerequisiti minimi

Servono una macchina Ubuntu 22.04 aggiornata, accesso sudo, almeno 4 GB di RAM per un setup minimo, spazio disco adeguato per foto e video, un nome DNS se vuoi pubblicarlo su Internet e una porta libera per il proxy. Per uso serio, meglio 8 GB di RAM o più e storage su SSD.

Verifica subito sistema e spazio:

lsb_release -a
free -h
df -h
uname -a

Atteso: Ubuntu 22.04, memoria sufficiente, spazio libero coerente con il volume atteso dei media. Se il disco è già saturo, fermati qui: Immich scrive molto, e con poco margine rischi corruzione o downtime.

Installare Docker e Docker Compose

Su Ubuntu 22.04 puoi usare i pacchetti ufficiali Ubuntu, ma per un ambiente stabile e aggiornabile conviene il repository Docker ufficiale. Se Docker è già presente, controlla versione e stato dei servizi prima di toccare altro.

docker --version
docker compose version
systemctl status docker --no-pager

Se non sono installati, procedi con una installazione pulita. Questo impatta solo il layer runtime, non i dati di Immich, quindi il blast radius è basso e il rollback è semplice: rimozione pacchetti e repository, senza toccare i volumi applicativi.

sudo apt update
sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Controllo finale:

docker --version
docker compose version
systemctl is-active docker

Atteso: Docker attivo e plugin Compose disponibile. Se il demone non parte, guarda subito journalctl -u docker -xe --no-pager.

Creare la directory di lavoro e i volumi

Immich non va installato in una directory casuale. Serve un path dedicato, stabile e facilmente backupabile, ad esempio /opt/immich. Dentro avrai il file Compose, il file di ambiente e i dati persistenti. Se separi bene configurazione e storage, il rollback è molto più semplice.

sudo mkdir -p /opt/immich
cd /opt/immich
sudo mkdir -p library postgres model-cache

Se vuoi ridurre errori di permessi, puoi far gestire i file al tuo utente amministrativo, ma i volumi del database e della libreria devono restare persistenti e coerenti con l’UID/GID usato dai container. Il punto critico qui è non mischiare ownership a caso.

Verifica i permessi:

ls -ld /opt/immich /opt/immich/library /opt/immich/postgres /opt/immich/model-cache

Atteso: directory presenti e scrivibili dall’utente che lancerà Compose o, più semplicemente, dal root via sudo. Se hai storage esterno o mount separato, controlla anche che sia montato prima di avviare i container.

Scaricare i file ufficiali di Immich

Immich cambia rapidamente. Non copiare file a mano da fonti non affidabili: usa il repository ufficiale e prendi la versione coerente dei file di deploy. Serve sempre verificare che la release e i file Compose siano allineati, perché un mismatch tra immagine e schema del database è una delle cause più comuni di avvio fallito.

Procedura tipica:

cd /opt/immich
sudo curl -fsSL -o docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
sudo curl -fsSL -o .env https://github.com/immich-app/immich/releases/latest/download/example.env

Se preferisci maggiore controllo, puoi scaricare una release specifica invece di latest. Per ambienti produzione è più pulito: sai esattamente quale versione è in esecuzione e puoi fare rollback pinning alla release precedente.

Controlla i file:

sed -n '1,220p' docker-compose.yml
sed -n '1,220p' .env

Atteso: nel Compose devono comparire i servizi principali di Immich e i mount verso le directory persistenti. Nel file .env devi impostare almeno le variabili richieste dalla release corrente.

Configurare .env e storage persistente

Qui si fanno gli errori più costosi. Devi impostare una password forte per PostgreSQL, definire il percorso della libreria, e controllare che i path dei volumi corrispondano alle directory create prima. Non mettere segreti in chiaro in documentazione condivisa o ticket: trattali come credenziali vere, con rotazione se esposte.

Apri .env e verifica i campi chiave. I nomi esatti possono cambiare tra release, quindi la regola è semplice: usa il file ufficiale come base e modifica solo ciò che sai verificare nel Compose.

nano /opt/immich/.env

Valori da controllare con attenzione:

• password del database
• directory della libreria media
• timezone
• eventuali path del modello AI o cache
• eventuale endpoint esterno se usi reverse proxy o dominio pubblico

Se vuoi validare subito il file senza avviare tutto, usa:

docker compose --env-file /opt/immich/.env config

Atteso: Compose renderizzato senza errori di sintassi e con i path risolti. Se fallisce qui, hai già isolato il problema prima di toccare i container.

Avviare Immich con Docker Compose

Una volta che i file sono corretti, avvia i servizi. Questa è l’azione minima reversibile: se qualcosa va storto, puoi fermare i container senza distruggere i volumi.

cd /opt/immich
sudo docker compose up -d

Subito dopo controlla lo stato:

sudo docker compose ps
sudo docker compose logs -f --tail=100

Atteso: database, Redis, API e worker in stato running o healthy. Se uno o più servizi crashano, il primo indizio è quasi sempre nei log. Cerca errori su connessione a PostgreSQL, permessi sui mount, o variabili mancanti.

Se il database non parte, verifica che il volume sia scrivibile e che non ci sia uno spazio disco insufficiente:

df -h
sudo ls -ld /opt/immich/postgres
sudo docker compose logs --tail=100 postgres

Accesso iniziale e creazione account amministratore

Quando i container sono su, il frontend dovrebbe rispondere sulla porta esposta dal Compose, spesso 2283. In locale verifica prima l’HTTP, poi il browser. Questo evita di confondere problemi di GUI con problemi di rete.

curl -I http://127.0.0.1:2283

Atteso: un codice HTTP 200 o un redirect coerente. Se ricevi connection refused, il servizio non è in ascolto o la porta è diversa nel Compose. Se ricevi 5xx, passa ai log del container web/API.

Apri il browser verso http://IP_SERVER:2283 o verso il dominio se hai già un proxy. Al primo accesso crea l’account admin. Da lì controlla che upload, anteprime e navigazione libreria funzionino.

Mettere Immich dietro reverse proxy

Per esposizione pubblica, il reverse proxy è la scelta corretta. Puoi usare Nginx, Caddy, Traefik o Apache, ma il principio è identico: TLS terminato sul proxy, backend su porta interna, header corretti, e timeout adeguati per upload e transcodifica. Se il proxy è sbagliato, vedrai upload che falliscono, websocket interrotti o errori 502/504.

Esempio logico di configurazione: il proxy riceve https://immich.example.com e inoltra verso http://127.0.0.1:2283. Devi preservare Host, X-Forwarded-For e X-Forwarded-Proto. Il certificato può essere gestito con Let’s Encrypt se il dominio punta correttamente al server.

Controllo rapido del layer proxy:

curl -I https://immich.example.com
curl -I http://127.0.0.1:2283

Se il backend risponde ma il dominio no, il problema è nel proxy o nel DNS. Se entrambi rispondono male, il problema è nel servizio o nella porta esposta.

Backup e manutenzione

Immich ha due asset da proteggere: database PostgreSQL e libreria media. Senza backup del database puoi perdere metadati, album, utenti e relazioni tra file; senza backup dei media perdi il contenuto. La strategia minima è snapshot coerente del database più copia dei volumi.

Per il database, usa dump regolari. Per i media, usa backup del volume o dello storage sottostante. Esempio minimo per il DB:

sudo docker compose exec -T postgres pg_dump -U postgres immich > /root/immich-backup.sql

Il comando esatto può variare in base ai nomi definiti nel Compose e nel file di ambiente, quindi verifica prima il servizio database e l’utente reale. Il backup va poi copiato fuori macchina.

Per manutenzione, controlla periodicamente:

• spazio disco
• stato container
• versione release
• log di errori su upload o scansione
• validità del certificato TLS

Problemi comuni e come chiuderli in fretta

Se Immich non parte, la diagnosi pratica segue sempre lo stesso ordine: DNS e proxy, porta locale, container, database, storage. Non fare tuning o reinstallazioni finché non hai un errore concreto da log.

Tre casi tipici:

1. Pagina bianca o 502: controlla il reverse proxy e i log del backend con docker compose logs --tail=100.
2. Upload falliti: verifica permessi sulla directory media e spazio disco con df -h e ls -ld.
3. Database non raggiungibile: controlla il servizio PostgreSQL, il volume persistente e la password nel file .env.

Se devi fare una modifica, falla una alla volta. Per esempio, cambia solo il path del volume, rilancia docker compose up -d, poi verifica. Questo riduce il blast radius e rende chiaro il rollback.

Controlli finali e rollback

Checklist finale minima:

• docker compose ps mostra tutti i servizi attivi
• curl -I http://127.0.0.1:2283 risponde correttamente
• login amministratore funziona
• upload e visualizzazione media funzionano
• reverse proxy e TLS, se presenti, rispondono senza 5xx

Rollback consigliato se qualcosa si rompe dopo il deploy: fermare i container, ripristinare il precedente docker-compose.yml e .env da backup/versioning, poi rilanciare. I dati nei volumi non vanno cancellati a meno che tu non stia facendo una reinstallazione intenzionale e controllata.

cd /opt/immich
sudo docker compose down
sudo cp docker-compose.yml.bak docker-compose.yml
sudo cp .env.bak .env
sudo docker compose up -d

Assunzione: hai usato release ufficiali, storage persistente separato e un reverse proxy configurato con header corretti.