Deployment guide

HomeGallery

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 database powers a fast, browsable web gallery with search by date, tag, color and similarity, plus a map view, all without an external database or object store.

The SecureAnyCloud image installs the pinned HomeGallery 1.21.0 release as a single self-contained binary. The binary bundles its own runtime and its image and video processing, so there is no Node.js, libvips or ffmpeg to install. It runs as the home-gallery systemd service on port 3000.

HomeGallery serves with no authentication by default, and this image never ships that way. Authentication is enforced for every network client. 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.

What you get:

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
A file-based media database, with no external database or object store to run or maintain
Bundled image and video processing (sharp and ffmpeg), so no system Node.js, libvips or ffmpeg is required
Secure by default: HTTP Basic authentication is required for every network client, and loopback is 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 SecureAnyCloud support

Prerequisites

You need an active Azure subscription, an SSH key pair, and a VNet with a 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.

For NSG inbound rules, 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 SecureAnyCloud, and select Create.

On the Basics tab, 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).

Click Review + create, then Create. After deployment, add an inbound rule for 3000/tcp in the Network Security Group so you can reach the gallery.

Step 2 - Deploy from the Azure CLI

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:home-gallery-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name home-gallery \
  --image sac1647283583153:home-gallery-ubuntu-24-04:default:latest \
  --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 to the VM as azureuser:

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the service is running

Check the service status:

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.

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

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

Step 6 - Sign in to the web gallery

Open http://<vm-public-ip>:3000/ in a browser. Access over the network requires authentication, so the browser prompts for HTTP credentials. Enter admin and the per-VM password from Step 5.

The gallery grid opens and shows the sample media that ships already indexed.

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

Step 7 - Search and browse

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

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. It requires the per-VM admin password for every request over the network. Confirm this 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. This proves the gallery is never open over the network.

Where things live

The file-based database, the media directory and the generated previews all live under /var/lib/home-gallery. 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

Binary: /opt/home-gallery/gallery (self-contained, with a 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 run sudo systemctl restart home-gallery.service. Generate a {SHA256-salted} hash with the one-line command 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 distribution site of the project and replace /opt/home-gallery/gallery. Then restart the service.

Support. Every SecureAnyCloud deployment includes 24/7 support with a 24 hour response SLA. Contact sales@secureanycloud.com.

SecureAnyCloud is not affiliated with or endorsed by the HomeGallery project. HomeGallery is MIT-licensed. The sample images are NASA and Hubble public domain works.

Deploy on Azure

Launch HomeGallery on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on Azure

Overview

HomeGallery is an open source, self-hosted photo and video gallery. It indexes a media directory into a fast, file-based database and serves a clean, browsable web gallery. The gallery offers a photo grid, a full-screen lightbox, an interactive map of geotagged media, a timeline, faceted search and content-based similar-image discovery.

There is no external database and no object store to run. That makes this image a privacy-respecting alternative to cloud photo services, deployable entirely in your own VPC.

HomeGallery ships as a single self-contained binary that bundles its own runtime, image processing and video tooling. It serves the web gallery directly on port 3000, so there is no separate interpreter, database server or reverse proxy to manage.

Your media, the file-based index and the generated previews live on a dedicated, independently resizable EBS data volume mounted at /var/lib/home-gallery. This keeps gallery data off the operating system disk.

Upstream HomeGallery serves with no authentication by default, and this SecureAnyCloud image never does. Authentication is enabled with a deny-all-except-loopback rule and no usable account. The gallery service does not start until first boot.

On first boot, the instance generates a strong administrator password that is unique to that instance. It stores only a salted hash in the configuration, writes the plaintext to a root-only file, and only then begins serving. Every network client must present that per-instance password. The loopback interface is allowed without authentication so local health checks work. No shared, default or known credential is baked into the image.

To give you something to look at immediately, the image ships a handful of public domain NASA and Hubble sample images already indexed. Replace them with your own photos and videos.

Prerequisites

To deploy this image, you need:

An Amazon Web Services account where you can launch EC2 instances
IAM permissions to launch instances, create security groups and subscribe to AWS Marketplace products
An EC2 key pair in the target Region for SSH access to the instance
A VPC and subnet in the target Region, with a security group that allows inbound port 22 from your management network and inbound port 3000 from the networks your users reach the gallery on
The AWS CLI (version 2) installed locally, if you plan to deploy from the command line

Connecting to your instance

Connect over SSH as the default login user for the operating system variant you launched. HomeGallery runs the same on every variant, and only the login user differs.

For Ubuntu 24.04 LTS, the SSH login user is ubuntu.

Launch the instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service and select Launch instance. Under Application and OS Images, choose AWS Marketplace AMIs and search for HomeGallery. Select the SecureAnyCloud listing, choose Select, then choose Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login).

Under Network settings, select your VPC and subnet. Create or select a security group that allows inbound port 22 from your management network and inbound port 3000 from the networks your users connect from. Leave the root volume and the attached data volume at their default sizes, or increase the data volume if you plan to index a large library.

Select Launch instance. First boot initialization takes under a minute after the instance state becomes Running and the status checks pass.

Launch the instance from the AWS CLI

The following command launches an instance from the SecureAnyCloud HomeGallery Marketplace AMI into an existing subnet and security group.

Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, and <subnet-id> with your subnet ID. Replace <security-group-id> with a security group that opens ports 22 and 3000 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=home-gallery}]'

Connect to the instance

Connect over SSH, using your key pair and the ubuntu login user. Replace <public-ip> with the public IP address of the instance.

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

Retrieve your per-instance admin password

The administrator password is generated on first boot and is unique to this instance. Read it over SSH:

$
sudo cat /root/home-gallery-credentials.txt HOMEGALLERY_URL=http://<public-ip>:3000/ HOMEGALLERY_USERNAME=admin HOMEGALLERY_PASSWORD=<HOMEGALLERY_PASSWORD>

Keep this password somewhere safe. It is the only administrator credential, and it is never shown anywhere else.

You can confirm that the gallery is running and that the network surface enforces authentication, without ever printing the password. The check covers the service and the local health endpoint. It also confirms that a network request is rejected without the password but accepted with it:

systemctl is-active home-gallery.service curl -s -o /dev/null -w 'local health endpoint: HTTP %{http_code}\n' http://127.0.0.1:3000/
PW=$(sudo grep '^HOMEGALLERY_PASSWORD=' /root/home-gallery-credentials.txt | cut -d= -f2-)
IP=$(hostname -I | awk '{print $1}')
echo "network request without password: HTTP $(curl -s -o /dev/null -w '%{http_code}' -u wrong:wrong http://$IP:3000/)"
echo "network request with your password: HTTP $(curl -s -o /dev/null -w '%{http_code}' -u admin:"$PW" http://$IP:3000/)"

A healthy instance reports active, HTTP 200 on the local endpoint, HTTP 401 for the network request without a password, and HTTP 200 for the network request with your password.

Open the gallery

Browse to http://<public-ip>:3000/ and sign in as admin with the password from Step 4. Your browser prompts for HTTP credentials.

The gallery opens on the photo grid, showing the seeded sample media. Use the navigation bar to switch between Show All, Years, Videos, Tags and Map, or use the Search box.

Click any photo to open the full-screen lightbox, where you can step through your library, view metadata and find visually similar images.

Open Map to see geotagged photos and videos plotted on an interactive world map, so you can browse your library by place. The seeded samples carry no location data, so only your own geotagged media appears there.

Type a term into the Search box to filter the library instantly. Search matches file names, dates, tags and detected content.

Add your own photos and videos

Copy your media into the media directory of the gallery on the dedicated data volume. Then rebuild the index, so the new files appear in the grid, map and search.

Run the following over SSH. It processes your files and updates the file-based database, so run it whenever you add media:

$
sudo cp -r /path/to/your/photos/. /var/lib/home-gallery/media/ $
sudo chown -R homegallery:homegallery /var/lib/home-gallery/media $
sudo -u homegallery env HOME=/var/lib/home-gallery \
  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 your media appears alongside (or in place of) the samples. To remove the sample images, delete them from /var/lib/home-gallery/media/ before you import.

Confirm the dedicated data volume

Gallery media, the file-based index and the previews live on their own EBS volume, so you can grow storage independently of the OS disk. Confirm that the volume is mounted:

df -h /var/lib/home-gallery | tail -1

To enlarge your library later, expand the EBS volume in the AWS console. Then grow the filesystem on the instance with sudo resize2fs on the underlying device. SecureAnyCloud support can walk you through it.

Restrict access

The per-instance admin password protects the gallery, but you should still limit who can reach port 3000. In your EC2 security group, restrict the inbound rule for TCP port 3000 to the specific IP ranges your users connect from, rather than leaving it open to the internet. Keep port 22 restricted to your management network.

Enable HTTPS

For production, terminate TLS in front of the gallery on your own domain. Point a DNS record at the instance, put a reverse proxy such as nginx or Caddy in front of port 3000, and obtain a certificate with a tool such as certbot.

The following outline shows the general shape. SecureAnyCloud support provides a full, tested configuration for your domain:

# Install a reverse proxy and certbot, proxy your-domain to 127.0.0.1:3000,
# then request a certificate: $
sudo certbot --nginx -d your-domain.example.com

Back up and maintain the gallery

Everything that matters lives under /var/lib/home-gallery: your media, the file-based database at config/database.db and the generated previews. Back up that directory on a schedule, or snapshot the data EBS volume. HomeGallery has no external database, so a filesystem-level backup of that one directory is a complete backup.

Manage the service with systemctl (home-gallery). For example, restart it after a configuration change, or check its logs with journalctl -u home-gallery. SecureAnyCloud handles tested upgrade paths between HomeGallery releases.

Scaling and operations

HomeGallery is efficient and runs comfortably on an m5.large for typical libraries. Indexing large collections, especially videos that generate previews, is CPU and IO intensive. A larger instance speeds up the initial import, and you can resize the instance afterwards.

Grow the data volume as your library grows. For high-traffic deployments, place a caching reverse proxy in front and serve previews from the proxy.

Support

SecureAnyCloud provides 24/7 technical support for this product by email and live chat. We help with deployment, media indexing, TLS termination, HomeGallery version upgrades, backup strategy, data migration and troubleshooting. Contact us at sales@secureanycloud.com.

HomeGallery is a trademark of its respective owner. All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.

Deploy on AWS

Launch HomeGallery on AWS with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on AWS