# LibrePhotos

> Self-hosted photo management with AI features.

- Category: Media & Entertainment
- Difficulty: advanced
- Components: librephotos, postgres, redis
- Tags: librephotos, photos, ai, gallery
- Source: https://docker.recipes/media/librephotos

## Overview

LibrePhotos is a self-hosted photo management platform that serves as a privacy-focused alternative to Google Photos, offering AI-powered features like facial recognition, object detection, and automatic photo organization. Originally developed as an open-source solution for users who want complete control over their photo libraries, LibrePhotos leverages machine learning models to automatically categorize and search through thousands of photos without sending data to external services. This Docker stack combines LibrePhotos with PostgreSQL for robust metadata storage and Redis for high-performance caching and task queue management. The PostgreSQL database handles complex relational queries for photo metadata, facial recognition data, and user management, while Redis accelerates the AI processing pipeline by caching face embeddings and managing background tasks for photo analysis. This combination provides photographers, families, and privacy-conscious users with a powerful alternative to cloud-based photo services, offering features like automatic face clustering, location-based organization, duplicate detection, and full-text search across photo metadata while maintaining complete data ownership and privacy.

## Features

- AI-powered facial recognition with automatic person clustering using deep learning models
- Object and scene detection with automatic tagging based on image content analysis
- PostgreSQL-backed metadata storage with JSONB support for flexible photo attributes and geospatial indexing
- Redis-accelerated face embedding cache for sub-second similarity searches across photo collections
- Automatic photo timeline generation with intelligent date/time extraction from EXIF data
- Duplicate photo detection using perceptual hashing algorithms
- Full-text search across photo metadata, locations, and AI-generated tags
- Background task processing for batch photo analysis and thumbnail generation

## Use cases

- Family photo archival with automatic face tagging and person-based photo organization
- Photography enthusiasts managing large RAW and JPEG collections with metadata preservation
- Small businesses organizing product photography with automatic object detection and tagging
- Privacy-focused individuals migrating from Google Photos while retaining AI features
- Home media servers providing Netflix-style photo browsing for household members
- Digital asset management for creative agencies with AI-powered content discovery
- Personal photo backup solutions with intelligent organization and search capabilities

## Prerequisites

- Docker host with minimum 4GB RAM (8GB+ recommended for AI processing)
- 50GB+ available storage for photo library, database, and generated thumbnails
- Port 3000 available for frontend web interface access
- Basic understanding of photo management workflows and EXIF metadata concepts
- CPU with AVX instruction set support for optimal machine learning model performance
- Existing photo collection organized in accessible directory structure

## docker-compose.yml

```yaml
services:
  frontend:
    image: reallibrephotos/librephotos-frontend:latest
    container_name: librephotos-frontend
    restart: unless-stopped
    ports:
      - "3000:3000"
    depends_on:
      - backend

  backend:
    image: reallibrephotos/librephotos:latest
    container_name: librephotos-backend
    restart: unless-stopped
    environment:
      SECRET_KEY: ${SECRET_KEY}
      BACKEND_HOST: backend
      DB_BACKEND: postgresql
      DB_NAME: librephotos
      DB_USER: librephotos
      DB_PASS: ${DB_PASSWORD}
      DB_HOST: db
      REDIS_HOST: redis
      ADMIN_EMAIL: ${ADMIN_EMAIL}
      ADMIN_USERNAME: admin
      ADMIN_PASSWORD: ${ADMIN_PASSWORD}
    volumes:
      - librephotos_data:/data
      - /path/to/photos:/photos
    depends_on:
      - db
      - redis

  db:
    image: postgres:15-alpine
    container_name: librephotos-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: librephotos
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: librephotos
    volumes:
      - librephotos_db:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    container_name: librephotos-redis

volumes:
  librephotos_data:
  librephotos_db:
```

## .env

```bash
SECRET_KEY=generate-long-random-key
DB_PASSWORD=changeme
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=changeme
```

## Usage notes

- Docs: https://docs.librephotos.com/
- Frontend at http://localhost:3000, backend at :8001/api
- Login with configured admin credentials on first visit
- Scan photos: User > Scan Photos after mounting library
- Face recognition and object detection (resource intensive)
- Google Photos alternative with similar clustering features

## Troubleshooting

- Face recognition not working: Ensure photos have clear faces and enable face detection in settings, check backend logs for model loading errors
- High memory usage during photo scan: Reduce concurrent workers in backend environment or increase available RAM, face detection is memory-intensive
- Photos not appearing after scan: Verify photo directory permissions and check for supported file formats (JPEG, PNG, TIFF, RAW)
- Redis connection errors: Ensure Redis container is healthy and reachable, restart backend service if connection pool is exhausted
- PostgreSQL connection timeout: Check database container resources and increase connection limits if handling large photo libraries
- Slow thumbnail generation: Enable hardware acceleration if available or reduce thumbnail quality settings in backend configuration

