HomeGallery: A Self-Hosted Photo Gallery That Ships the Whole Database to the Browser

The Problem HomeGallery Picks: Your Archive Is Local and Your Gallery Software Is Not

The README states the motivation plainly. The author's private images and videos live on a NAS at home, cloud services do not cover his privacy concerns, and existing gallery software is described as lacking a fast mobile experience. The stated goal is a gallery that sits on top of or close to the source rather than uploading it somewhere else. That combination, local originals plus phone browsing, is the gap the project targets. It is not aimed at families sharing an album or at teams managing a media library. The target users section says computer-affine users who solve their own problems, one user only, all files served, and multiple source directories such as hard drives, camera files and phone files. The single-user assumption is not a missing feature. It is a stated scope decision, and it shapes everything from authentication to the query model.

How the Index Reaches the Browser, and Why That Is the Whole Architecture

The mechanism that matters is described under Limits. The complete database is loaded into the browser. The README gives its own numbers: 100,000 media items are about 100 MB of plain JSON and 12 MB compressed, and a user reported a setup with over 400,000 media files. Search, filtering and reverse image lookup therefore run client side against that payload rather than against a server-side query engine. The features list supports this reading. Endless photo stream via virtual scrolling, an expressive query language with and, or, not operands, reverse image lookup for similar image search, and face detection with search by similar faces. All of those operate over an index the browser already holds. The indexing side, according to the documentation links, is a workflow described under internals, and the repository topics name the steps: calculate-previews, exif, face-detection, face-recognition, geo-reverse-lookups and reverse-image-search. Media are identified by content, so identical files are processed once and renames do not trigger recalculation. Preview files and extracted metadata are what the server needs afterwards. The README states that once previews are generated and metadata extracted, the original sources are not touched and not required, which is what makes offline and read-only disks workable.

Getting It Running: Four Commands and One YAML File

The quickstart is short. Download the binary, make it executable, initialise with a source, start the server. The README gives exactly this: curl -sL https://dl.home-gallery.org/dist/latest/home-gallery-latest-linux-x64 -o gallery, then chmod 755 gallery, then ./gallery init --source ~/Pictures, then ./gallery run server, and open localhost:3000. The Docker path keeps the same CLI shape. You create a data directory, define an alias that runs xemle/home-gallery with -v $(pwd)/data:/data, -v $HOME/Pictures:/data/Pictures, -u $(id -u):$(id -g) and -p 3000:3000, then run gallery init --source /data/Pictures and gallery run server. The -u flag matters more than it looks: without it the container writes index files as root and later host-side access gets awkward. Configuration lands in gallery.config.yml in the current directory for the binary, or ./data/config/gallery.config.yml for Docker. The README calls that file the place for fine tuning and points to the configuration documentation for the keys themselves. It does not enumerate them here, so treat the generated file as the source of truth for what is tunable.

The Browser-Side Database Is Also the Ceiling

The Limits section is unusually honest and should be read as a constraint rather than a footnote. A 100,000 item archive means roughly 100 MB of plain JSON and 12 MB compressed transferred to the client. The README says performance is quite good on current mobile devices and cites one user report above 400,000 media files. Those are the author's numbers and a single report, not a benchmark, and the project does not publish a figure for how long the initial index load takes on a mid-range phone. The practical consequence is that first load and cold cache behaviour scale with archive size, and every browser that opens the gallery pays that cost again. There is no server-side pagination to fall back on, because the design has no server-side query stage. A second limitation is built into the same paragraph: one user only, all files are served. There is no per-user visibility model described in the material. If two people need different views of the same library, this is the wrong tool. The README also states the project is a private spare-time effort without any warranty, which is a maintenance signal as much as a legal one.

What You Get for the Index Cost: Similarity, Faces, Geo and a Static Site

The features that justify the index are the discovery ones. Reverse image lookup is framed concretely in the README: if you have one sunset image, you can find other sunset photos in your archive without manual tagging. Face detection and search by similar faces work the same way, and geo location reverse lookups attach place information. Tagging supports single and multi selection. Video transcoding is listed, as is streaming to Chromecast devices and PWA support for a phone home screen. Two features stand apart from the browsing story. Meta data export to XMP sidecar files means the tagging work can leave the application, which reduces lock-in. Static web gallery site export produces something like the demo gallery, which is how you would publish a curated subset without running the server. The README also notes the project tries to use as few public services as possible and prefers services that can be deployed locally, because the image data is sensitive. That is a design position, not a guarantee, and the truncated README does not list which optional services exist or how to disable them.

Where It Fits Compared With a Traditional Server-Side Gallery

The obvious alternative is a self-hosted gallery that keeps the database on the server and answers queries over HTTP, the model used by server-rendered photo applications. The difference is not cosmetic. In that model the browser receives a page of results and the server holds the index, so archive size affects server memory and query time rather than the payload sent to the phone. In HomeGallery the trade runs the other way: the server does less work at browse time, the client holds everything, and offline or read-only source disks are viable because the originals are not needed after indexing. If your archive is small or your phone is recent, the client-side approach removes a whole class of server-side search infrastructure. If your archive is large and your clients are heterogeneous, the same choice becomes the bottleneck. The README's own framing, gallery software should be fast on mobile, is the bet being made. Whether it holds depends on your archive size and your devices, and the material gives no way to predict that without trying it.

Maintenance, Licence and What to Verify Before You Commit

The project is MIT licensed, which permits commercial and private use, modification and redistribution with the licence and copyright notice retained. That is a permissive baseline and nothing in the README adds restrictions, but this is not legal advice and the CHANGELOG plus the repository itself are where the current state lives. The README states the software is a private pet and spare-time project without warranty, which is the honest maintenance picture: there is a Gitter channel and a Discord server for questions, and the project asks for financial support through Patreon or PayPal. There are no releases retrieved in the supplied material, so versioning and upgrade cadence cannot be assessed from it. Before adopting, verify three concrete things. Run ./gallery init --source against a small directory and inspect the generated gallery.config.yml to see which keys exist for your build. Confirm the browser-side index size and load time on the phone you actually use, since that is the number the README quantifies and the one that decides whether the design suits you. And check the XMP export path if you care about getting tags back out, because that is the exit route if the project stalls.

Editorial conclusion

Adopt HomeGallery if you keep your originals on a NAS or local disk, want one user to see everything, and accept that the whole index is shipped to the browser. Skip it if you need multi-user permissions, a hosted service, or a gallery that scales without that transfer. Before committing, run ./gallery init --source on a small directory, check the generated gallery.config.yml keys for journal, database and events, and load the result on the phone you actually use.

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. xemle/home-gallery on GitHub