Photoview

Photoview is a lightweight, self‑hosted photo gallery that turns any directory of images and videos into a fully navigable web interface. From the developer’s point of view, it is built around a modern Go‑based backend that scans file systems, extracts EXIF metadata, and serves thumbnails through an HTTP API. The front‑end is a single‑page application rendered with React, communicating with the backend via REST endpoints and WebSocket streams for real‑time updates. The architecture is intentionally simple to enable rapid deployment in containerized environments while still offering a rich set of extensible features.

Technical Stack

• Backend: Go 1.22+, using the standard net/http library combined with Gorilla Mux for routing and a lightweight ORM (sqlx) to interface with PostgreSQL. The scanner is a concurrent worker pool that watches the file system for changes and regenerates thumbnails on demand.
• Database: PostgreSQL 18 (default), storing metadata such as album hierarchy, user accounts, sharing tokens, and EXIF tags. The schema is intentionally flat to keep queries fast; indexes are created on frequently queried columns like user_id, album_path, and photo_hash.
• Front‑end: React 18, bundled with Vite. It consumes the API through Axios and leverages WebSockets for push notifications when new media is detected. The UI is responsive, with lazy loading of thumbnails and progressive image decoding.
• Containerization: Official Docker images are available on hub.docker.com/r/photoview/photoview. The container mounts a host directory for media and a PostgreSQL data volume. Docker Compose examples are provided, simplifying multi‑service deployments.

Core Capabilities

• File System Scanning: A configurable scanner walks a directory tree, generating thumbnails on first encounter and updating them when the source file changes. It supports common image formats (JPEG, PNG) and video codecs for thumbnail extraction.
• EXIF & Geo‑Tagging: The backend parses EXIF metadata to expose GPS coordinates, camera settings, and timestamps. These are exposed via the API and rendered on an interactive map using Leaflet.
• User & Sharing Model: Multi‑tenant support allows each user to own a separate root directory. The API provides endpoints for creating public or password‑protected share links, which are stored as short tokens in the database.
• Webhooks & API Hooks: While no external webhook support is shipped out of the box, the codebase exposes hooks in the scanning pipeline that can be overridden by custom middleware. This makes it straightforward to plug in services like Slack notifications or automated backups.

Deployment & Infrastructure

Photoview is designed for self‑hosting on Linux servers, NAS devices, or cloud VMs. It requires:

• Storage: Persistent file system (e.g., NFS, Samba) for media and a separate volume for PostgreSQL data. The Docker image mounts /media for source files and /var/lib/postgresql for the database.
• Scalability: The Go server is single‑process but can be replicated behind a reverse proxy (NGINX or Traefik) to handle increased load. Thumbnails are cached in memory and on disk, reducing CPU usage for repeated requests.
• High Availability: PostgreSQL can be configured in a replication setup; the Go application is stateless aside from the database, making it trivial to roll out zero‑downtime updates.

Integration & Extensibility

• Plugin System: The scanner and HTTP server expose interfaces that can be extended with Go plugins compiled as shared objects. This allows developers to add support for new media formats, custom metadata extraction, or third‑party authentication providers.
• API: All functionality is reachable via a RESTful API. The schema follows standard JSON conventions, and Swagger documentation can be generated automatically using swaggo/swag.
• Webhooks: Custom webhooks can be defined in the admin UI, triggering POST requests on events like “photo added” or “album created.” This facilitates integration with CI/CD pipelines, backup scripts, or notification services.

Developer Experience

The project maintains comprehensive documentation on GitHub, including setup guides, API references, and contribution guidelines. The community is active on Discord, where developers can discuss architecture decisions or request new features. Code coverage remains above 90%, indicating a mature test suite that covers both the scanner logic and API endpoints. Licensing is MIT, allowing unrestricted use in commercial or open‑source projects.

Use Cases

1. Personal Photo Server – A photographer can host a private gallery that syncs with a NAS, exposing albums via secure credentials.
2. Family Photo Sharing – Multiple family members can each have isolated directories; shared albums are distributed through short links.
3. Event Photography – Event organizers can mount a USB drive, let Photoview auto‑index the photos, and provide guests with a public gallery.
4. Integration into Existing Media Stacks – Photoview can be embedded behind an existing Nextcloud instance, using its file system API to fetch media.

Advantages

• Performance: Go’s compiled binaries provide low memory footprint and high throughput, especially for concurrent scanning tasks.
• Flexibility: The file‑system‑based approach removes the need for a heavy CMS, giving developers full control over organization and access.
• Licensing: MIT license removes any commercial restrictions, making it suitable for proprietary deployments.
• Community & Support: Active contributors