Deployment Guide

Relevant source files

• docker/docker-compose.dev.yml
• docker/docker-compose.prod.yml
• docker/docker-compose.rootless.yml
• docker/docker-compose.yml
• docker/example.env
• docker/hwaccel.ml.yml
• docker/hwaccel.transcoding.yml
• docs/docs/administration/postgres-standalone.md
• docs/docs/features/hardware-transcoding.md
• docs/docs/features/ml-hardware-acceleration.md
• docs/docs/install/all-in-one.md
• docs/docs/install/docker-compose.mdx
• docs/docs/install/environment-variables.md
• docs/docs/install/kubernetes.md
• docs/docs/install/portainer.md
• docs/docs/install/post-install.mdx
• docs/docs/install/requirements.md
• docs/docs/install/script.md
• docs/docs/install/truenas.md
• docs/docs/install/unraid.md
• docs/docs/install/upgrading.md
• docs/docs/partials/_server-backup.md
• e2e/docker-compose.dev.yml
• e2e/docker-compose.yml
• e2e/src/utils.ts
• install.sh
• machine-learning/Dockerfile
• machine-learning/uv.lock
• server/Dockerfile
• server/Dockerfile.dev
• server/bin/get-cpus.sh
• server/bin/immich-admin
• server/bin/immich-dev
• server/bin/start.sh
• web/bin/immich-web

This document provides a comprehensive overview for deploying Immich in production environments. It covers the containerized architecture, core service setup, hardware considerations, and platform-specific options. Detailed instructions and configurations for specific deployment scenarios are available in linked child pages.

For development environment setup, see Development Environment Setup. For hardware acceleration options, see Hardware Acceleration. For environment and service configuration, see Configuration. For maintenance and backup procedures, see Maintenance and Backup.

---

Deployment Architecture

Immich employs a microservices design with each major component running in a dedicated container. Docker Compose orchestrates these containers, managing dependencies, volumes, and networking.

High-level Deployment Architecture Diagram

This diagram maps the high-level service names used in deployment to container names, ports, and volume mounts.

Sources: docker/docker-compose.yml10-77 docker/docker-compose.prod.yml10-108

---

System Requirements

To run Immich effectively in production, recommended hardware specifications include:

• Operating System: A Linux or Unix-like 64-bit OS. While Windows and macOS are supported for development, production deployments should prefer Linux-based hosts for stability and performance.
• Memory: Minimum 6GB RAM; 8GB or more recommended. Systems with only 4GB may struggle, especially if machine learning features are enabled.
• CPU: Minimum 2 cores, preferably 4 or more. For amd64 architectures, the CPU must support at least x86-64-v2 instruction set.
• Storage: SSD storage is critical for the PostgreSQL database performance, mounted at ${DB_DATA_LOCATION}.

Refer to Installation Requirements for full details.

Sources: docs/docs/install/requirements.md11-42

---

Core Services Overview

Immich is composed of several core services, each responsible for specific functionality within the system.

immich-server

• This is the main backend API and service orchestrator built with NestJS.
• It handles the REST API, authentication, asset processing, and job management.
• Uses BullMQ workers internally for background processing.
• Depends on Redis for caching and job queues.
• Mounts uploaded media files from ${UPLOAD_LOCATION} to /data.
• Exposes port 2283 for client connections.
• Reads configuration primarily from a .env file.

Immich Server Container Diagram

• Image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
• Container Name: immich_server
• Port: 2283
• Restart: always

Sources: docker/docker-compose.yml13-32 docker/docker-compose.prod.yml13-35

---

immich-machine-learning

• Provides AI-powered features such as face detection, smart search using CLIP embeddings.
• Runs as a separate service with its own container.
• Caches downloaded ML models in the named volume model-cache.
• Supports hardware acceleration by selecting image tags suffixed with device names, e.g. -cuda, -openvino.
• Exposes port 3003 for the server to communicate ML inference requests.

Refer to Hardware Acceleration for detailed device-specific setup.

Sources: docker/docker-compose.yml34-49 docker/docker-compose.prod.yml36-56 machine-learning/Dockerfile1-170

---

PostgreSQL Database

• Immich requires PostgreSQL 14 with advanced vector extensions for smart search and facial recognition.
• Uses a custom image ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0 which bundles pgvector and VectorChord extensions.
• Mounts persistent storage at ${DB_DATA_LOCATION} inside container at /var/lib/postgresql/data.
• Sets shm_size to at least 128MB, a requirement for vector operations.
• Uses --data-checksums to improve data integrity.
• Supports connecting to pre-existing Postgres servers. See the child wiki page for details.

Sources: docker/docker-compose.yml57-73 docs/docs/administration/postgres-standalone.md

---

Redis

• Provides caching and messaging queues for the background job workers.
• Uses the stable image docker.io/valkey/valkey:9.
• Healthchecks ensure Redis availability to the server.

---

Optional Monitoring Services

• immich-prometheus: Exposes internal metrics for performance and system health.
• immich-grafana: Provides a web interface dashboard for Prometheus metrics.

These services are optional but recommended for production monitoring setups.

---

Platform and Deployment Variations

Immich deployment is flexible to support various environments:

Platform	Deployment Method	Notes
Standard Linux	Docker Compose (recommended)	Use the official release Compose file.
Unraid	Compose Manager	Requires mapping UPLOAD_LOCATION to /mnt/user/... accordingly.
TrueNAS	Community App / Jail	Requires dedicated ownership of pgData dataset by netdata user (UID 999).
Rootless Docker	docker-compose.rootless.yml	Runs containers as non-root user 1000:1000, with reduced capabilities.
Portainer	Docker Stacks	Deploy via Portainer UI, replace env vars in stack.env.

Refer to the platform-specific installation guides for exact steps and limitations.

Sources: docs/docs/install/unraid.md docs/docs/install/truenas.md docker/docker-compose.rootless.yml1-98 docs/docs/install/portainer.md

---

Upgrading Immich

To upgrade Immich services to a new version release, simply pull new images and restart the stack:

This will pull updated container images and recreate the containers with minimal downtime.

A convenience installation script exists for new installations on Linux to automate initial setup and secure environment creation: see install.sh for details.

---

Further Deployment Details and Child Pages

This guide provides a high-level perspective focused on Docker Compose container orchestration and service relationships. Detailed deployment scenarios, configuration options, and maintenance operations are covered extensively in the following child pages:

• Docker Deployment
  Explains Docker Compose setup, service scaling, volume configuration, and reverse proxy integration with nginx, Traefik, or Caddy.

• Hardware Acceleration
  Covers setup of GPU/accelerator options for machine learning including CUDA, OpenVINO, ARM NN, RKNN, and ROCm.

• Configuration
  Documents all environment variables, storage paths, and runtime service settings for fine-tuning Immich deployment.

• Maintenance and Backup
  Describes maintenance mode, automated database backup and restore procedures, and monitoring capabilities.

---

This structured approach allows users to start with this consolidated deployment overview and dive into specific topics via the linked child pages tailored to their environment and needs.

---

Sources:

• docker/docker-compose.yml10-77 docker/docker-compose.prod.yml10-108 docker/server/Dockerfile1-122 machine-learning/Dockerfile1-170 docs/docs/install/requirements.md11-42 docs/docs/administration/postgres-standalone.md docs/docs/install/unraid.md docs/docs/install/truenas.md docker/docker-compose.rootless.yml1-98 docs/docs/install/portainer.md install.sh5-34