Immich Config for Intel N100 with Hardware ML & Reverse Proxy (Ugreen DXP4800, 8GB RAM)

[Luke56784]

Hi everyone,

I wanted to share my Docker Compose configuration for running Immich on an Intel N100 system (specifically a Ugreen DXP4800 running Debian 13 with 8GB RAM).

The Challenge

Initially, heavy tasks like bulk imports or machine learning jobs would completely overwhelm the N100 CPU. The load average would spike dangerously high (sometimes >16), causing the entire system and web interface to become unresponsive because Immich was hogging all 4 cores.

The Solution

I tuned the configuration to prioritize system stability while maintaining good performance. The key changes are:

1. CPU Pinning & Limits:

• I used cpuset: "1-3" to exclude Core 0 entirely. This ensures the OS, SSH, and Reverse Proxy always remain responsive.
• I added hard deploy.resources.limits. The Server is capped at 1.5 CPUs and ML at 1.0 CPU, leaving guaranteed headroom for the database and system processes.

2. Machine Learning Optimization:

• I'm using the OpenVINO image to leverage the N100's iGPU.
• Crucially, I limited the container to WORKERS=1 and single-threaded operations (OMP_NUM_THREADS=1,MKL_NUM_THREADS=1). This prevents the ML process from aggressively stealing CPU time.

3. Storage Tiering:

• Bulk storage (/data) sits on a BTRFS RAID1 HDD array.
• Performance-critical folders (thumbs, encoded-video, profile) are mounted from an NVMe drive for a snappy browsing experience.

4. Network Security:

• No exposed ports: You will notice I commented out ports: 2283:2283. This setup is designed to run behind a Reverse Proxy (like Nginx Proxy Manager). The container is only accessible via the internal Docker network (immich-internal / npm-network), meaning no unencrypted traffic is exposed directly on the host interface. SSL is handled by the proxy.

---

Post-Install Settings

For this config to work effectively, you must adjust two settings in the Immich Web UI after starting the containers:

1. Enable Hardware Acceleration
Go to Administration -> Settings -> Transcoding.

• Hardware Acceleration: Set to Quick Sync.
• Hardware decoding: enabled.

2. Lower Job Concurrency
Go to Administration -> Settings -> Job Settings.

• Set concurrency for heavy tasks (Machine Learning, Smart Search, Face Detection, Transcoding) to 1.
• Why: Even with Docker limits, setting the queue to 5 (default) will cause unnecessary context switching overhead. Let the N100 work on one item at a time efficiently.

---

The docker-compose.yml

name: immich

services:
  immich-server:
    container_name: immich-server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    # Pin to Cores 1-3, leaving Core 0 free for the OS/Proxy
    cpuset: "1-3"
    deploy:
      resources:
        limits:
          cpus: '1.50' # Hard cap: Server can never use more than 1.5 cores total
    volumes:
      # 1. HDD RAID for bulk storage (original photos/videos)
      - /mnt/btrfs-raid1/@media/immich/library:/data

      # 2. NVMe injections for speed (thumbnails, transcoded video, avatars)
      # PLEASE ADJUST THESE PATHS TO YOUR SYSTEM!
      - /mnt/nm790/@media/immich/library/thumbs:/data/thumbs
      - /mnt/nm790/@media/immich/library/encoded-video:/data/encoded-video
      - /mnt/nm790/@media/immich/library/profile:/data/profile
      
      - /etc/localtime:/etc/localtime:ro
    env_file:
      - .env
    depends_on:
      - redis
      - database
    restart: always
    # Hardware Acceleration (QuickSync) mapping
    devices:
      - /dev/dri:/dev/dri
    healthcheck:
      disable: false
    networks:
      - npm-network
      - immich-internal
      - immich-internet

  immich-machine-learning:
    container_name: immich-machine-learning
    # Using OpenVINO for Intel iGPU support
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-openvino
    # Pin to Cores 1-3
    cpuset: "1-3"
    deploy:
      resources:
        limits:
          cpus: '1.00' # ML is restricted to max 1 core total load
    shm_size: 1gb
    volumes:
      - model-cache:/cache
    environment:
      # Limit concurrency to keep the system responsive
      - MACHINE_LEARNING_WORKERS=1
      - OMP_NUM_THREADS=1
      - MKL_NUM_THREADS=1
    env_file:
      - .env
    restart: always
    # Hardware Acceleration (OpenVINO) mapping
    devices:
      - /dev/dri:/dev/dri
    healthcheck:
      disable: false
    networks:
      - immich-internal
      - immich-internet

  redis:
    container_name: immich-redis
    image: docker.io/valkey/valkey:9@sha256:fb8d272e529ea567b9bf1302245796f21a2672b8368ca3fcb938ac334e613c8f
    tmpfs:
      - /data
    healthcheck:
      test: redis-cli ping || exit 1
    restart: always
    networks:
      - immich-internal

  database:
    container_name: immich-postgres
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:bcf63357191b76a916ae5eb93464d65c07511da41e3bf7a8416db519b40b1c23
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      POSTGRES_INITDB_ARGS: '--data-checksums'
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    shm_size: 128mb
    restart: always
    networks:
      - immich-internal
      
volumes:
  model-cache:

networks:
  # External network for Reverse Proxy (e.g., Nginx Proxy Manager)
  # If you don't use a proxy, remove this and uncomment ports in immich-server
  npm-network:
    external: true
  immich-internal:
    name: immich-internal
    internal: true
  immich-internet:
    driver: bridge

[cedricwalter]

it is better to let immich use the default cpu scheduler and hog temporary all your cpu core. Cpu pinning is most of the time a bad idea...Let immich complete what has to be done, your initial load and forget it.

You should also really backed your claims with benchmarks, maybe the load is not any more of 16, but add another set of docker container and all these optimizations are done for nothing as core will be shared again.

Pinning becomes disadvantageous or difficult to manage in other situations:

• General-Purpose Microservices: For most standard, lightweight microservices or applications that aren't resource-heavy, the default CPU scheduler works efficiently and pinning is unnecessary.

• Increased Management Complexity: Manually managing CPU pins across many containers and VMs, especially as your setup grows, becomes a management challenge.

• If you pin a multi-threaded application to only one or a few cores, you may underutilize your system's total CPU capacity. You scarify one core for the reverse proxy but nginx or Traefik won't get sluggish if it share a core temporary with immich.

• If you pin a container to the same core(s) the host operating system (like unRAID OS) heavily favors (often CPU 0), it can cause system instability or an unresponsive user interface. A common recommendation is to leave core 0 (or core 0/1) unpinned/unisolated for the host OS's tasks.

• Some underlying file systems or host-level processes (like ZFS in certain configurations) might happily ignore the pinning and use any available core, which can defeat the purpose of isolation in docker. You use Btrfs but some other users may have a different outcome.