# Immich Photo Management

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

- Category: Media & Entertainment
- Difficulty: intermediate
- Components: immich-server, immich-machine-learning, postgres, redis
- Tags: immich, photos, backup, google-photos-alternative, machine-learning
- Source: https://docker.recipes/media/immich-photos

## 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.

## 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

## Use cases

- Family photo backup replacing Google Photos with unlimited storage and no privacy concerns
- Photography enthusiasts organizing large RAW and JPEG collections with AI-powered tagging
- Small businesses backing up product photos with automatic object detection for inventory
- Content creators managing video libraries with thumbnail generation and metadata extraction
- Privacy-focused individuals wanting full control over personal photos without cloud dependence
- Multi-user households with separate libraries and shared family albums
- 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

## docker-compose.yml

```yaml
services:
  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:
    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:
    image: ghcr.io/immich-app/immich-machine-learning:release
    container_name: immich-ml
    volumes:
      - immich_ml_cache:/cache
    networks:
      - immich-network

  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:
    image: redis:7-alpine
    container_name: immich-redis
    networks:
      - immich-network

volumes:
  immich_upload:
  immich_ml_cache:
  postgres_data:

networks:
  immich-network:
    driver: bridge
```

## .env

```bash
# Immich
POSTGRES_USER=immich
POSTGRES_PASSWORD=immich_password
```

## Usage notes

- Web UI at http://localhost:2283
- Mobile apps available for iOS/Android
- ML features for face/object recognition
- Supports external libraries
- Check Immich docs for GPU acceleration

## 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

