Guide d’installation Immich dans un container LXC unprivileged avec accélération GPU NVIDIA

Posted on by webmaster

Ce guide détaille l’installation complète d’Immich avec support de l’accélération matérielle NVIDIA dans un container LXC unprivileged sur Proxmox, en suivant les recommandations officielles Docker Compose.

Architecture

  • Hôte : Proxmox VE
  • Container : LXC unprivileged (Debian/Ubuntu)
  • GPU : NVIDIA avec support NVENC
  • Stockage : Mount point dédié pour les données Immich
  • Déploiement : Docker Compose (méthode officielle)

Prérequis

  • driver nvidia installer sur l’hôte

1. Configuration du container LXC sur Proxmox

Configuration du fichier LXC

Sur l’hôte Proxmox, éditez le fichier de configuration de votre container (remplacez XXX par l’ID de votre container) :

nano /etc/pve/lxc/XXX.conf

Ajoutez la configuration suivante :

# Autorisation des périphériques GPU NVIDIA
lxc.cgroup2.devices.allow: c 195:* rwm
lxc.cgroup2.devices.allow: c 226:* rwm
lxc.cgroup2.devices.allow: c 508:* rwm
lxc.cgroup2.devices.allow: c 511:* rwm

# Montage des périphériques NVIDIA dans le container
lxc.mount.entry: /dev/nvidia1 dev/nvidia1 none bind,optional,create=file
lxc.mount.entry: /dev/nvidiactl dev/nvidiactl none bind,optional,create=file
lxc.mount.entry: /dev/nvidia-modeset dev/nvidia-modeset none bind,optional,create=file
lxc.mount.entry: /dev/nvidia-uvm dev/nvidia-uvm none bind,optional,create=file
lxc.mount.entry: /dev/nvidia-uvm-tools dev/nvidia-uvm-tools none bind,optional,create=file
lxc.mount.entry: /dev/dri dev/dri none bind,optional,create=dir

# Activation du nesting pour Docker
features: nesting=1

# Mount point pour le stockage Immich
mp0: /dev/<mon vm>/<mon export>,mp=/mnt/immich
# Mapping des UID/GID pour container unprivileged pour mp0
lxc.idmap: u 0 100000 65536
lxc.idmap: g 0 100000 65536

Pour les autorisations des périphériques GPU Nvidia, prendre le premier nombre 195,226,508,511

pve:~# ls /dev/nv* -al |grep -v nvme |grep -v nvram
crw-rw-rw- 1 root root 195,   0 12 déc.  21:38 /dev/nvidia0
crw-rw-rw- 1 root root 195,   1 12 déc.  21:38 /dev/nvidia1
crw-rw-rw- 1 root root 195, 255 12 déc.  21:38 /dev/nvidiactl
crw-rw-rw- 1 root root 508,   0 20 déc.  13:00 /dev/nvidia-uvm
crw-rw-rw- 1 root root 508,   1 20 déc.  13:00 /dev/nvidia-uvm-tools
crw-rw-rw- 1 root root 508,   0 12 déc.  21:39 /dev/nvidia-vgpuctl

/dev/nvidia-caps:
cr--------  1 root root 511, 1 12 déc.  21:38 nvidia-cap1
cr--r--r--  1 root root 511, 2 12 déc.  21:38 nvidia-cap2

pve:~# ls /dev/dri/ -al
crw-rw----  1 root video  226,   0 12 déc.  21:20 card0
crw-rw----  1 root render 226, 128 20 déc.  13:00 renderD128

Explications :

  • lxc.idmap : Mapping des utilisateurs/groupes pour un container unprivileged
  • lxc.cgroup2.devices.allow : Autorise l’accès aux périphériques GPU (codes majeurs)
  • lxc.mount.entry : Monte les devices NVIDIA nécessaires dans le container
  • features: nesting=1 : Indispensable pour exécuter Docker dans le container
  • mp0 : Mount point pour stocker les données Immich (ajustez selon votre configuration)

Redémarrage du container

pct stop XXX
pct start XXX

Vérification du montage GPU

Connectez-vous au container et vérifiez la présence des périphériques :

pct enter XXX
ls -la /dev/nvidia* /dev/dri/

Vous devriez voir les périphériques NVIDIA montés.

2. Installation des pilotes NVIDIA dans le container

Installation des pilotes

Depuis l’intérieur du container :

# Téléchargez les pilotes NVIDIA (version adaptée à votre GPU)
wget https://us.download.nvidia.com/XFree86/Linux-x86_64/580.119.02/NVIDIA-Linux-x86_64-580.119.02.run

# Installation sans les modules kernel (déjà sur l'hôte)
chmod +x NVIDIA-Linux-x86_64-580.119.02.run
./NVIDIA-Linux-x86_64-580.119.02.run --no-kernel-modules

Vérification

nvidia-smi

Si la commande retourne les informations de votre GPU, l’installation est réussie.

3. Installation de Docker

Installation de Docker

Suivez la documentation officielle Docker pour votre distribution :

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

Configuration du proxy Docker (optionnel)

Si vous utilisez un proxy, créez le fichier de configuration :

mkdir -p /etc/systemd/system/docker.service.d
nano /etc/systemd/system/docker.service.d/http-proxy.conf

Ajoutez :

[Service]
Environment="HTTP_PROXY=http://
<proxy>/"
Environment="HTTPS_PROXY=http://
<proxy>/"
Environment="NO_PROXY=localhost,127.0.0.1,
<domain>,192.168.0.0/16,10.0.0.0/8,172.16.0.0/12"

Rechargez la configuration :

systemctl daemon-reload
systemctl restart docker

4. Installation du NVIDIA Container Toolkit

Installation des prérequis

apt-get update && apt-get install -y --no-install-recommends \
   curl \
   gnupg2

Configuration du dépôt

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

Installation du toolkit

apt-get update

export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.18.1-1
apt-get install -y \
    nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
    nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
    libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
    libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}

Configuration de Docker pour utiliser NVIDIA

nvidia-ctk runtime configure --runtime=docker
systemctl restart docker

Vérification

docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi

Si vous voyez les informations de votre GPU, Docker peut accéder au GPU correctement.

5. Installation de CUDA Toolkit (optionnel)

Si vous avez besoin des outils de développement CUDA :

wget https://developer.download.nvidia.com/compute/cuda/13.1.0/local_installers/cuda-repo-debian13-13-1-local_13.1.0-590.44.01-1_amd64.deb

dpkg -i cuda-repo-debian13-13-1-local_13.1.0-590.44.01-1_amd64.deb
cp /var/cuda-repo-debian13-13-1-local/cuda-*-keyring.gpg /usr/share/keyrings/
apt-get update
apt-get -y install cuda-toolkit-13-1

6. Création de l’utilisateur Immich

adduser --shell /bin/bash --disabled-password immich --comment "Immich User"
apt install -y git
usermod -aG video,render,docker immich

Note : L’utilisateur immich aura l’UID 1000 dans le container, ce qui correspondra à l’UID 101000 sur l’hôte Proxmox grâce au mapping unprivileged.

7. Préparation du stockage

Création de la structure des répertoires

Sur le mount point /mnt/immich :

mkdir -p /mnt/immich/{upload,library,thumbs,encoded-video,profile,backups,immich}

Je ne comprend pas pourquoi il a besoin de /mnt/immich/immich, sans ça, il ne démarre pas.

Configuration des permissions

chown -R 1000:1000 /mnt/immich
chmod -R u+rwX,g+rwX /mnt/immich

Important : Dans un container unprivileged, l’UID 1000 dans le container correspond à l’UID 101000 sur l’hôte Proxmox.

8. Installation d’Immich (méthode officielle)

Téléchargement de la configuration officielle

Basculez sur l’utilisateur immich :

su - immich
cd ~

Téléchargez les fichiers de configuration officiels :

# Clonez le repository officiel ou téléchargez le docker-compose.yml
mkdir immich-app
cd immich-app

# Téléchargez le fichier docker-compose.yml officiel
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
wget -O hwaccel.transcoding.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.transcoding.yml

Configuration du fichier .env

Éditez le fichier .env :

nano .env

Modifiez au maximum via ce fichier, plus simple que de faire des modifications dans le docker compose :

# Chemin de stockage des uploads
UPLOAD_LOCATION=/mnt/immich

# Base de données
DB_PASSWORD=votreMotDePasseSecurise

# Version d'Immich
IMMICH_VERSION=release

# Timezone
TZ=Europe/Paris

no_proxy=
https_proxy=
http_proxy=

OMP_NUM_THREADS="4"
HF_HUB_DISABLE_XET="1"
MACHINE_LEARNING_WORKER_TIMEOUT=300
MACHINE_LEARNING_MODEL_INTRA_OP_THREADS=2
IMMICH_MAX_UPLOAD_SIZE="8192MB"

Modification du docker-compose.yml pour adapter les paths

Éditez docker-compose.yml et modifiez la section immich-server :

nano docker-compose.yml
#
# WARNING: To install Immich, follow our guide: https://docs.immich.app/install/docker-compose
#
# Make sure to use the docker-compose.yml of the current release:
#
# https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
#
# The compose file on main may not be compatible with the latest release.

name: immich

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    volumes:
      # Do not edit the next line. If you want to change the media storage location on your system, edit the value of UPLOAD_LOCATION in the .env file
      - ${UPLOAD_LOCATION}/upload:/data/upload
      - ${UPLOAD_LOCATION}/library:/data/library
      - ${UPLOAD_LOCATION}/thumbs:/data/thumbs
      - ${UPLOAD_LOCATION}/encoded-video:/data/encoded-video
      - ${UPLOAD_LOCATION}/profile:/data/profile
      - ${UPLOAD_LOCATION}/backups:/data/backups
      - /etc/localtime:/etc/localtime:ro
    env_file:
      - .env
    ports:
      - '2283:2283'
    depends_on:
      - redis
    restart: always
    healthcheck:
      disable: false

  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-cuda
    volumes:
      - model-cache:/cache
    env_file:
      - .env
    restart: always
    healthcheck:
      disable: false
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
  redis:
    container_name: immich_redis
    image: docker.io/valkey/valkey:9@sha256:fb8d272e529ea567b9bf1302245796f21a2672b8368ca3fcb938ac334e613c8f
    healthcheck:
      test: redis-cli ping || exit 1
    restart: always

volumes:
  model-cache:

9. Démarrage d’Immich

Première exécution

# En tant qu'utilisateur immich
cd ~/immich-app
docker compose up -d

Vérification des logs

docker compose logs -f

10. Accès à Immich

Ouvrez votre navigateur et accédez à :

http://IP_DU_CONTAINER:2283

Suivez l’assistant de configuration pour créer votre compte administrateur.

Voir les logs

docker logs immich_machine_learning  -f
docker logs immich_server  -f

Docker GPU

Modifier le fichier /etc/nvidia-container-runtime/config.toml

no-cgroups = true
# Reconfigurer le runtime
nvidia-ctk runtime configure --runtime=docker
systemctl restart docker

# Vérifier la configuration Docker
docker info | grep -i nvidia

⚠️ Il faut que docker run --rm --gpus all nvidia/cuda:13.1.0-base-ubuntu22.04 nvidia-smi fonctionne comme nvidia-smi

Vérifier l’utilisation du GPU par Immich

# Pendant le transcodage d'une vidéo
nvidia-smi dmon

Vous devriez voir l’utilisation du moteur de décodage/encodage lors de l’upload de fichier

Dernière mise à jour : Décembre 2025

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *