3 - Installation sur TrueNAS

• 3.1 - Concevoir les datasets Immich
• 3.2 - Installer et configurer l'application
• 3.3 - Permissions, UID, GID et ACL
• 3.4 - Stockages multiples et bibliothèques externes

3.1 - Concevoir les datasets Immich

Organisation recommandée

Pour TrueNAS Community Edition, Immich utilise au minimum deux zones de stockage :

Dataset	Rôle	Stockage conseillé
data	médias et sauvegardes automatiques	pool de grande capacité
pgData	base PostgreSQL	SSD si possible

Exemple adapté à ton pool :

/mnt/HDD_DATA_TRUENAS/IMMICH/data
/mnt/HDD_DATA_TRUENAS/IMMICH/pgData

Il est possible de créer un parent IMMICH, puis les deux datasets enfants. Ne pas transformer un dossier existant contenant des données en dataset sans plan de copie et sauvegarde préalable.

Création dans l'interface

1. Ouvrir Datasets.
2. Sélectionner le pool.
3. Créer le parent IMMICH avec le preset Generic.
4. Créer data avec le preset Apps.
5. Créer pgData avec le preset Generic.
6. Vérifier les chemins complets.

Le preset Apps prépare normalement les permissions pour l'utilisateur apps.

Propriétaires attendus

• data doit être modifiable par l'utilisateur qui exécute Immich, par défaut apps UID 568 et GID 568.
• pgData doit appartenir à l'utilisateur utilisé par PostgreSQL. La documentation TrueNAS actuelle indique netdata UID 999 pour le dataset PostgreSQL de l'application.

Ces valeurs peuvent évoluer avec le catalogue. Vérifier l'écran d'installation et les conteneurs avant de changer un propriétaire.

Contrôles depuis le shell

sudo ls -ldn /mnt/HDD_DATA_TRUENAS/IMMICH
sudo ls -ldn /mnt/HDD_DATA_TRUENAS/IMMICH/data
sudo ls -ldn /mnt/HDD_DATA_TRUENAS/IMMICH/pgData
sudo zfs list | grep -i immich

Datasets supplémentaires

Immich utilise :

library
upload
thumbs
profile
encoded-video
backups

Il est possible de créer un dataset pour certains dossiers, par exemple les miniatures sur SSD. Chaque dataset supplémentaire augmente toutefois la complexité des montages, permissions, snapshots et sauvegardes.

Propriétés ZFS

Recommandations générales à adapter :

• compression ZFS activée ;
• snapshots réguliers ;
• pas de déduplication ZFS sans besoin démontré ;
• quotas uniquement avec une marge suffisante ;
• PostgreSQL sur un stockage à faible latence.

Ne pas modifier au hasard recordsize, sync ou d'autres propriétés de fiabilité. Mesurer et comprendre l'impact avant tout réglage avancé.

Référence : https://docs.immich.app/install/truenas/

3.2 - Installer et configurer l'application

Installer l'application

1. Ouvrir Apps.
2. Cliquer sur Discover Apps.
3. Rechercher Immich.
4. Ouvrir l'application puis cliquer sur Install.

La méthode TrueNAS est une contribution communautaire intégrée à la documentation Immich. Elle doit être maintenue via le catalogue TrueNAS, pas en modifiant les fichiers générés du projet Compose.

Paramètres principaux

Paramètre	Exemple
Nom	immich
Fuseau horaire	Europe/Paris
Port Web	30041 par défaut sur l'application TrueNAS
Stockage de données	/mnt/HDD_DATA_TRUENAS/IMMICH/data
Stockage PostgreSQL	/mnt/HDD_DATA_TRUENAS/IMMICH/pgData
Machine learning	activé si les ressources le permettent

Dans le conteneur, les données doivent être montées à l'emplacement attendu par l'application, généralement /data.

Ressources

La documentation TrueNAS indique au moins 6 Go de mémoire pour Immich et recommande davantage avec le machine learning. Pour une bibliothèque importante :

• 4 à 8 threads CPU selon les ressources du serveur ;
• 8 Go de mémoire ou davantage ;
• base sur SSD si disponible ;
• GPU configuré seulement après un fonctionnement correct sur CPU.

Les limites CPU et mémoire ne sont pas des réservations. Éviter de priver TrueNAS et ZFS de mémoire.

Premier démarrage

Une fois l'état Running, ouvrir :

http://ADRESSE_TRUENAS:30041

Vérifier depuis le shell :

sudo docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}' | grep -i immich
sudo ss -ltnp | grep 30041

Journaux

Découvrir les noms :

sudo docker ps -a --format '{{.Names}} {{.Image}} {{.Status}}' | grep -i immich

Puis :

sudo docker logs --tail 200 NOM_CONTENEUR

Ton installation observée exposait le port interne 2283 sur le port hôte 30041 et utilisait un projet Compose nommé ix-immich.

Modifier les paramètres

Utiliser Apps > Installed Applications > Immich > Edit. TrueNAS recrée ensuite les conteneurs. Ne pas modifier durablement :

/mnt/.ix-apps/app_configs/immich/versions/.../templates/rendered/

Ces fichiers peuvent être écrasés lors d'une mise à jour ou d'un redéploiement.

Référence : https://docs.immich.app/install/truenas/

3.3 - Permissions, UID, GID et ACL

Les erreurs de permissions empêchent souvent Immich ou PostgreSQL de démarrer. Identifier les UID et GID réellement utilisés avant toute correction.

Valeurs courantes

Élément	Compte courant
Application Immich	apps, UID 568, GID 568
PostgreSQL de l'application	UID 999 selon le guide TrueNAS actuel

Ces valeurs sont des références et non une raison d'appliquer un changement récursif sans vérification.

Identifier les utilisateurs des conteneurs

sudo docker inspect NOM_CONTENEUR_IMMICH --format '{{.Config.User}}'
sudo docker exec NOM_CONTENEUR_IMMICH id
sudo docker exec NOM_CONTENEUR_POSTGRES id

Examiner les datasets

sudo stat -c '%u:%g %a %n' /mnt/HDD_DATA_TRUENAS/IMMICH/data
sudo stat -c '%u:%g %a %n' /mnt/HDD_DATA_TRUENAS/IMMICH/pgData
sudo getfacl /mnt/HDD_DATA_TRUENAS/IMMICH/data

Corriger avec l'interface

Préférer l'éditeur ACL TrueNAS :

1. sélectionner le dataset ;
2. ouvrir les permissions ;
3. donner Modify à l'utilisateur ou groupe de l'application ;
4. préserver les accès nécessaires aux sauvegardes ;
5. appliquer récursivement uniquement si le contenu et l'effet sont compris.

Pour un dataset SMB/NFSv4 utilisé avec le modèle de stockage, la documentation TrueNAS demande un mode ACL Passthrough afin qu'Immich puisse effectuer les changements nécessaires.

Bibliothèque externe en lecture seule

L'utilisateur Immich a besoin au minimum de lecture et traversée :

sudo -u '#568' find /mnt/HDD_DATA_TRUENAS/PHOTOS -maxdepth 1 -type f -print | head

Le test peut échouer si l'utilisateur 568 n'existe pas dans la base locale. Dans ce cas, contrôler depuis le conteneur après montage :

sudo docker exec NOM_CONTENEUR_IMMICH sh -lc 'id; ls -la /mnt/external-libraries/photos | head'

Erreurs à éviter

• chmod -R 777 sur les datasets ;
• changer récursivement le propriétaire de pgData pendant que PostgreSQL fonctionne ;
• appliquer une ACL SMB incompatible avec les opérations POSIX requises ;
• donner l'écriture à Immich sur une archive devant rester immuable ;
• utiliser le même chemin de montage pour deux bibliothèques différentes.

Après correction, redéployer l'application depuis l'interface et examiner les journaux.

Référence : https://docs.immich.app/install/truenas/

3.4 - Stockages multiples et bibliothèques externes

Stockages Immich séparés

Pour chaque dataset supplémentaire, ajouter une entrée Additional Storage dans l'application TrueNAS.

Dossier Immich	Chemin dans le conteneur	Exemple hôte
originaux organisés	/data/library	/mnt/HDD_DATA_TRUENAS/IMMICH/library
uploads	/data/upload	/mnt/HDD_DATA_TRUENAS/IMMICH/upload
miniatures	/data/thumbs	/mnt/SSD/IMMICH/thumbs
profils	/data/profile	/mnt/HDD_DATA_TRUENAS/IMMICH/profile
vidéos encodées	/data/encoded-video	/mnt/HDD_DATA_TRUENAS/IMMICH/encoded-video
dumps automatiques	/data/backups	/mnt/HDD_DATA_TRUENAS/IMMICH/backups

Le chemin du conteneur doit commencer par /data/ et correspondre exactement au dossier attendu.

Bibliothèque externe

Exemple :

Host Path  : /mnt/HDD_DATA_TRUENAS/PHOTOS
Mount Path : /mnt/external-libraries/photos
Read Only  : activé

Dans Immich, ajouter :

/mnt/external-libraries/photos

Le chemin /mnt/HDD_DATA_TRUENAS/PHOTOS n'existe pas forcément dans le conteneur. Il ne doit pas être saisi dans Immich si le montage interne utilise un autre nom.

Lecture seule ou lecture-écriture

Lecture seule est recommandée lorsqu'Immich sert uniquement à indexer une photothèque existante. En lecture-écriture, Immich peut supprimer un original lorsque la corbeille est vidée et peut créer des fichiers XMP selon les fonctions utilisées.

Contrôler depuis le conteneur

sudo docker exec NOM_CONTENEUR_IMMICH sh -lc \
  'find /mnt/external-libraries/photos -maxdepth 2 -type f | head'

Sauvegardes

Chaque dataset séparé doit être inclus dans :

• les snapshots ;
• la réplication ;
• la copie distante ;
• le plan de restauration ;
• les contrôles d'intégrité.

Si profile ou backups est déplacé vers un autre dataset, une sauvegarde limitée au dataset data ne suffit plus.

Changer un montage existant

1. déclencher un dump PostgreSQL ;
2. arrêter l'application ;
3. copier les données avec préservation des attributs ;
4. vérifier les tailles et les sommes ;
5. modifier le montage dans TrueNAS ;
6. redémarrer ;
7. contrôler l'intégrité et les journaux ;
8. conserver l'ancienne copie jusqu'à validation.

Références :

• https://docs.immich.app/install/truenas/
• https://docs.immich.app/guides/custom-locations/