homelab-blueprint/docker-compose-files/immich/README.md

Immich

Self-hosted photo and video management solution with high performance and visual aesthetics.

Prerequisites

• NVIDIA GPU: This template is configured for NVIDIA GPU acceleration (RTX A400).
• Proxmox LXC: Must be a Privileged LXC with NVIDIA drivers and Container Toolkit installed.
• Storage: NFS-backed storage for photo uploads is recommended.

Deployment

1. Update .env: Ensure the Immich variables are set in your root .env file. IMMICH_UPLOAD_LOCATION should point to your dedicated Immich share on the UNAS:

   IMMICH_UPLOAD_LOCATION=/mnt/unas/immich_data
   IMMICH_VERSION=release
   IMMICH_DB_PASSWORD=<your-secure-password>
   IMMICH_DB_USERNAME=immich
   IMMICH_DB_DATABASE_NAME=immich
   IMMICH_DB_HOSTNAME=immich-postgres
   IMMICH_REDIS_HOSTNAME=immich-redis
   

   Optional OIDC settings can also be supplied. Set OIDC_ENABLED=true explicitly when enabling OAuth; leaving it unset keeps Immich local-login only.

   OIDC_ENABLED=true
   OIDC_ISSUER=https://auth.example.com/application/o/immich/
   OIDC_CLIENT_ID=<immich-client-id>
   OIDC_CLIENT_SECRET=<immich-client-secret>
   OIDC_NAME=Single Sign-On
   OIDC_AUTO_REDIRECT=false
   OIDC_MOBILE_OVERRIDE_ENABLED=false
   

2. Create Directories: Create the local appdata directories and the shared media directory:

   # Local config/database storage
   sudo mkdir -p /opt/arr-stack/appdata/immich/{postgres,model-cache}
   sudo chown -R 1000:1000 /opt/arr-stack/appdata/immich
   
   # Separate UNAS share for photos
   sudo mkdir -p /mnt/unas/immich_data
   sudo chown -R 1000:1000 /mnt/unas/immich_data
   

3. Mounting the Share: Ensure you have created a separate NFS share on your UNAS (e.g., immich_data) and mounted it on your Proxmox host at /mnt/unas/immich_data before starting the containers.

4. Render Compose File:

   ./substitute_env.sh docker-compose-files/immich/template.yaml docker-compose.immich.yml .env
   

5. Start Stack:

   docker compose -f docker-compose.immich.yml up -d
   

Privileged Mode Rationale

Immich is deployed in a Privileged LXC to ensure:

• GPU Access: The immich-machine-learning container requires direct access to NVIDIA device nodes for CUDA compute.
• VRAM Management: CUDA memory allocation and GSP firmware communication are more stable in privileged mode.
• Storage Mapping: Simplified 1:1 UID/GID mapping for photo uploads on the UNAS NFS share.

GPU Verification

Once the stack is running, you can verify GPU usage by the Machine Learning container:

docker exec -it immich_machine_learning nvidia-smi

You should see the RTX A400 listed. Immich will use this for facial recognition and object detection.