LibrePhotos

LibrePhotos is a full‑stack, self‑hosted photo management platform built to replace proprietary cloud services with an open‑source alternative. From a technical standpoint, it ingests media files from arbitrary directories, extracts rich metadata (EXIF, GPS, timestamps), and builds an index that powers faceted search, semantic queries, and auto‑generated albums. The core of the application is a RESTful API that exposes image collections, face clusters, and metadata filters to clients such as the web UI or third‑party integrations. The API follows standard JSON:API conventions, enabling developers to build custom front‑ends or automate cataloging workflows without touching the codebase.

Architecture

LibrePhotos is written in Python 3.11 and leverages the FastAPI framework for its HTTP layer, providing asynchronous request handling and automatic OpenAPI documentation. The persistence layer is PostgreSQL 15, accessed through SQLAlchemy ORM; a dedicated media table stores file paths, while auxiliary tables hold face embeddings, scene tags, and reverse‑geocoded locations. Media processing is decoupled via Celery workers that consume a Redis queue; each worker performs heavy tasks such as image conversion (ImageMagick), video transcoding (FFmpeg), and machine‑learning inference (face_recognition, scikit‑learn + hdbscan, im2txt). This producer/consumer model keeps the API responsive while scaling horizontally by adding more worker nodes.

The front‑end is a Vue 3 single‑page application that communicates with the API over HTTPS. Authentication uses OAuth2 Password Grant with JSON Web Tokens, and role‑based access controls are enforced at the API layer. The entire stack is Docker‑ready: a multi‑service Compose file orchestrates the FastAPI app, PostgreSQL, Redis, and optional Nginx reverse proxy. For production, Kubernetes manifests are available, allowing developers to deploy LibrePhotos on any cloud provider or bare‑metal cluster with minimal custom configuration.

Core Capabilities

• Media ingestion & indexing: Recursive filesystem scans, incremental updates via file‑watcher hooks.
• Metadata extraction: ExifTool integration exposes camera settings, GPS coordinates, and timestamps to the database.
• Computer‑vision pipelines: Face detection (face_recognition), face clustering (hdbscan + sklearn), scene classification (Places365), and object detection via TensorFlow‑Lite models.
• Semantic search: A vector index (FAISS) stores image embeddings from im2txt, enabling caption‑based queries.
• Event & album generation: Algorithms that group photos by temporal proximity and location (e.g., “Thursday in Berlin”) produce auto‑created albums.
• Reverse geocoding: Geopy fetches human‑readable place names for GPS tags.
• API hooks & webhooks: Endpoints to trigger re‑indexing, receive notifications on new media, and expose custom search filters.

Developers can extend the API by adding new endpoints or creating custom Celery tasks that consume the existing media queue. The modular design encourages plugging in alternative ML models or swapping PostgreSQL for CockroachDB without changing the core logic.

Deployment & Infrastructure

LibrePhotos is designed to run on any Linux distribution with Docker support. The official container image is built on Alpine, reducing attack surface and footprint to ~200 MB. For high‑availability setups, the Celery workers can be horizontally scaled; Redis is typically deployed in a Sentinel cluster to avoid single‑point failures. PostgreSQL can be configured with logical replication for read replicas, allowing API nodes to serve search queries from a local copy. The optional Nginx reverse proxy handles TLS termination and can be integrated with Let’s Encrypt for automated certificates.

Because the heavy processing is offloaded to Celery, a single machine can serve small to medium deployments (tens of thousands of images) comfortably. For enterprise‑grade workloads, a Kubernetes deployment can run the API as stateless pods behind an Ingress controller, while Redis and PostgreSQL are provisioned as StatefulSets. The entire stack is fully container‑native, making CI/CD pipelines straightforward and enabling rapid rollbacks.

Integration & Extensibility

LibrePhotos exposes a well‑documented OpenAPI spec; developers can generate client SDKs in any language using tools like Swagger Codegen or OpenAPI‑Generator. The plugin system is currently based on Python entry points: third‑party packages can register new Celery tasks, database models, or API routers. Webhooks are available for events such as “media‑added” or “album‑created,” allowing external services (e.g., a CI pipeline that uploads images to the gallery) to react automatically. The front‑end is also open source, so custom UI components can be added or replaced without affecting the API.

The project’s translation infrastructure (Weblate) demonstrates its commitment to localization, and developers can contribute new language packs or UI text via the same workflow. Continuous integration tests cover API endpoints and worker logic, ensuring that extensions do not regress core functionality.

Use Cases

• Personal photo backup: Home users can run LibrePhotos on a NAS, ingesting photos from USB drives and accessing them via a web UI.
• Small business media libraries: Agencies can host their own photo archives, leveraging semantic search to quickly find shots from specific events.
• Research labs: Scientists can ingest large collections of images, automatically tag them with object/scene embeddings, and query by content.
• Enterprise intranet: Companies can host a corporate photo gallery with multi‑