docker.recipes

Immich

intermediate

High performance self-hosted photo and video backup.

Overview

Immich is a high-performance, self-hosted photo and video backup solution designed as a privacy-focused alternative to Google Photos. Built with a modern TypeScript and Dart stack, Immich provides automatic mobile backup capabilities with advanced machine learning features for face recognition, object detection, and intelligent search. The application has gained significant traction in the self-hosting community for its rapid development pace and polished user experience that closely mirrors commercial cloud photo services. This stack combines Immich's server component with a specialized machine learning service, PostgreSQL with vector extensions, and Redis for caching and job queuing. The immich-server handles the web interface and API endpoints, while immich-machine-learning processes photos for face recognition and CLIP-based semantic search using the pgvecto-rs PostgreSQL extension for efficient vector similarity operations. Redis manages background job queues for thumbnail generation, metadata extraction, and ML processing tasks. This configuration is ideal for families wanting to centralize photo storage, privacy-conscious users migrating from Google Photos, and tech enthusiasts running home labs. The stack provides enterprise-grade photo management with features like multi-user support, album sharing, and geotagged photo mapping, while maintaining complete control over your data. The automatic mobile backup functionality makes it particularly valuable for households with multiple smartphones generating hundreds of photos monthly.

Key Features

  • Automatic mobile backup from iOS and Android apps with background sync
  • Face recognition and grouping powered by machine learning models
  • CLIP-based semantic search allowing natural language photo queries
  • Live Photos support preserving motion and audio from iPhone captures
  • Interactive map view displaying geotagged photos by location
  • Memories feature creating automatic slideshows and yearly recaps
  • External library integration for importing existing NAS photo collections
  • Multi-user support with individual libraries and sharing permissions

Common Use Cases

  • 1Family photo centralization replacing iCloud or Google Photos subscriptions
  • 2Privacy-focused photo backup for users concerned about cloud data mining
  • 3Home lab photo server with external library import from existing NAS storage
  • 4Small business photo asset management with team sharing capabilities
  • 5Photography enthusiast backup with high-resolution RAW file support
  • 6Multi-generational family archives with face recognition across decades
  • 7Travel photo organization with automatic geotagging and map visualization

Prerequisites

  • Minimum 4GB RAM recommended for ML processing and face recognition
  • At least 100GB available storage space for photo uploads and database
  • Port 2283 available for web interface access
  • Mobile device with iOS or Android for automatic backup functionality
  • Basic understanding of environment variables for database password configuration
  • Network access from mobile devices to Docker host for backup uploads

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    restart: unless-stopped
6    ports: 
7      - "2283:3001"
8    environment: 
9      DB_HOSTNAME: database
10      DB_USERNAME: postgres
11      DB_PASSWORD: ${DB_PASSWORD}
12      DB_DATABASE_NAME: immich
13      REDIS_HOSTNAME: redis
14    volumes: 
15      - immich_upload:/usr/src/app/upload
16    depends_on: 
17      - redis
18      - database
19
20  immich-machine-learning: 
21    image: ghcr.io/immich-app/immich-machine-learning:release
22    container_name: immich-ml
23    restart: unless-stopped
24    volumes: 
25      - immich_ml_cache:/cache
26
27  redis: 
28    image: redis:7-alpine
29    container_name: immich-redis
30    restart: unless-stopped
31
32  database: 
33    image: tensorchord/pgvecto-rs:pg14-v0.2.0
34    container_name: immich-db
35    restart: unless-stopped
36    environment: 
37      POSTGRES_USER: postgres
38      POSTGRES_PASSWORD: ${DB_PASSWORD}
39      POSTGRES_DB: immich
40    volumes: 
41      - immich_db:/var/lib/postgresql/data
42
43volumes: 
44  immich_upload: 
45  immich_ml_cache: 
46  immich_db:

.env Template

.env
1DB_PASSWORD=changeme

Usage Notes

  1. 1Docs: https://immich.app/docs/overview/introduction
  2. 2Access at http://localhost:2283 - create admin on first visit
  3. 3Mobile apps (iOS/Android) for automatic photo backup
  4. 4ML container provides face recognition and CLIP search
  5. 5Uses pgvecto.rs for efficient vector similarity search
  6. 6External library support for existing NAS photo storage

Individual Services(4 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
  restart: unless-stopped
  ports:
    - "2283:3001"
  environment:
    DB_HOSTNAME: database
    DB_USERNAME: postgres
    DB_PASSWORD: ${DB_PASSWORD}
    DB_DATABASE_NAME: immich
    REDIS_HOSTNAME: redis
  volumes:
    - immich_upload:/usr/src/app/upload
  depends_on:
    - redis
    - database
immich-machine-learning
immich-machine-learning:
  image: ghcr.io/immich-app/immich-machine-learning:release
  container_name: immich-ml
  restart: unless-stopped
  volumes:
    - immich_ml_cache:/cache
redis
redis:
  image: redis:7-alpine
  container_name: immich-redis
  restart: unless-stopped
database
database:
  image: tensorchord/pgvecto-rs:pg14-v0.2.0
  container_name: immich-db
  restart: unless-stopped
  environment:
    POSTGRES_USER: postgres
    POSTGRES_PASSWORD: ${DB_PASSWORD}
    POSTGRES_DB: immich
  volumes:
    - immich_db:/var/lib/postgresql/data

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    restart: unless-stopped
8    ports:
9      - "2283:3001"
10    environment:
11      DB_HOSTNAME: database
12      DB_USERNAME: postgres
13      DB_PASSWORD: ${DB_PASSWORD}
14      DB_DATABASE_NAME: immich
15      REDIS_HOSTNAME: redis
16    volumes:
17      - immich_upload:/usr/src/app/upload
18    depends_on:
19      - redis
20      - database
21
22  immich-machine-learning:
23    image: ghcr.io/immich-app/immich-machine-learning:release
24    container_name: immich-ml
25    restart: unless-stopped
26    volumes:
27      - immich_ml_cache:/cache
28
29  redis:
30    image: redis:7-alpine
31    container_name: immich-redis
32    restart: unless-stopped
33
34  database:
35    image: tensorchord/pgvecto-rs:pg14-v0.2.0
36    container_name: immich-db
37    restart: unless-stopped
38    environment:
39      POSTGRES_USER: postgres
40      POSTGRES_PASSWORD: ${DB_PASSWORD}
41      POSTGRES_DB: immich
42    volumes:
43      - immich_db:/var/lib/postgresql/data
44
45volumes:
46  immich_upload:
47  immich_ml_cache:
48  immich_db:
49EOF
50
51# 2. Create the .env file
52cat > .env << 'EOF'
53DB_PASSWORD=changeme
54EOF
55
56# 3. Start the services
57docker compose up -d
58
59# 4. View logs
60docker 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/run | bash

Troubleshooting

  • Face recognition not working: Ensure immich-machine-learning container has adequate RAM allocation and check logs for model download failures
  • Mobile app upload failures: Verify port 2283 is accessible from mobile network and check firewall rules on Docker host
  • Database connection errors: Confirm DB_PASSWORD environment variable matches between immich-server and database containers
  • ML processing stuck: Restart immich-machine-learning container and check available disk space in immich_ml_cache volume
  • External library import fails: Verify file permissions and ensure immich-server container can read mounted photo directories
  • Search not returning results: Wait for initial ML processing to complete and check pgvecto-rs extension is properly loaded in PostgreSQL

Community Notes

Loading...
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-mlpostgresredis

Tags

#immich#photos#backup#google-photos

Category

Media & Entertainment

Related Recipes

Ad Space