Storage Azure

HomeGallery on Ubuntu 24.04 on Azure User Guide

| Product: HomeGallery on Ubuntu 24.04 LTS on Azure

Overview

HomeGallery is an open source, self hosted photo and video gallery. It scans your media directories, extracts previews and metadata, and builds a file based database that powers a fast, browsable web gallery with search by date, tag, colour, similarity and a map view, all without an external database or object store. The cloudimg image installs the pinned HomeGallery 1.21.0 release as a single self contained binary (it bundles its own runtime, image and video processing, so there is no Node.js, libvips or ffmpeg to install) and runs it as the home-gallery systemd service on port 3000.

HomeGallery serves with no authentication by default; this image never ships that. The web gallery is secure by default: authentication is enforced for every network client, and a unique admin password is generated on the first boot of every VM and written to a root only file, so nothing is shared between deployments. Loopback access stays open so local health checks work, while every request over the network must present the per-VM password. A small set of public domain NASA and Hubble sample images ships already indexed, so the gallery is browsable the moment it boots. Backed by 24/7 cloudimg support.

What is included:

  • HomeGallery 1.21.0 installed as a single self contained binary and running as the home-gallery systemd service
  • A browsable, searchable web gallery on port 3000 with grid, single photo, search and map views
  • File based media database - no external database or object store to run or maintain
  • Bundled image and video processing (sharp and ffmpeg) - no system Node.js, libvips or ffmpeg required
  • Secure by default: HTTP Basic authentication required for every network client, loopback allowed for local health checks
  • A unique admin password generated on first boot, stored hashed ({SHA256-salted}, never plaintext) and written to a 0600 root:root file
  • Public domain NASA and Hubble sample images shipped already indexed so the gallery is populated on first view
  • home-gallery.service as a systemd unit, enabled and active
  • 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a comfortable starting point for evaluation and a modest personal library; scale the VM up as your collection grows. NSG inbound: allow 22/tcp from your management network and 3000/tcp for the web gallery. HomeGallery serves plain HTTP on 3000; for production, front it with TLS on your own domain and restrict access to trusted IP ranges (see Maintenance).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for HomeGallery by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22). After deployment, add an inbound rule for 3000/tcp in the Network Security Group so you can reach the gallery. Then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name home-gallery \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name home-gallery --port 3000 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the service is running

systemctl is-active home-gallery.service

It reports active. HomeGallery serves the web gallery on port 3000 and keeps its file based database under /var/lib/home-gallery.

The home-gallery service reported active, HomeGallery listening on port 3000, the installed version, and the web UI returning HTTP 200 on loopback

Step 5 - Retrieve your admin login

On the first boot of your VM a unique admin password is generated and written to a root only file. Read it:

sudo cat /root/home-gallery-credentials.txt

You will see the gallery URL, the username admin and the per-VM password. The credentials file is 0600 root:root, and inside the gallery configuration the password is stored {SHA256-salted} hashed, never in plaintext.

The per-VM HomeGallery configuration showing host, port, public URL and the admin user with a hashed password, and the root only credentials file with 0600 permissions

Step 6 - Sign in to the web gallery

Open http://<vm-public-ip>:3000/ in a browser. Because access over the network requires authentication, the browser prompts for HTTP credentials - enter admin and the per-VM password from Step 5. The gallery grid opens, showing the sample media that ships already indexed.

The HomeGallery web gallery grid showing the indexed sample images with the Show All, Years, Videos, Edit, Tags and Map navigation and the search box

Click any image to open the single photo detail view, where you can page through your library, read metadata and open the tag and similarity tools.

A single photo opened in the HomeGallery detail view with navigation and metadata controls

Step 7 - Search and browse

Type a query into the search box to filter your library instantly - by text, tag, date, colour or similarity. HomeGallery also groups your media by year and plots geotagged photos on the Map view.

HomeGallery search results filtered to the galaxy images by a text query in the search box

The HomeGallery Map view, which plots geotagged media geographically

Step 8 - Add your own photos

Copy your own photos and videos into the media directory and rebuild the index. HomeGallery generates previews and updates the file based database:

sudo -u homegallery env HOME=/var/lib/home-gallery TMPDIR=/var/lib/home-gallery/tmp \
  GALLERY_BASE_DIR=/var/lib/home-gallery GALLERY_CONFIG_DIR=/var/lib/home-gallery/config \
  GALLERY_CACHE_DIR=/var/lib/home-gallery/cache \
  /opt/home-gallery/gallery run import -c /var/lib/home-gallery/config/gallery.config.yml

Refresh the gallery in your browser and the new media appears. To add a directory tree, copy it under /var/lib/home-gallery/media first, then run the command above.

Step 9 - Confirm the secure by default access model

HomeGallery on this image allows loopback requests without a password (so local health checks work) but requires the per-VM admin password for every request over the network. Confirm it end to end:

PW=$(sudo grep '^HOMEGALLERY_PASSWORD=' /root/home-gallery-credentials.txt | cut -d= -f2-)
IP=$(hostname -I | awk '{print $1}')
echo "loopback (no password)   -> HTTP $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3000/)"
echo "network  (no password)   -> HTTP $(curl -s -o /dev/null -w '%{http_code}' http://$IP:3000/)"
echo "network  (per-VM password)-> HTTP $(curl -s -o /dev/null -w '%{http_code}' -u admin:"$PW" http://$IP:3000/)"
echo "network  (wrong password)-> HTTP $(curl -s -o /dev/null -w '%{http_code}' -u admin:wrong-password http://$IP:3000/)"

You should see loopback return 200, an unauthenticated network request return 401, the per-VM password return 200, and a wrong password return 401 - proving the gallery is never open over the network.

The secure by default HTTP Basic authentication round-trip: loopback returns 200, an unauthenticated network request returns 401, the per-VM password returns 200 and a wrong password returns 401

Where things live

The file based database, the media directory and the generated previews all live under /var/lib/home-gallery, so a single node runs the full gallery with no external services:

ls -1 /var/lib/home-gallery/media
ls -l /var/lib/home-gallery/config/database.db

The indexed sample media and the file based database on disk, with the generated preview files - no external database

  • Binary: /opt/home-gallery/gallery (self contained, bundled runtime)
  • Configuration: /var/lib/home-gallery/config/gallery.config.yml
  • Media sources: /var/lib/home-gallery/media
  • File based database and index: /var/lib/home-gallery/config/database.db, media.idx
  • Generated previews: /var/lib/home-gallery/cache/storage
  • Per-VM credentials: /root/home-gallery-credentials.txt (0600 root:root)

Maintenance

Change the admin password. Edit /var/lib/home-gallery/config/gallery.config.yml and replace the password under server.auth.users with a new hash, then sudo systemctl restart home-gallery.service. Generate a {SHA256-salted} hash with the one line documented in the shipped example configuration, or set a plain value for testing.

Enable HTTPS. For production, put HomeGallery behind a reverse proxy (nginx or Caddy) that terminates TLS on your own domain, set server.publicUrl to your HTTPS URL, and restrict the Network Security Group so only the proxy reaches port 3000.

Updates. The image applies unattended security updates for the operating system. To move HomeGallery to a newer release, download the new self contained binary from the project's distribution site, replace /opt/home-gallery/gallery, and restart the service.

Support. Every cloudimg deployment includes 24/7 support with a 24 hour response SLA. Contact support@cloudimg.co.uk.

cloudimg is not affiliated with or endorsed by the HomeGallery project. HomeGallery is MIT licensed. Sample images are NASA and Hubble public domain works.