# 3 - Installation sur TrueNAS

Préparer les datasets, permissions, ressources et stockages de l'application Immich sur TrueNAS.

# 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 :

```text
/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

```bash
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 :

```text
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 :

```text
http://ADRESSE_TRUENAS:30041
```

Vérifier depuis le shell :

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

## Journaux

Découvrir les noms :

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

Puis :

```bash
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 :

```text
/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

```bash
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

```bash
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 :

```bash
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 :

```bash
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 :

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

Dans Immich, ajouter :

```text
/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

```bash
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/`