HomeGallery takes a different approach to personal photo and video galleries by shifting the entire metadata database to the client side as compressed JSON. This enables fast, mobile-friendly browsing without the overhead of a traditional backend database, a tradeoff that’s worth understanding if you manage large local media archives.
What HomeGallery is and how it works
HomeGallery is an open-source, self-hosted web gallery built on Node.js for managing personal photo and video collections. It’s designed to browse large archives efficiently while providing modern features like AI-powered image discovery, reverse image lookup, face detection, and object recognition.
The backend is a Node.js CLI tool that indexes media from user-configured sources such as local folders. It builds a metadata database capturing file details, thumbnails, geolocation, and AI analysis results. This metadata database is then served as a large JSON payload to the client, where all browsing, searching, and filtering happen.
The project supports multiple media sources, including read-only or offline locations, and handles duplicates using content-based identification. It also features video transcoding to improve playback compatibility and a progressive web app (PWA) frontend for mobile access.
Under the hood, HomeGallery optionally integrates with a public AI API for image analysis but also supports a self-hosted alternative, allowing users to avoid external dependencies for privacy or performance reasons.
What makes HomeGallery’s architecture interesting
The standout architectural choice is loading the entire media metadata database client-side as compressed JSON. For example, 100,000 media files produce about 100MB of uncompressed JSON and 12MB compressed. A user even reported success with over 400,000 files.
This design eliminates the need for a traditional backend database during browsing. Instead, the frontend performs all search and filtering operations locally. This enables incredibly fast, responsive interactions, especially on mobile devices where round-trip latency and backend overhead would otherwise slow down browsing.
To handle the large data volume, HomeGallery employs virtual scrolling techniques, only rendering visible items in the UI to keep memory and CPU usage reasonable.
The tradeoff is clear: the client needs sufficient memory and processing power to load and query the metadata JSON. This might limit usability on very low-end devices or extremely large archives beyond the reported 400k files.
The codebase is surprisingly clean for a project handling such complexity. The CLI tool is written in JavaScript with straightforward commands for initialization, indexing, and serving the gallery. The frontend uses modern web technologies and supports PWA features out of the box.
AI-powered discovery features distinguish it from many self-hosted galleries. The combination of face detection, object recognition, and reverse image lookup allows users to find related media intuitively beyond traditional folder or date-based browsing.
Quick start
Following steps need to be performed to use HomeGallery
- Download the gallery software as prebuilt binary or docker image
- Init the configuration with media sources like
~/Pictures - Start the server on localhost:3000
curl -sL https://dl.home-gallery.org/dist/latest/home-gallery-latest-linux-x64 -o gallery
chmod 755 gallery
./gallery init --source ~/Pictures
./gallery run server
and open localhost:3000 in your browser. Run ./gallery -h for
further help of the CLI.
See dl.home-gallery.org/dist for further binaries. Eg. latest binaries for Linux, Mac or Windows.
The configuration gallery.config.yml can be found in the current directory for
fine tuning.
See install section in the documentation
for further information.
Quickstart using Docker
mkdir -p data
alias gallery="docker run -ti --rm \
-v $(pwd)/data:/data \
-v $HOME/Pictures:/data/Pictures \
-u $(id -u):$(id -g) \
-p 3000:3000 xemle/home-gallery"
gallery init --source /data/Pictures
gallery run server
and open localhost:3000 in your browser. Run gallery -h for
further help of the CLI.
The gallery configuration can be found in ./data/config/gallery.config.yml for fine tuning.
Want to use docker compose? See install section in the documentation for further information.
Verdict
HomeGallery is a solid choice if you want a self-hosted personal media gallery that avoids complex backend databases by shifting metadata to the client. Its AI-powered discovery features add real value for browsing large collections beyond simple file trees.
The tradeoff is the client memory footprint and initial load time, which might be a limiting factor on very low-end devices or extremely large archives. However, the reported success with 400k+ files shows this approach scales reasonably well for most personal uses.
If you prioritize fast, fluid browsing on mobile and want an open-source Node.js solution with modern web features, HomeGallery is worth trying. The CLI and Docker quickstart make deployment straightforward even if you’re not a Node.js expert.
On the other hand, if your media archive is massive or you need multi-user support and robust backend querying, a more traditional server-based gallery might be a better fit.
Overall, HomeGallery’s architecture and AI features solve a real-world problem in a practical way, balancing performance and complexity with a fresh take on self-hosted media browsing.
Related Articles
- Immich: a high-performance self-hosted photo and video management platform — Immich offers a self-hosted, high-performance solution for photo and video management with facial recognition, metadata
- Crawlee: a TypeScript library for stealthy web scraping and browser automation — Crawlee is a TypeScript library for web scraping and browser automation with human-like stealth. Supports Playwright, Pu
- glTF-Sample-Assets: a curated collection of glTF models for 3D development and testing — glTF-Sample-Assets offers a curated set of 3D models in glTF format, organized for testing and showcasing glTF capabilit
- awesome-web-scraping: a curated hub for web scraping tools and resources — A comprehensive, multi-language curated list of web scraping tools, services, and resources that acts as a vital referen
- Ferret v2: A declarative Go engine for web data extraction with a new API architecture — Ferret v2 is a Go-based declarative system for web scraping that introduces a native Go API and a compatibility layer to
→ GitHub Repo: xemle/home-gallery ⭐ 1,121 · JavaScript