Piwigo Image Gallery

Setup & configuration

Piwigo is installed using the linuxserver.io docker image which is particularly easy to use.

DANGER

Although widely used, Linuxserver.io images do not adhere to many docker principles and are prone to security risks; hence this should be used with respective care.

The docker container itself does not require much setup, only the config and the gallery directory need to be mounted. Both however deserve some further explanation

config directory

The config directory of Piwigo contains a number of folders holding various aspects of a web server's configuration.

• 📁 keys: holds the SSL certificates

• 📁 logs: contains the nginx and PHP logs

• 📁 nginx: the underlying nginx server can be configured here

• 📁 php: contains a php.ini allowing to override the container settings

• 📁 www: contains again various folders:

  • 📁 _data : in this folder all the thumbnails, previews and other image formats/sizes are generated
  • 📁 local: allows the localization/re-design of the website using local CSS etc.
  • 📁 plugins: Piwigo plugins are installed here, and we use plenty of them
  • 📁 template-extension: the template can be extended here
  • 📁 themes: Piwigo offers various themes which are stored here.

Most of the configurations/customizations for Piwigo are implemented using the admin backend of Piwigo:

1. Install plugins - see the admin backend of Piwigo

2. Install and set Bootstrap Darkroom as the standard theme

3. Change the CSS to the look and feel of the KL Harriettes Website. This can either be done directly in ~/docker/piwigo/config/www/local/bootstrap_darkroom-rules.css or through the plugin LocalFiles Editor in Piwigo editing the same file

   INFO

   The bootstrap_darkroom-rules.css file is added during the ansible installation process automatically creating the KL Harriettes specific design

gallery directory

The gallery directory (mounted in our setup to ~/docker/piwigo/images) holds the images which are displayed on the Piwigo website. There are two different ways to add images to the website:

1. The folder galleries. Images can be loaded to this directory including a folder tree structure which will be displayed as an album structure on the website itself. In the Piwigo admin backend these images/folders can be synchronized under Tools → Synchronize.

   TIP

   In our setup this mechanism is/was used to load the images/structure before the launch of the new website. See Backup & Restore below

2. The folder uploads holds the images which are uploaded using the admin backend (Albums -> Manage). The album structure/image assignment is created directly in the database when choosing this path; the images under uploads are structured in folders YYYY/MM/DD according to their upload date

   TIP

   In our setup this mechanism is used for image which are uploaded by HashFlash after the launch of the new website

Besides the usage as a standalone Image Gallery we also use the Piwigo API to pull data directly into the website's frontend (e.g., the image thumbnails for the particular run and the link to the gallery itself)

INFO

An Explorer of the Piwigo API can be reached under https://gallery.klharriettes.org/tools/ws.htm

To load the images for a particular run we use the creation date parameter - we can safely assume that an image was taken at the date of the run - for an API based search in the image galleries. This method is also indirectly used to identify the album link displayed in the frontend - with the assumption of course that all images of a single run are all combined into a single folder.

PIWIGO BUG

The pwg.images.search endpoint is used for the purpose of identifying and loading the image thumbnails which works, but is not optimal. The better choice to do this would be the pwg.images.filteredSearch.create endpoint. This is however not possible as the call runs into an error because the cal_months_in_days() function from the PHP calendar extension is missing in the linuxserver.io docker image

Deployment

The docker container just needs to be started - for a deploying a new version of Piwigo we just rely on the linuxserver.io container image, which needs to be pulled and the container restarted

Backup & Restore

Piwigo as an image management system creates large amounts of (image) data, the backup strategy is defined by the limited storage of the Google Drive account in use. We need to back up configuration and images with as little as possible storage impact.

Configuration

The configuration data is backed up by archiving the complete config folder (see above) excluding www/_data, the folder holding all image thumbnails and rendered sizes of an image. The www/_data holds large amounts of data (13 GB at the time of writing) and can be recreated by Piwigo easily (using up server performance on the downside) in case of data loss.

The backup is managed by the ~/scripts/piwigo/backup_piwigo.sh script and executed using cron every day at 3.20am

Images

For the backup of the images a split approach was implemented in order to keep the storage usage on Google Drive low.

1. Historic images, i.e., images taken before the launch of the new website (2017-02 - 2025-04) are backed up in a single tar-archive and kept outside the standard backup cycle. These images are stored in and have been integrated through the gallery/galleries folder described above. In case of data loss this separate archive needs to be expanded into that folder and synchronized with Piwigo using the respective backend functionality
2. Current Images, i.e., images taken and uploaded after the launch of the new website (2025-04+) are stored in the gallery/uploads folder and backed once a week to Google Drive. The backup is executed using a cron running every Saturday at 3.05am using the rclonecopy function:

/usr/bin/rclone copy --max-age 8d /home/ubuntu/docker/piwigo/images/upload klhhh-google:/Backups/images >> /home/ubuntu/logs/rclone

In case of data loss the backup folder can just be copied over to the Piwigo server.

WARNING

the ansible scripts do not include a script for restoring data. This approach was chosen as the restore is rather fiddly and should be supervised manually