PiGallery2 on Ubuntu 24.04 on Azure User Guide

Overview

This guide covers the deployment and configuration of PiGallery2 on Ubuntu 24.04 on Azure using cloudimg Azure Marketplace images. PiGallery2 is a fast, open source, directory first photo gallery and management server. You point it at a folder of photos and videos and it serves a modern browser gallery that preserves your directory structure, generates thumbnails, reads EXIF metadata, and adds search, maps, face grouping and secure sharing.

The image installs the latest stable PiGallery2 release and pins the exact version (recorded in /opt/pigallery2/VERSION). PiGallery2 runs on Node.js 22 LTS under systemd as the unprivileged pigallery2 system user and binds to loopback only (127.0.0.1:8080). nginx is the sole network facing surface and terminates TLS on port 443, reverse proxying to PiGallery2. Port 80 redirects to HTTPS. Your photos, the thumbnail cache and the SQLite index live on a dedicated data disk mounted at /var/lib/pigallery2, provisioned automatically with every VM.

Secure by default. When password protection is enabled, PiGallery2 will otherwise create a well known default administrator, which would leave an unprotected gallery open to anyone who can reach it. This image turns authentication on and generates a unique administrator credential on each virtual machine's first boot. Only a one way bcrypt hash of the password is written to the configuration; the plain password is placed in a root only file for the administrator to read. There are no shared or default credentials, and nothing is baked into the image.

What is included:

• The latest stable PiGallery2 release, installed on Node.js 22 LTS and run under systemd as the unprivileged pigallery2 system user

• PiGallery2 bound to loopback only (127.0.0.1:8080); it is never network exposed directly

• nginx terminating TLS on :443 and reverse proxying to PiGallery2, with HSTS and sensible security headers

• Port :80 returns a 301 redirect to HTTPS for every path except an unauthenticated /healthz endpoint (HTTP 200) for load balancer probes

• Authentication on by default with a unique admin credential generated per VM on first boot; only the one way bcrypt hash is stored in the configuration, the plain password lands in a root only file

• A dedicated data disk mounted at /var/lib/pigallery2 holding your photos (images/), the thumbnail cache (tmp/) and the SQLite index (db/), captured into the image so every VM is provisioned with it

• A small set of sample photos so the gallery is populated the moment you sign in; replace them with your own

• ffmpeg installed for video thumbnails and transcoding

• A self signed TLS certificate regenerated per VM on first boot (its Subject Alternative Names include the VM IP, hostname and 127.0.0.1); replace it with your own CA signed certificate for production

• A built in self test at /usr/local/bin/pigallery2-selftest that proves the authenticated login and gallery listing end to end over TLS

• Ubuntu 24.04 LTS base with the latest security patches applied at build time

• Azure Linux Agent for seamless cloud integration and SSH key injection

• 24/7 cloudimg support with a guaranteed 24 hour response SLA

Prerequisites

• An Azure subscription with permission to deploy virtual machines

• An SSH key pair for administrative access to the VM as the azureuser account

• A Network Security Group allowing inbound TCP 443 (HTTPS) and 80 (redirect) from the networks that should reach the gallery, and 22 (SSH) from your management network only

• A recommended size of Standard_B2s or larger

Step 1: Deploy from the Azure Portal

1. Locate the PiGallery2 on Ubuntu 24.04 LTS image in the Azure Marketplace and select Create.

2. Choose your subscription, resource group and region.

3. Select a VM size (Standard_B2s or larger) and provide your SSH public key for the azureuser account.

4. On the Networking tab, allow inbound 443 and 80 from your users, and restrict 22 to your management network.

5. Review and create. When the VM is running, browse to https://<your-public-ip>/.

Step 2: Deploy from the Azure CLI

Deploy the image from the command line, restricting SSH to your management network. Replace the placeholder values with your own before running:

az vm create \
  --resource-group my-resource-group \
  --name pigallery2 \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_rsa.pub \
  --public-ip-sku Standard

# Allow the gallery from your users and SSH from your management network only
az vm open-port --resource-group my-resource-group --name pigallery2 --port 443 --priority 1001
az network nsg rule create --resource-group my-resource-group --nsg-name pigallery2NSG \
  --name allow-ssh --priority 1002 --destination-port-ranges 22 \
  --source-address-prefixes <your-mgmt-cidr> --access Allow --protocol Tcp

When the VM is running, browse to https://<public-ip>/.

Step 3: Retrieve your per instance admin credential

Authentication is on by default. Each VM generates its own admin username and password on first boot, written to a root only file. Read it over SSH:

ssh azureuser@<vm-ip> 'sudo cat /root/pigallery2-credentials.txt'

The file contains the PIGALLERY2_USER, PIGALLERY2_PASS and PIGALLERY2_URL for this specific VM. Keep it secret. The configuration only ever stores a one way bcrypt hash of the password, never the plain text.

Step 4: Sign in to the gallery

Browse to https://<vm-ip>/. Because the certificate is self signed per VM, your browser will show a certificate warning the first time; accept it to proceed (or install the per VM certificate, or place a CA signed certificate in front, as covered in Step 9). PiGallery2 presents a login screen.

Sign in with the username and password from Step 3. PiGallery2 opens on the gallery, showing the photos in your media folder as a responsive grid. The included sample photos are visible immediately; the top bar carries Gallery, Albums and Faces navigation, a search box, and the signed in admin user.

Step 5: View and browse your photos

Click any photo to open it full screen in the lightbox. Use the arrow keys or the on screen arrows to move between photos, and the toolbar to see photo information, go full screen, or start a slideshow. Directory structure is preserved, so subfolders of your media folder appear as albums you can browse into.

Step 6: Add your own photos

Your gallery reads from /var/lib/pigallery2/images on the dedicated data disk. Copy your own photos and videos into that folder (preserving any subfolder structure you want as albums), fix ownership so the service can read them, then browse the gallery to index them:

# Copy your photos into the gallery folder (use sudo; the folder is owned by the service user)
sudo cp -r ~/my-photos/. /var/lib/pigallery2/images/
sudo chown -R pigallery2:pigallery2 /var/lib/pigallery2/images

PiGallery2 indexes directories lazily the first time they are browsed, and a background job keeps the index up to date. Thumbnails and transcoded videos are written to /var/lib/pigallery2/tmp, and the SQLite index to /var/lib/pigallery2/db, both on the same data disk. Because the data disk is captured with the image and re attached to every VM, your photos and index survive a redeploy of the OS disk.

Step 7: Manage settings as an administrator

The signed in admin user can open the Settings page to manage users, media handling, sharing, indexing and more. The Server section shows the loopback bind (127.0.0.1:8080) that nginx proxies to, and the Users section shows that password protection is enabled with the per VM admin account enforced.

Step 8: Verify the deployment

SSH to the VM as azureuser and confirm the services are running and PiGallery2 is bound to loopback only:

systemctl is-active pigallery2 nginx
sudo ss -tlnp | grep 8080

Both services report active, and PiGallery2 listens on 127.0.0.1:8080 only. nginx is the only component exposed on :80 and :443.

Run the built in self test. It reads this VM's credential and proves the full round trip over TLS: an unauthenticated gallery request is refused, a login with the per VM credential succeeds, the gallery lists the sample photos, and the PiGallery2 default admin/admin login is rejected because it was never shipped:

sudo /usr/local/bin/pigallery2-selftest

Step 9: TLS, authentication and the per instance certificate

nginx terminates TLS on port 443 and redirects plain HTTP on port 80 to HTTPS. Confirm the redirect and the unauthenticated health probe from the VM:

curl -s -o /dev/null -w 'port 80 -> HTTP %{http_code}\n' http://127.0.0.1/
curl -sk -o /dev/null -w 'healthz over TLS -> HTTP %{http_code}\n' https://127.0.0.1/healthz

Port 80 returns 301 and the health endpoint returns 200. An unauthenticated request to the gallery API is refused (NOT_AUTHENTICATED), while a login carrying this VM's credential returns the admin user. The self signed certificate is regenerated per VM on first boot, with the VM IP and hostname in its Subject Alternative Names:

Step 10: Replace the certificate for production

The per VM certificate is self signed, so browsers warn on first use. For a public deployment, put a real certificate in front. The simplest path is to point a DNS name at the VM and obtain a free certificate with Certbot:

# Point https://<your-domain> at this VM first, then:
sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d <your-domain>

Alternatively, terminate TLS at an Azure Application Gateway or a load balancer in front of the VM and forward to port 443.

Step 11: Baked version and credential summary

The baked version and this VM's credential summary are recorded on the VM. The password line is redacted below; read the full value from the root only file in Step 3:

Security notes

• No default login. Authentication is on by default and a unique admin credential is generated on each VM's first boot. Only a one way bcrypt hash is stored in the configuration; the plain password lives in the root only /root/pigallery2-credentials.txt. The PiGallery2 default admin/admin account is never shipped.

• Loopback only application. PiGallery2 binds to 127.0.0.1:8080 and is only reachable through the nginx TLS reverse proxy on :443. Keep it that way and let nginx (or a load balancer) be the sole network facing surface.

• Data on a dedicated disk. Your photos, thumbnail cache and index live on the data disk at /var/lib/pigallery2, separate from the OS disk. Back up this disk to protect your library.

• Restrict access. Allow 443 only from the networks that need it, keep 22 restricted to your management network, and replace the self signed certificate with a CA signed one for production.

• Rotate the credential from the admin Settings page (change the admin password), or by placing your own identity aware proxy in front.

Support

This image is backed by 24/7 cloudimg support with a guaranteed 24 hour response SLA. Contact support@cloudimg.co.uk for assistance. PiGallery2 is open source software distributed under the MIT License and is free; the cloudimg charge covers packaging, hardening, security patching, image maintenance and support.