Immich Photo Management

intermediate

Immich self-hosted photo and video backup solution with ML-powered features.

[i]Overview

Immich is a rapidly evolving self-hosted photo and video backup solution that provides a compelling alternative to Google Photos. Developed with modern web technologies, Immich focuses on automatic mobile backup, machine learning-powered organization, and privacy-first photo management. The project has gained significant traction in the self-hosting community for its intuitive interface and comprehensive feature set that rivals commercial cloud photo services. This stack combines Immich's server and microservices architecture with PostgreSQL using the pgvecto-rs extension for vector similarity searches, Redis for caching and session management, and a dedicated machine learning service for AI-powered photo analysis. The pgvecto-rs PostgreSQL variant enables efficient similarity searches for duplicate detection and smart clustering, while Redis handles real-time operations like job queues and user sessions. The separate machine learning container processes face recognition, object detection, and CLIP embeddings for semantic search without impacting the main application performance. This configuration is ideal for families looking to replace Google Photos, photography enthusiasts managing large collections, or privacy-conscious users who want full control over their media. The machine learning capabilities provide automatic face grouping, object recognition, and smart search functionality while keeping all processing local. The multi-container architecture ensures that resource-intensive ML operations don't interfere with photo browsing and upload performance, making it suitable for everything from Raspberry Pi deployments to high-performance home servers.

[*]Key Features

[+]Automatic mobile backup with iOS and Android apps supporting background sync
[+]Face recognition and clustering with person identification across your photo library
[+]Object and scene detection for searching photos by content like 'beach', 'dog', or 'car'
[+]CLIP-based semantic search allowing natural language queries like 'sunset at the beach'
[+]Memories feature that automatically creates yearly photo compilations and highlights
[+]Live Photos support preserving the motion and audio from iPhone Live Photos
[+]Shared albums with granular permissions for family and friends collaboration
[+]Map view visualization for geotagged photos with clustering and timeline navigation

[#]Common Use Cases

[1]Family photo backup replacing Google Photos with unlimited storage and no privacy concerns
[2]Photography enthusiasts organizing large RAW and JPEG collections with AI-powered tagging
[3]Small businesses backing up product photos with automatic object detection for inventory
[4]Content creators managing video libraries with thumbnail generation and metadata extraction
[5]Privacy-focused individuals wanting full control over personal photos without cloud dependence
[6]Multi-user households with separate libraries and shared family albums
[7]Travel photography organization with automatic location clustering and timeline views

[!]Prerequisites

[!]Minimum 4GB RAM recommended for smooth machine learning operations and face recognition
[!]Docker host with at least 20GB free storage for application data and photo thumbnails
[!]Port 2283 available for web interface access and mobile app connectivity
[!]Understanding of environment variables for database credentials configuration
[!]Mobile device with iOS or Android for optimal automatic backup experience
[!]Basic familiarity with photo management concepts like albums, tags, and metadata

[!]

WARNING: For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

[$]docker-compose.yml

[docker-compose.yml]

1services: 
2  immich-server: 
3    image: ghcr.io/immich-app/immich-server:release
4    container_name: immich-server
5    command: ["start.sh", "immich"]
6    environment: 
7      - DB_HOSTNAME=postgres
8      - DB_USERNAME=${POSTGRES_USER}
9      - DB_PASSWORD=${POSTGRES_PASSWORD}
10      - DB_DATABASE_NAME=immich
11      - REDIS_HOSTNAME=redis
12      - UPLOAD_LOCATION=/usr/src/app/upload
13      - IMMICH_MACHINE_LEARNING_URL=http://immich-machine-learning:3003
14    volumes: 
15      - immich_upload:/usr/src/app/upload
16      - /etc/localtime:/etc/localtime:ro
17    ports: 
18      - "2283:3001"
19    depends_on: 
20      - postgres
21      - redis
22    networks: 
23      - immich-network
24
25  immich-microservices: 
26    image: ghcr.io/immich-app/immich-server:release
27    container_name: immich-microservices
28    command: ["start.sh", "microservices"]
29    environment: 
30      - DB_HOSTNAME=postgres
31      - DB_USERNAME=${POSTGRES_USER}
32      - DB_PASSWORD=${POSTGRES_PASSWORD}
33      - DB_DATABASE_NAME=immich
34      - REDIS_HOSTNAME=redis
35      - UPLOAD_LOCATION=/usr/src/app/upload
36      - IMMICH_MACHINE_LEARNING_URL=http://immich-machine-learning:3003
37    volumes: 
38      - immich_upload:/usr/src/app/upload
39      - /etc/localtime:/etc/localtime:ro
40    depends_on: 
41      - postgres
42      - redis
43    networks: 
44      - immich-network
45
46  immich-machine-learning: 
47    image: ghcr.io/immich-app/immich-machine-learning:release
48    container_name: immich-ml
49    volumes: 
50      - immich_ml_cache:/cache
51    networks: 
52      - immich-network
53
54  postgres: 
55    image: tensorchord/pgvecto-rs:pg14-v0.2.0
56    container_name: immich-db
57    environment: 
58      - POSTGRES_USER=${POSTGRES_USER}
59      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
60      - POSTGRES_DB=immich
61    volumes: 
62      - postgres_data:/var/lib/postgresql/data
63    networks: 
64      - immich-network
65
66  redis: 
67    image: redis:7-alpine
68    container_name: immich-redis
69    networks: 
70      - immich-network
71
72volumes: 
73  immich_upload: 
74  immich_ml_cache: 
75  postgres_data: 
76
77networks: 
78  immich-network: 
79    driver: bridge

[$].env Template

[.env]

1# Immich
2POSTGRES_USER=immich
3POSTGRES_PASSWORD=immich_password

[i]Usage Notes

[1]Web UI at http://localhost:2283
[2]Mobile apps available for iOS/Android
[3]ML features for face/object recognition
[4]Supports external libraries
[5]Check Immich docs for GPU acceleration

Individual Services(5 services)

Copy individual services to mix and match with your existing compose files.

immich-server

immich-server:
  image: ghcr.io/immich-app/immich-server:release
  container_name: immich-server
  command:
    - start.sh
    - immich
  environment:
    - DB_HOSTNAME=postgres
    - DB_USERNAME=${POSTGRES_USER}
    - DB_PASSWORD=${POSTGRES_PASSWORD}
    - DB_DATABASE_NAME=immich
    - REDIS_HOSTNAME=redis
    - UPLOAD_LOCATION=/usr/src/app/upload
    - IMMICH_MACHINE_LEARNING_URL=http://immich-machine-learning:3003
  volumes:
    - immich_upload:/usr/src/app/upload
    - /etc/localtime:/etc/localtime:ro
  ports:
    - "2283:3001"
  depends_on:
    - postgres
    - redis
  networks:
    - immich-network

immich-microservices

immich-microservices:
  image: ghcr.io/immich-app/immich-server:release
  container_name: immich-microservices
  command:
    - start.sh
    - microservices
  environment:
    - DB_HOSTNAME=postgres
    - DB_USERNAME=${POSTGRES_USER}
    - DB_PASSWORD=${POSTGRES_PASSWORD}
    - DB_DATABASE_NAME=immich
    - REDIS_HOSTNAME=redis
    - UPLOAD_LOCATION=/usr/src/app/upload
    - IMMICH_MACHINE_LEARNING_URL=http://immich-machine-learning:3003
  volumes:
    - immich_upload:/usr/src/app/upload
    - /etc/localtime:/etc/localtime:ro
  depends_on:
    - postgres
    - redis
  networks:
    - immich-network

immich-machine-learning

immich-machine-learning:
  image: ghcr.io/immich-app/immich-machine-learning:release
  container_name: immich-ml
  volumes:
    - immich_ml_cache:/cache
  networks:
    - immich-network

postgres

postgres:
  image: tensorchord/pgvecto-rs:pg14-v0.2.0
  container_name: immich-db
  environment:
    - POSTGRES_USER=${POSTGRES_USER}
    - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    - POSTGRES_DB=immich
  volumes:
    - postgres_data:/var/lib/postgresql/data
  networks:
    - immich-network

redis

redis:
  image: redis:7-alpine
  container_name: immich-redis
  networks:
    - immich-network

[>]Quick Start

[terminal]

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  immich-server:
5    image: ghcr.io/immich-app/immich-server:release
6    container_name: immich-server
7    command: ["start.sh", "immich"]
8    environment:
9      - DB_HOSTNAME=postgres
10      - DB_USERNAME=${POSTGRES_USER}
11      - DB_PASSWORD=${POSTGRES_PASSWORD}
12      - DB_DATABASE_NAME=immich
13      - REDIS_HOSTNAME=redis
14      - UPLOAD_LOCATION=/usr/src/app/upload
15      - IMMICH_MACHINE_LEARNING_URL=http://immich-machine-learning:3003
16    volumes:
17      - immich_upload:/usr/src/app/upload
18      - /etc/localtime:/etc/localtime:ro
19    ports:
20      - "2283:3001"
21    depends_on:
22      - postgres
23      - redis
24    networks:
25      - immich-network
26
27  immich-microservices:
28    image: ghcr.io/immich-app/immich-server:release
29    container_name: immich-microservices
30    command: ["start.sh", "microservices"]
31    environment:
32      - DB_HOSTNAME=postgres
33      - DB_USERNAME=${POSTGRES_USER}
34      - DB_PASSWORD=${POSTGRES_PASSWORD}
35      - DB_DATABASE_NAME=immich
36      - REDIS_HOSTNAME=redis
37      - UPLOAD_LOCATION=/usr/src/app/upload
38      - IMMICH_MACHINE_LEARNING_URL=http://immich-machine-learning:3003
39    volumes:
40      - immich_upload:/usr/src/app/upload
41      - /etc/localtime:/etc/localtime:ro
42    depends_on:
43      - postgres
44      - redis
45    networks:
46      - immich-network
47
48  immich-machine-learning:
49    image: ghcr.io/immich-app/immich-machine-learning:release
50    container_name: immich-ml
51    volumes:
52      - immich_ml_cache:/cache
53    networks:
54      - immich-network
55
56  postgres:
57    image: tensorchord/pgvecto-rs:pg14-v0.2.0
58    container_name: immich-db
59    environment:
60      - POSTGRES_USER=${POSTGRES_USER}
61      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
62      - POSTGRES_DB=immich
63    volumes:
64      - postgres_data:/var/lib/postgresql/data
65    networks:
66      - immich-network
67
68  redis:
69    image: redis:7-alpine
70    container_name: immich-redis
71    networks:
72      - immich-network
73
74volumes:
75  immich_upload:
76  immich_ml_cache:
77  postgres_data:
78
79networks:
80  immich-network:
81    driver: bridge
82EOF
83
84# 2. Create the .env file
85cat > .env << 'EOF'
86# Immich
87POSTGRES_USER=immich
88POSTGRES_PASSWORD=immich_password
89EOF
90
91# 3. Start the services
92docker compose up -d
93
94# 4. View logs
95docker compose logs -f

[>]One-Liner

Run this command to download and set up the recipe in one step:

[terminal]

1curl -fsSL https://docker.recipes/api/recipes/immich-photos/run | bash

[?]Troubleshooting

[!]Machine learning container consuming high CPU: Adjust IMMICH_MACHINE_LEARNING_WORKERS environment variable to limit concurrent processing
[!]Mobile app failing to backup: Verify port 2283 is accessible from mobile network and check background app refresh permissions
[!]Face recognition not working: Ensure immich-machine-learning container has sufficient memory allocation (minimum 2GB recommended)
[!]Upload location permission errors: Verify Docker daemon has read/write access to mounted volume directories
[!]PostgreSQL connection failures: Check POSTGRES_USER and POSTGRES_PASSWORD environment variables match between services
[!]Large library causing slow performance: Enable thumbnail generation priority and consider increasing Redis memory allocation

Community Notes

Loading notes...

## Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

## Components

immich-serverimmich-machine-learningpostgresredis

## Tags

#immich#photos#backup#google-photos-alternative#machine-learning

## Category

Media & Entertainment

## Related

Shortcuts: C CopyF FavoriteD Download