# Immich Self-Hosted Photos

> Immich Google Photos alternative with ML.

- Category: Media & Entertainment
- Difficulty: intermediate
- Components: immich, postgresql, redis, machine-learning
- Tags: photos, immich, backup, mobile
- Source: https://docker.recipes/media/immich-photos-stack

## Overview

Immich is a modern, self-hosted photo and video backup solution that provides a Google Photos-like experience while maintaining complete control over your personal media. Developed as a privacy-focused alternative to cloud photo services, Immich combines automatic mobile backup with advanced machine learning capabilities for face recognition, object detection, and intelligent search. Unlike commercial solutions that impose storage limits and privacy concerns, Immich gives users unlimited storage capacity on their own hardware with sophisticated features like timeline views, album sharing, and geotagged photo mapping.

This deployment creates a complete Immich infrastructure using four specialized containers: immich-server handles the web interface and API operations, immich-machine-learning provides AI-powered face recognition and object detection, immich-db runs a PostgreSQL database with vector search extensions (pgvecto-rs) for storing metadata and enabling semantic search, and immich-redis manages caching and background job queues. The machine learning container operates independently to process photos for tagging and facial recognition without impacting the main server performance.

This stack is ideal for families wanting to replace Google Photos, photographers managing large collections, or privacy-conscious users seeking complete control over their media. The combination of automatic mobile backup, advanced search capabilities, and multi-user support makes it particularly valuable for households or small teams who want professional-grade photo management without recurring subscription costs or data privacy compromises.

## Features

- Automatic mobile backup from iOS and Android apps with background synchronization
- Machine learning-powered face recognition and object detection for intelligent photo organization
- Vector-based semantic search using pgvecto-rs PostgreSQL extension for finding photos by content
- Interactive timeline with memories feature showing photos from previous years
- Geotagged photo mapping with location-based browsing and search
- Multi-user support with individual libraries and shared album capabilities
- Live photos support preserving motion from iPhone and compatible Android devices
- Bulk metadata extraction and duplicate detection for existing photo libraries

## Use cases

- Family photo backup replacing Google Photos with unlimited storage and privacy control
- Professional photographer portfolio management with client access and album sharing
- Small business asset management for storing product photos and marketing materials
- Travel documentation with automatic geotagging and location-based photo organization
- Homelab media server integration for comprehensive personal data sovereignty
- Multi-generational family archive with face recognition connecting photos across decades
- Photography enthusiast collection management with advanced search and tagging capabilities

## Prerequisites

- Minimum 4GB RAM recommended for machine learning processing and PostgreSQL operations
- Port 2283 available for Immich web interface access
- Sufficient storage space for photo uploads in the configured upload directory
- Mobile device compatibility for iOS 12+ or Android 8+ for automatic backup features
- Understanding of photo library organization for optimal initial setup and user management
- Network access planning for mobile app connectivity and potential external access configuration

## docker-compose.yml

```yaml
services:
  immich-server:
    image: ghcr.io/immich-app/immich-server:release
    container_name: immich-server
    restart: unless-stopped
    ports:
      - "${IMMICH_PORT:-2283}:2283"
    environment:
      - DB_HOSTNAME=immich-db
      - DB_USERNAME=${DB_USER}
      - DB_PASSWORD=${DB_PASSWORD}
      - DB_DATABASE_NAME=immich
      - REDIS_HOSTNAME=immich-redis
    volumes:
      - ${UPLOAD_PATH:-./uploads}:/usr/src/app/upload
    depends_on:
      - immich-db
      - immich-redis

  immich-machine-learning:
    image: ghcr.io/immich-app/immich-machine-learning:release
    container_name: immich-ml
    restart: unless-stopped
    volumes:
      - model_cache:/cache

  immich-db:
    image: tensorchord/pgvecto-rs:pg15-v0.2.0
    container_name: immich-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=immich
    volumes:
      - immich_db_data:/var/lib/postgresql/data

  immich-redis:
    image: redis:7-alpine
    container_name: immich-redis
    restart: unless-stopped

volumes:
  immich_db_data:
  model_cache:
```

## .env

```bash
# Immich Photos
IMMICH_PORT=2283
UPLOAD_PATH=./uploads
DB_USER=immich
DB_PASSWORD=immich_password
```

## Usage notes

- Immich at http://localhost:2283
- Download mobile apps for backup
- ML container for face recognition
- Uses pgvecto-rs for vector search

## Troubleshooting

- Mobile app cannot connect to server: Verify port 2283 is accessible and check firewall settings, ensure UPLOAD_PATH directory has proper write permissions
- Machine learning face recognition not working: Check that immich-machine-learning container has sufficient memory allocation and model_cache volume is properly mounted
- Database connection errors in immich-server: Verify DB_USER and DB_PASSWORD environment variables match between immich-server and immich-db services
- Slow photo upload and processing: Monitor Redis performance and consider increasing memory allocation for immich-redis container caching
- Search functionality not finding photos: Ensure pgvecto-rs extension is properly loaded in PostgreSQL and vector indexing has completed for uploaded photos

