ZenphotoCMS on AWS User Guide

Overview

This image runs ZenphotoCMS behind nginx with PHP FPM 8.3 and OPcache enabled, with all the extensions ZenphotoCMS needs (gd, exif, intl, mbstring, mysqli, curl and zip). MariaDB provides the database, on the same instance and bound to the loopback interface only. ImageMagick and Ghostscript are installed so ZenphotoCMS can generate high quality image thumbnails.

The image ships with ZenphotoCMS's setup wizard already driven and its setup environment protected, so the first request lands directly on a working public gallery with no install wizard to work through. A small sample album ships so the gallery is populated on first view. A fresh administrator password and a fresh MariaDB password are generated on the first boot of every deployed instance, so two instances launched from the same Amazon Machine Image never share secrets. The administrator and database passwords are written to /root/zenphoto-credentials.txt with mode 0600 so that only the root user can read them.

The whole ZenphotoCMS tree, including the gallery albums, upload staging, image cache and configuration, lives under /var/www on a dedicated EBS volume separate from the operating system disk. The MariaDB data directory sits on its own EBS volume at /var/lib/mysql. Each tier can be resized independently of the others. ZenphotoCMS derives its base URL from the request host, so it works on whatever hostname or IP address you reach it on with no reconfiguration.

Prerequisites

Before you 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 allowing inbound port 22 from your management network and inbound ports 80 and 443 from the networks your visitors and editors will reach ZenphotoCMS on
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: 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 ZenphotoCMS. Select the cloudimg listing and choose Select, then 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, and either create or select a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks your visitors use. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes a few seconds after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg ZenphotoCMS 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, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, and 443 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> \
  --metadata-options "HttpTokens=required,HttpEndpoint=enabled" \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=zenphoto}]'

Connecting to your instance

Connect over SSH on port 22 as the default login user for the operating system variant you launched. The image derives all secrets on first boot, so there is no shared password.

Connect with ssh -i <path-to-key.pem> ubuntu@<instance-public-ip>, substituting your key path and the instance's public IP address.

Step 3: Connect and Retrieve Initial Credentials

On the first boot of the instance a one shot service rotates the MariaDB password and the ZenphotoCMS administrator password to values unique to that instance, and writes them to a root only file. Retrieve them over SSH:

sudo cat /root/zenphoto-credentials.txt

The file lists the administrator user (admin) and password, the browse and backend URLs, and the MariaDB database name, user and password. Store the administrator password somewhere safe and treat the file as sensitive.

Step 4: Verify the Stack is Running

Confirm the three services are active and the application answers on the loopback interface:

systemctl is-active nginx php8.3-fpm mariadb
curl -s http://127.0.0.1/healthz
curl -s -o /dev/null -w 'gallery HTTP %{http_code}\n' http://127.0.0.1/

You should see active three times, ok from the health endpoint, and gallery HTTP 200.

Step 5: Browse the Public Gallery

Open http://<instance-public-ip>/ in a browser. The public gallery renders immediately, with the seeded sample album already visible so the page is never empty on first view.

Click an album to browse its images as a thumbnail grid; click a thumbnail to open the single image view with its EXIF and IPTC metadata, tags and comments.

Step 6: First Login to the Backend

Browse to http://<instance-public-ip>/zp-core/admin.php and sign in with the admin user and the password from /root/zenphoto-credentials.txt.

After signing in you land on the backend Overview, which shows the installation information (ZenphotoCMS version, PHP and MariaDB versions, gallery theme and statistics) and the utility functions for managing your gallery.

Step 7: Change the Administrator Password and Create Albums

From the backend, open Users to change the administrator password and set your own name and email, then open Albums to create your first real album. You can remove the seeded cloudimg-sample album once you have your own content. Use Upload to add images and videos to an album; ZenphotoCMS generates the thumbnails and sized images automatically.

Step 8: Themes

Open Themes in the backend to preview and activate a different gallery theme. ZenphotoCMS ships with several themes and more are available from the ZenphotoCMS extensions site; the active theme controls the look of your public gallery without touching your images or albums.

Step 9: The Zenpage CMS (Pages and News)

ZenphotoCMS includes the Zenpage CMS for static pages plus a news and blog section. Enable and configure it under Options and manage its content from the Pages and News backend tabs, so your site can be a gallery and a simple website at the same time.

Step 10: Users and Per Album Access Control

Open Users to create additional accounts with scoped rights, and set per album access control so that specific albums are visible only to signed in users or to particular users. This lets you publish a public portfolio while keeping private albums restricted.

Step 11: Enable HTTPS with Let's Encrypt

ZenphotoCMS is served over plain HTTP on port 80 so you can front it with TLS. To terminate HTTPS directly on the instance, point a DNS name at the instance and install a certificate with certbot:

sudo apt-get update
sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com

Certbot obtains a certificate, edits the nginx site to serve HTTPS, and installs a renewal timer. ZenphotoCMS follows the request host automatically, so no application reconfiguration is needed.

Step 12: Storage Layout

The application tree and the database sit on their own EBS volumes, each resizable independently of the operating system disk:

df -hT /var/www /var/lib/mysql

/var/www holds the ZenphotoCMS code, the gallery albums, upload staging, the image cache and the configuration; /var/lib/mysql holds the MariaDB data directory. Snapshot these volumes to back up your gallery and its database.

Step 13: Backups and Maintenance

Back up the gallery by snapshotting the two EBS volumes, or export a database dump and archive the albums directory:

sudo mysqldump zenphoto > /tmp/zenphoto-db.sql
sudo tar -czf /tmp/zenphoto-albums.tgz -C /var/www/zenphoto albums

Keep the operating system patched with sudo apt-get update && sudo apt-get upgrade, and manage the services with systemctl (nginx, php8.3-fpm, mariadb).

Screenshots

Support

cloudimg provides 24/7 technical support for this ZenphotoCMS image by email at support@cloudimg.co.uk and by live chat. We help with deployment and initial configuration, theming and gallery layout, user accounts and per album access control, the Zenpage CMS, version upgrades and migration, MariaDB database administration, and troubleshooting. Critical issues receive a one hour average response time.