PiGallery2 on AWS User Guide

Overview

This guide covers the deployment and configuration of PiGallery2 on AWS using the cloudimg AWS Marketplace AMI. 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 volume mounted at /var/lib/pigallery2, provisioned automatically with every instance.

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 instance'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 instance 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 volume mounted at /var/lib/pigallery2 holding your photos (images/), the thumbnail cache (tmp/) and the SQLite index (db/), captured into the AMI so every instance 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 instance on first boot (its Subject Alternative Names include the instance public 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

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

Connecting to your instance

Connect over SSH on port 22 as the default login user for the operating system variant you launched. The corresponding private key is the EC2 key pair you selected at launch.

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

Prerequisites

• An AWS account with permission to launch EC2 instances

• An EC2 key pair for administrative SSH access to the instance as the ubuntu user

• A 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 instance type of m5.large or larger

Step 1: Launch from the AWS Marketplace

1. Locate the PiGallery2 listing in the AWS Marketplace and choose Continue to Subscribe, then Continue to Configuration and Continue to Launch.

2. Select the region, the m5.large (or larger) instance type, your VPC and subnet, and your EC2 key pair.

3. Configure the security group to allow inbound 443 and 80 from your users, and restrict 22 to your management network.

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

Step 2: Launch from the AWS CLI

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

aws ec2 run-instances \
  --image-id <pigallery2-ami-id> \
  --instance-type m5.large \
  --key-name your-key \
  --security-group-ids <sg-id> \
  --subnet-id <subnet-id> \
  --associate-public-ip-address

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

Step 3: Retrieve your per instance admin credential

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

ssh -i /path/to/your-key.pem ubuntu@<public-ip> 'sudo cat /root/pigallery2-credentials.txt'

The file contains the PIGALLERY2_USER, PIGALLERY2_PASS and PIGALLERY2_URL for this specific instance. 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://<public-ip>/. Because the certificate is self signed per instance, your browser will show a certificate warning the first time; accept it to proceed (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 volume. 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 volume. Because the data volume is captured with the AMI and re attached to every instance, 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 instance admin account enforced.

Step 8: Verify the deployment

SSH to the instance as ubuntu 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:

active
active
LISTEN 0  511  127.0.0.1:8080  0.0.0.0:*

Run the built in self test. It reads this instance's credential and proves the full round trip over TLS: an unauthenticated gallery request is refused, a login with the per instance 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

OK pigallery2 self-test passed: unauth rejected, per-VM login OK, gallery lists samples, admin/admin rejected (TLS)

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 instance:

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:

port 80 -> HTTP 301
healthz over TLS -> HTTP 200

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

Step 10: Replace the certificate for production

The per instance 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 instance and obtain a free certificate with Certbot:

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

Alternatively, terminate TLS at an Application Load Balancer in front of the instance and forward to port 443.

Step 11: Baked version summary

The baked PiGallery2 and Node.js versions are recorded on the instance at /opt/pigallery2/VERSION:

cat /opt/pigallery2/VERSION

pigallery2_version=3.5.2
node_version=v22.23.1

Security notes

• No default login. Authentication is on by default and a unique admin credential is generated on each instance'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 volume. Your photos, thumbnail cache and index live on the data volume at /var/lib/pigallery2, separate from the OS disk. Back up this volume 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.