HomeGallery

HomeGallery is a lightweight, self‑hosted photo and video gallery written in JavaScript/Node.js that emphasizes speed, privacy, and mobile usability. From a technical standpoint it exposes a REST‑like API for image metadata while serving a single‑page React/Vue front‑end that consumes this data. The application parses media files on disk, extracts EXIF/IPTC tags, and performs optional AI‑based face recognition or image similarity scoring via TensorFlow.js models. All of this is orchestrated by a single binary, making it trivial to deploy on Linux, macOS, Windows or as a Docker container.

Architecture

• Runtime: Node.js (v18+) with the Fastify framework for low‑latency request handling.
• Front‑end: A SPA built with React (or Vue, selectable via build flag) that communicates through a JSON API.
• Data Layer: A lightweight SQLite database stores file metadata, tags, and AI embeddings. The image files themselves remain on the host filesystem in user‑specified source directories.
• AI Engine: TensorFlow.js models run server‑side to generate face embeddings or image similarity vectors; results are cached in the database.
• CLI: The gallery binary provides sub‑commands for initialization, indexing, and running the server, simplifying bootstrap.

Core Capabilities

• Tagging & Facets: Automatic extraction of GPS, date/time, camera model, and user‑defined tags.
• AI Discovery: Face clustering and image similarity search powered by pre‑trained models; exposes endpoints for custom queries.
• Webhooks & Events: Emits events on media addition or deletion, allowing external services to react (e.g., sync with cloud).
• Plugin System: Developers can extend the API or front‑end via a simple plugin interface that hooks into lifecycle events.
• Search & Filtering: Full‑text search over tags and metadata, with support for range queries (date, GPS radius).

Deployment & Infrastructure

• Containerization: Official Docker image (xemle/home-gallery) mounts a host directory for media and persists the SQLite database in another volume.
• Scalability: While a single instance is sufficient for most personal use cases, the stateless API can be horizontally scaled behind a reverse proxy; the database is file‑based but can be swapped for PostgreSQL with minimal changes.
• Resource Footprint: A typical deployment uses < 200 MB RAM and a few percent CPU, making it suitable for NAS or Raspberry Pi environments.
• HTTPS & Auth: Supports TLS termination via reverse proxy; optional JWT authentication can be enabled for multi‑user scenarios.

Integration & Extensibility

• REST API: Exposes endpoints such as /api/media, /api/tags, and /api/search.
• Webhooks: Configurable URLs receive POST payloads on media changes.
• Custom Renderers: Front‑end templates can be swapped or extended through a plugin hook, allowing developers to inject their own UI components.
• CLI Hooks: The gallery command accepts custom scripts to run after indexing or before shutdown, enabling integration with backup tools.

Developer Experience

• Configuration: YAML/JSON config files allow fine‑grained control over media sources, indexing intervals, and AI model selection.
• Documentation: Comprehensive docs at docs.home-gallery.org cover architecture, API reference, and plugin development.
• Community: Active Gitter/Discord channels provide quick support; the project is MIT‑licensed, encouraging commercial or open‑source use.
• Testing: The codebase includes unit and integration tests, with a CI pipeline that builds Docker images automatically.

Use Cases

1. Personal Memory Management – A hobbyist can index thousands of photos on a NAS and explore them via mobile‑friendly UI.
2. Small Business Portfolio – A photographer can serve a curated gallery without relying on cloud services, maintaining full control over metadata.
3. Research Prototypes – Developers experimenting with image similarity or face clustering can plug the AI engine into their own workflows.
4. Embedded Systems – The lightweight binary runs on ARM devices, making it ideal for DIY photo frames or kiosk displays.

Advantages

• Privacy‑First: All data stays on the host; no third‑party uploads.
• Performance: Fast indexing and low API latency due to Fastify and SQLite.
• Flexibility: Modular AI components and a plugin system let developers tailor the gallery to niche needs.
• Licensing: MIT license removes barriers for commercial deployment or redistribution.

In summary, HomeGallery offers a technically robust, developer‑friendly platform for building custom photo‑gallery services that prioritize speed, privacy, and extensibility.