Skip to content
Klutch.sh Docs

Deploying LibrePhotos

Introduction

LibrePhotos is a powerful, self-hosted photo management system that brings Google Photos-like features to your own server. Using machine learning for facial recognition, object detection, and scene classification, LibrePhotos automatically organizes your photo library while keeping your memories completely private.

Forked from Ownphotos, LibrePhotos has evolved into a feature-rich platform with an active development community. The application uses Python and Django for the backend, with a React frontend providing a modern, responsive user interface.

Key highlights of LibrePhotos:

  • Facial Recognition: Automatically detect and group faces across your photo library
  • Object Detection: Identify objects, scenes, and locations in photos using AI
  • Timeline View: Browse photos chronologically with smart grouping
  • Map Integration: View photos on a map based on GPS metadata
  • Album Management: Create and organize albums manually or automatically
  • Search: Find photos by person, object, location, or date
  • Sharing: Share albums with other users or via public links
  • RAW Support: Handle RAW photo formats from various cameras
  • Video Support: Manage videos alongside photos
  • Multi-User: Support multiple users with separate libraries
  • Mobile Apps: Access your library from iOS and Android apps
  • Privacy-Focused: All processing happens on your server

This guide walks through deploying LibrePhotos on Klutch.sh using Docker and configuring it for your photo library.

Why Deploy LibrePhotos on Klutch.sh

Deploying LibrePhotos on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh builds LibrePhotos from your Dockerfile automatically. Push to GitHub, and your photo library deploys.

Persistent Storage: Attach persistent volumes for your photos, thumbnails, and database. Your library survives restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access to your photos.

GitHub Integration: Connect your repository for automatic redeployments on updates.

Scalable Resources: AI processing requires significant resources. Allocate CPU and memory based on library size.

Environment Variable Management: Securely store configuration without exposing credentials.

Custom Domains: Assign a custom domain for your photo library.

Always-On Availability: Your photo library remains accessible 24/7.

Prerequisites

Before deploying LibrePhotos on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • Basic familiarity with Docker and containerization concepts
  • A PostgreSQL database
  • Redis for caching and task queues
  • Sufficient storage for your photo library and generated thumbnails
  • (Optional) A custom domain for your LibrePhotos instance

Understanding LibrePhotos Architecture

LibrePhotos consists of multiple components:

Backend (Django): Python/Django application handling API requests and photo processing.

Frontend (React): Modern web interface for browsing and managing photos.

PostgreSQL: Database storing metadata, face encodings, and user data.

Redis: Message broker for background tasks and caching.

Worker Processes: Celery workers handling photo scanning, face detection, and AI processing.

Machine Learning Models: Pre-trained models for face recognition, object detection, and scene classification.

Preparing Your Repository

Repository Structure

librephotos-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

FROM reallibrephotos/librephotos:latest


# Environment configuration
ENV BACKEND_HOST=0.0.0.0
ENV BACKEND_PORT=8001
ENV DB_BACKEND=postgresql
ENV DB_HOST=${DB_HOST:-postgres}
ENV DB_PORT=${DB_PORT:-5432}
ENV DB_NAME=${DB_NAME:-librephotos}
ENV DB_USER=${DB_USER:-librephotos}
ENV DB_PASS=${DB_PASS}
ENV REDIS_HOST=${REDIS_HOST:-redis}
ENV REDIS_PORT=${REDIS_PORT:-6379}
ENV SECRET_KEY=${SECRET_KEY}
ENV MAPBOX_API_KEY=${MAPBOX_API_KEY:-}


# Create directories
RUN mkdir -p /data /protected_media /logs


# Expose ports
EXPOSE 8001


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=3 \
  CMD curl -f http://localhost:8001/api/health/ || exit 1

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local
__pycache__/

Environment Variables Reference

VariableRequiredDefaultDescription
DB_HOSTYespostgresPostgreSQL hostname
DB_PORTNo5432PostgreSQL port
DB_NAMENolibrephotosDatabase name
DB_USERYes-Database username
DB_PASSYes-Database password
REDIS_HOSTYesredisRedis hostname
SECRET_KEYYes-Django secret key
MAPBOX_API_KEYNo-Mapbox API key for maps
ALLOW_UPLOADNotrueAllow photo uploads

Deploying LibrePhotos on Klutch.sh

    Set Up PostgreSQL Database

    Deploy PostgreSQL with the required extensions. LibrePhotos needs a database for storing metadata and face encodings.

    Set Up Redis

    Deploy Redis for task queue management. LibrePhotos uses Celery with Redis for background processing.

    Generate a Secret Key

    Create a secure Django secret key:

    Terminal window
    python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'

    Push Your Repository to GitHub

    Terminal window
    git init
    git add Dockerfile .dockerignore README.md
    git commit -m "Initial LibrePhotos deployment configuration"
    git remote add origin https://github.com/yourusername/librephotos-deploy.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project named “librephotos” or “photos”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account and select your LibrePhotos repository.

    Configure HTTP Traffic

    In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 8001

    Set Environment Variables

    Add the following:

    VariableValue
    DB_HOSTYour PostgreSQL hostname
    DB_NAMElibrephotos
    DB_USERYour database username
    DB_PASSYour database password
    REDIS_HOSTYour Redis hostname
    SECRET_KEYYour generated secret key
    MAPBOX_API_KEYYour Mapbox API key (optional)

    Attach Persistent Volumes

    Mount PathRecommended SizePurpose
    /data100+ GBOriginal photo storage
    /protected_media50+ GBThumbnails and processed images
    /logs2 GBApplication logs

    Deploy Your Application

    Click Deploy to start the build process. Initial deployment may take time as ML models are downloaded.

    Create Admin User

    After deployment, create the admin account through the setup process or API.

Initial Configuration

Setting Up Your Library

Configure photo sources:

  1. Log in as administrator
  2. Go to Settings > Scan Directory
  3. Point to your photo directories
  4. Start the initial scan

Face Recognition Setup

Enable facial recognition:

  1. Navigate to Settings > Face Recognition
  2. Enable face detection
  3. Run face scan on your library
  4. Review and label detected faces

Map Configuration

Enable location features:

  1. Obtain a Mapbox API key
  2. Add to environment variables
  3. Restart the application
  4. View photos on the map

User Management

Set up additional users:

  1. Create accounts for family members
  2. Assign appropriate permissions
  3. Each user gets their own library or shared access

Using LibrePhotos

Browsing Photos

Navigate your library:

  1. Use the timeline view for chronological browsing
  2. Filter by date, person, or location
  3. View photos on the map
  4. Search for specific content

Albums and Organization

Create albums:

  1. Select photos to add
  2. Create new album or add to existing
  3. Set sharing permissions
  4. Generate sharing links if needed

Face Management

Organize people:

  1. Review auto-detected faces
  2. Label identified individuals
  3. Merge duplicate face clusters
  4. Search photos by person

Production Best Practices

Security Recommendations

  • Use strong passwords for all accounts
  • Keep LibrePhotos updated
  • Secure your PostgreSQL database
  • Consider access restrictions if public-facing

Performance Optimization

  • Allocate sufficient CPU for ML processing
  • Use SSD storage for better performance
  • Increase worker processes for faster scanning
  • Configure Redis for optimal caching

Backup Strategy

  1. Back up PostgreSQL database regularly
  2. Back up original photos separately
  3. The /protected_media directory can be regenerated
  4. Export face data if available

Troubleshooting

Photos Not Appearing

  • Verify scan directory path is correct
  • Check file permissions
  • Review scan logs for errors
  • Ensure supported file formats

Face Recognition Not Working

  • Check ML model downloads completed
  • Verify sufficient memory for processing
  • Review worker logs for errors
  • Manually trigger face scan

Slow Performance

  • Increase allocated resources
  • Check database query performance
  • Optimize Redis cache settings
  • Consider reducing concurrent workers

Additional Resources

Conclusion

Deploying LibrePhotos on Klutch.sh gives you a powerful, AI-enhanced photo management system with automatic builds and secure HTTPS access. With facial recognition, object detection, and intelligent organization, LibrePhotos provides Google Photos-like features while keeping your memories completely private.

Your photos deserve a home you control, and LibrePhotos on Klutch.sh provides the infrastructure to make that possible.