PiGallery 2

PiGallery 2 is a directory‑first photo gallery server written in JavaScript/Node.js. It scans a read‑only filesystem hierarchy, indexes image metadata (EXIF, GPS, face counts), and exposes a lightweight REST‑style API that powers a responsive web UI. The core philosophy is speed and simplicity: the server performs minimal processing at request time, delegating most rendering to static assets and client‑side JavaScript. This makes it ideal for low‑resource hosts such as Raspberry Pi, but it scales comfortably to tens of thousands of images on a modest VPS.

• Runtime: Node.js ≥ 12 (LTS) with ES‑module support.
• Framework: Express‑like minimal routing, bundled with helmet and compression.
• Storage: Pure filesystem; no external database. Metadata is cached in a lightweight JSON/SQLite snapshot that updates on file changes via chokidar.
• Image Processing: sharp for thumbnail generation and on‑the‑fly transformations.
• Map Integration: Leaflet front‑end consuming GeoJSON generated from EXIF GPS tags or GPX files.
• Testing: Mocha/Chai with Istanbul coverage, CI on Travis and GitHub Actions.
• Containerization: Official Docker image (bpatrik/pigallery2) built with multi‑stage Dockerfiles, exposing ports 80/443 and mounting host directories for photos and temp cache.

• Read‑Only Gallery: The server never writes to the source folder; all modifications are made in a separate cache.
• Advanced Search: Boolean query language (person:"John", orientation:portrait, after:2020) with wildcard, negation, and autocomplete.
• Metadata Exposure: REST endpoints expose EXIF, GPS, face detection counts, and custom tags extracted from filenames or sidecar files.
• Map & GPX Support: Auto‑detect GPS coordinates, render on OpenStreetMap or Mapbox layers, overlay GPX tracks with activity classification.
• Lightweight API: JSON payloads for gallery listings, photo details, and search results; can be consumed by custom front‑ends or third‑party services.
• Extensibility Hooks: hooks.json allows injection of custom middleware or route handlers, and optional WebSocket events for live updates.

• Self‑Hosting: Run on any machine with Node.js or via Docker; no external services required.
• Scalability: Stateless HTTP layer means you can horizontally scale behind a reverse proxy (NGINX, Traefik) and share the same photo directory via NFS or SMB.
• Resource Footprint: A single container uses < 200 MB RAM and < 1 CPU core on a Pi 4, while still delivering sub‑second API responses for 50k images.
• Container Orchestration: Docker Compose or Kubernetes manifests available; the image is built with --build-arg support for custom ports and cache directories.

• Plugin System: A lightweight plugin API lets developers add new metadata parsers, expose additional endpoints, or modify the UI by injecting CSS/JS bundles.
• Webhooks: Configure outbound HTTP callbacks on events such as new photo detection or search query completion.
• Custom Themes: The front‑end is modular; swap out the CSS or replace React components without touching the Node backend.
• CLI Utilities: pigallery2-cli can pre‑populate the cache, generate static snapshots, or perform bulk metadata updates.

• Configuration: All settings are environment‑variable driven (PIGALLERY_PHOTO_DIR, PIGALLERY_CACHE_DIR, PIGALLERY_PORT).
• Documentation: Comprehensive README, API reference in /docs/references, and a live demo for quick prototyping.
• Community: Active GitHub repo with issue triage, pull‑request guidelines, and a Discord channel for real‑time support.
• Testing & Quality: Continuous integration ensures every commit passes linting, unit tests, and coverage thresholds.

1. Home Media Server – Mount a NAS photo folder on a Pi and expose it to the LAN with minimal overhead.
2. Travel Diary – Automatically parse GPX tracks and overlay them on a map for each trip, all served from the same image directory.
3. Developer Playground – Use the API to build custom mobile apps or integrate photo search into existing services.
4. Educational Projects – Demonstrate file‑system scanning, metadata extraction, and map rendering in a single repository.

• Zero‑DB Architecture: Eliminates database migrations and maintenance; ideal for static collections.
• Performance: In‑memory indexing and sharp caching deliver fast thumbnail generation even on ARM hardware.
• Licensing: MIT‑licensed, no commercial restrictions; free to embed in proprietary projects.
• Extensibility: Plug‑in hooks and webhooks make it a flexible foundation for custom workflows.
• Community & Support: Active contributors and clear contribution guidelines reduce friction for extending the core.

PiGallery 2 offers a developer‑friendly, low‑footprint solution that turns any photo directory