Skip to content

This chapter is geared towards advanced users. Solid tech skills are required.

Piwigo

Piwigo

Piwigo is a self-hosted photo gallery. Access, organise and share your memories from anywhere. Piwigo supports nested albums, batch editing, multiple users, tags, plugins, themes, and more.

heart No ads • No tracking • Full data ownership heart
Are there alternatives to using Piwigo?

Of course, plenty! Each have their pros and cons. Choose a software which responds to your needs.

Feature Piwigo Photoprism Photoview Pigallery2 Lychee
Creation date 2002 2018 2020 2017 2018
Language PHP Go Go TypeScript PHP
Minimum requirements Apache or nginx, PHP 2 cores, 4GB RAM -- -- Apache or nginx
Database MySQL, MariaDB MySQL, MariaDB SQLite MySQL, Postgres, SQLite SQL or no database MySQL, PostgreSQL or SQLite
Installation Direct install Docker Docker, Direct install Docker, Direct install Docker, Direct install
User interface Basic Modern Modern Basic Modern
Speed Fast Fast Fast Fast Fast
Albums, nested albums
Tags, labels
Auto tags
Face recognition
(automatic)

(manual)
Bulk edit
Duplicate detection ?
Search
Calendar/Timeline
Places/Map
Multi users
Permissions
Sharing
Comments
Delete
RAW file support
Video support
Responsive web interface
Native mobile apps Android & iOS, no auto-upload Android & iOS, experimental auto-upload)
Folder structure support1
(indexing)
WebDAV, FTP support2 ?

[1] Software points to an existing folder structure containing photos/videos, without the need to alter or replicate them. No need for a separate copy of the files. The photos/videos remain untouched if the software is uninstalled.

[2] WebDAV / FTP clients can directly connect to folders containing photos/videos and mount them as a network drive. This way, photos/videos can be added, removed & modified on client devices.


Piwigo MySQL

Database preparation

Piwigo can be deployed with MySQL or MariaDB. In this tutorial, we'll generate a MySQL database required by Piwigo's server components. Read on below for detailed instructions.

Show me the step-by-step guide

Log into the server and access MySQL as root:

sudo mysql -u root -p

Create the MySQL user piwigoadmin (adjust accordingly). Make sure to replace the string StrongPassword with a strong, unique password:

CREATE USER 'piwigoadmin'@localhost IDENTIFIED BY 'StrongPassword';

Next, generate the database required by Piwigo and grant correct permissions:

CREATE DATABASE piwigo;
GRANT ALL ON piwigo.* TO 'piwigoadmin'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Log back into MySQL as the user piwigoadmin:

sudo mysql -u piwigoadmin -p

Make sure the piwigo database has been created correctly:

SHOW DATABASES;

The output should look similar to this:

+--------------------+
| Database           |
+--------------------+
| information_schema |
| piwigo              |
+--------------------+
2 rows in set (0.01 sec)

Exit MySQL:

EXIT;
Show me a summary video


Piwigo installation

Installation

Follow the instructions below to resolve all dependencies and install Piwigo on your server.

Show me the step-by-step guide

Prerequisites

Piwigo requires PHP to run. One of the previous chapters on server hardening covered how to deploy and secure PHP. This should fulfill Piwigo's main software dependencies, such as php7.4-{common,mysql,curl,json,xmlrpc,gd,mbstring,xml,intl,cli,zip}.

Install some additional PHP modules:

sudo apt install php7.4-{cgi,soap,ldap,readline,imap,tidy}
sudo apt install libapache2-mod-php7.4

Installation

Check the latest release of Piwigo's self-hosted package. At the time of writing, it was 11.4.0. Download and decompress the package with the following commands:

wget http://piwigo.org/download/dlcounter.php?code=latest -O /tmp/piwigo.zip
sudo unzip /tmp/piwigo.zip 'piwigo/*' -d /var/www

Set and verify the right permissions:

sudo chown -R www-data:www-data /var/www/piwigo/
sudo chmod -R 755 /var/www/piwigo/
sudo ls -al /var/www/
Show me a summary video


Piwigo web interface

Web interface

We are going to set up an Apache Virtual Host as a Reverse Proxy to access Piwigo's web interface. Read on below for more details on how to set this up.

Show me the step-by-step guide

Create an Apache configuration file:

sudo vi /etc/apache2/sites-available/myphotos.gofoss.duckdns.org.conf

Add the following content and make sure to adjust the settings to your own setup, such as domain names, path to SSL keys, IP addresses and so on:

<VirtualHost *:80>

ServerName              myphotos.gofoss.duckdns.org
ServerAlias             www.myphotos.gofoss.duckdns.org
Redirect permanent /    https://myphotos.gofoss.duckdns.org/

</VirtualHost>

<VirtualHost *:443>

ServerName              myphotos.gofoss.duckdns.org
ServerAlias             www.myphotos.gofoss.duckdns.org
ServerSignature         Off

SecRuleEngine           Off
SSLEngine               On
SSLProxyEngine          On
SSLProxyCheckPeerCN     Off
SSLCertificateFile      /etc/dehydrated/certs/gofoss.duckdns.org/fullchain.pem
SSLCertificateKeyFile   /etc/dehydrated/certs/gofoss.duckdns.org/privkey.pem
DocumentRoot            /var/www/piwigo

<Location />
    Order deny,allow
    Deny from all
    Allow from 127.0.0.1
    Allow from 192.168.1.0/24
    Allow from 10.8.0.1/24
</Location>

<Directory /var/www/piwigo/>
    Options +FollowSymlinks
    AllowOverride All
    Require all granted
</Directory>

ErrorLog ${APACHE_LOG_DIR}/myphotos.gofoss.duckdns.org-error.log
CustomLog ${APACHE_LOG_DIR}/myphotos.gofoss.duckdns.org-access.log combined

</VirtualHost>

Once the content is added, save and close the file (:wq!).

Note how we enable SSL encryption with the instruction SSLEngine On, and use the SSL certicate /etc/dehydrated/certs/gofoss.duckdns.org/fullchain.pem as well as the private SSL key /etc/dehydrated/certs/gofoss.duckdns.org/privkey.pem, which were created earlier on.

Also note how we disabled ModSecurity in the Apache configuration file with the instruction SecRuleEngine Off, as Piwigo and ModSecurity don't play well together.

Next, enable the Apache Virtual Host and restart Apache:

sudo a2ensite myphotos.gofoss.duckdns.org.conf
sudo systemctl reload apache2

Configure Pi-Hole to resolve Piwigo's local address. Browse to https://mypihole.gofoss.duckdns.org (adjust accordingly) and log into Pi-Hole's web interface. Navigate to the menu entry Local DNS Records and add the following domain/IP combination (adjust accordingly):

DOMAIN:      myphotos.gofoss.duckdns.org
IP ADDRESS:  192.168.1.100
Show me a summary video


Piwigo configuration

Configuration

After successfully installing Piwigo, we're going to configure a number of settings such as the maximum upload size, the gallery title, user registration and logging, and so on. More details below.

Show me the step-by-step guide

Maximum photo size

On the server, open the Apache PHP configuration file:

sudo vi /etc/php/7.4/apache2/php.ini

Modify or add the following parameters to increase the maximum upload file size to 20MB:

upload_max_filesize = 20M
post_max_size = 20M

Open the CLI PHP configuration file:

sudo vi /etc/php/7.4/cli/php.ini

Modify or add the following parameters to increase the maximum upload file size to 20MB:

upload_max_filesize = 20M
post_max_size = 20M

Wrap up

Browse to https://myphotos.gofoss.duckdns.org (adjust accordingly) and follow the configuration guide:

Field Description
Host The default value is localhost.
User Provide the name of the MySQL user. In our example, that's piwigoadmin, adjust accordingly.
Password Provide the password of the MySQL user.
Database name Provide the name of the MySQL database. In our example, that's piwigo, adjust accordingly.
Database tables prefix The default value is the name of the MySQL database followed by an underscore. In our exapmle, that's piwigo_.
Admin username Create a webmaster account for Piwigo. For the purpose of this tutorial, we'll call the webmaster piwigoadmin@gofoss.today, adjust accordingly.
Admin password Provide a strong, unique password for the webmaster account.
Admin email Provide an email address for the webmaster account.

Once the configuration is finished, click on the buttons Visit Piwigo and I want to add photos. That's it, Piwigo is ready for use!

Start adjusting some basic settings in Configuration ‣ Options ‣ General:

  • change the gallery title and banner
  • disable user registration (uncheck Allow user registration)
  • track who logs into Piwigo (select Save visits in history for visitors, registered users and/or administrators.)
Show me a summary video


Piwigo get started

Get started

Add users

Piwigo differenciates between three user types, more details are outlined below:

  • Webmasters have full access to Piwigo and can add, edit and remove photos, albums, users, groups, etc. In addition, webmasters can install plugins and themes, maintain and update the website, and so on.

  • Administrators have full access to Piwigo and can add, edit and remove photos, albums, users, groups, and so on.

  • Users have limited access to Piwigo. They can view public albums and photos if they have the right permissions.

Show me the step-by-step guide

Instructions Description
Step 1 Browse to https://myphotos.gofoss.duckdns.org and log in as webmaster piwigoadmin@gofoss.today (adjust accordingly).
Step 2 Navigate to Users ‣ Manage ‣ Add a user.
Step 3 Provide a user name, as well as a strong, unique password. Then click on Submit.
Step 4 Provide the status of the new user, for example user or administrator.

Show me a summary video

In this example, we add a new administrator Georg, and the users Lenina, Tom and RandomUser.

Users must have a working VPN access

Users must be connected to the server via VPN to access Piwigo.

Add photos

The web form only requires a browser. It's best suited to add a manageable amount of pictures, or single albums. Files are uploaded to the server directory /var/www/piwigo/upload. Note that only administrators can add, edit and remove photos. Instructions on how to add photos via the web form are outlined below.

Show me the step-by-step guide

Instructions Description
Log in Log into Piwigo's web interface with an administrator account.
Web form Navigate to Admin ‣ Photos ‣ Add ‣ Web Form.
Piwigo web form
Album Create a new album, or select an existing one.
Add photos Add photos by clicking on the Add Photos button, or dragging and dropping them into the dedicated area.
Upload Click on Start upload.

Show me a summary video

Georg is an administrator user. He uploads eight photos via the web form:

  • four photos from a recent hiking trip with Lenina: tree.png, lake.png, moutain.png and sunset.png
  • four pictures for a project he's working on: logo.png, georg.png, lenina.png and tom.png

This method requires a FTP client, such as FileZilla. It's best suited to add large amounts of files, or upload an entire folder structure at once. Files must be uploaded to the server directory /var/www/piwigo/galleries. The original folder structure will be preserved. Note that only administrators can add, edit and remove photos. Instructions on how to add photos via FTP are outlined below.

Show me the step-by-step guide

Instructions Description
Preparation On your Ubuntu/Linux computer, sort the photos in a folder structure of your choice. Each folder will become an album in Piwigo. The depth of the nested folder tree is unlimited. Make however sure to respect naming conventions: folders and files can only contain letters, numbers, dashes -, underscores _ or dots .. No blank spaces or special characters are allowed.
Login Still on your Ubuntu/Linux computer, log in with the gofossadmin account (adjust accordingly). This is the account with remote SSH access to the server, as configured in the chapters Ubuntu Server and Basic server hardening.
FTP installation If not already installed, open a terminal with the CTRL + ALT + T shortcut and run the command sudo apt install filezilla.
FTP preparation Open FileZilla and provide the correct credentials:

Filezilla

Host: sftp://192.168.1.100 (the server's IP address, adjust accordingly)

Username: gofossadmin (adjust accordingly)

Password: passphrase_used_to_ssh_into_the_server

Port: 2222 (SSH port configured in chapter Basic server hardening, adjust accordingly)
FTP connection Still in FileZilla, click on Quickconnect. You will be prompted once again for the SSH passphrase.
File copy FileZilla should display your local computer's file system in left pane, and the server's file system in the right one. Copy the folders with your pictures to the following directory on the server: /var/www/piwigo/galleries.
Login Log into Piwigo's web interface with an administrator account.
Simulation Navigate to Admin ‣ Tools ‣ Synchronise. Before synchronising anything, select the following settings (adapt the permissions Who can see these photos? to your needs):

Piwigo synchronise

Then click on Submit. Piwigo should display the number of new albums and photos which will be added or removed from the database, and if any errors are to be expected. Proceed if everything is OK.
Synchronisation Still in Admin ‣ Tools ‣ Synchronise, uncheck perform a simulation only:

Piwigo synchronise

Then click on Submit. This may take a while, depending on the amount of data. Grab a cup of coffee!

Some words of advice

Be aware that directories and files shouldn't be moved once they're uploaded to the server. Else, all associated data will be lost during the next synchronisation (such as comments, ratings and so on).

This method requires third party applications. It's best suited to add large amounts of unstructured photos, which are uploaded to the server directory /var/www/piwigo/upload. Note that only administrators can add, edit and remove photos. Some examples of third party applications:

Show me the step-by-step guide

Refer to the respective third party application documentation for instructions on how to add photos. Most third party applications require credentials to connect to the server:

Settings Description
Server Provide the address of the photo gallery. In our example, that's https://myphotos.gofoss.duckdns.org, adust accordingly.
User Provide the name of a Piwigo administrator or user.
Password Provide the password of the Piwigo administrator or user above.

Piwigo phone app

Edit photos

Log in as administrator and browse to Photos ‣ Batch Manager ‣ Global Mode. Apply one or several filters to find the photo you want to edit, as detailed at the end of this section. Hover over the photo and click on Edit. You are now able to modify the photo's:

  • Properties: change the title, author, creation date, album(s), keywords, description, privacy, and so on.
  • Centre of interest: define the most meaningful area of the photo.
  • OpenStreetMap: define geolocation.
Show me a summary video

Georg modifies the author of the picture logo.png.

Editing multiple photos at once is also called batch editing or bulk editing. Log in as administrator and browse to Photos ‣ Batch Manager ‣ Global Mode. Apply one or several filters to find the photos you want to edit, as detailed at the end of this section. You can select or de-select all photos at once by clicking on All or None. Finally, specify what action to perform: delete, associate to one or several album(s), move to an album or dissociate from an album, set keywords, author, title, creation date or geotags and so on.

Show me a summary video

Georg generates multiple size images for the photos from his hiking trip.

Tell me more about filter attributes

Filter attributes Description
Predefined filters Filter all photos, all videos, duplicated photos, latest imported photos, geotagged photos, photos without an attributed album (orphans), photos without keywords, favourite photos, and so on.
Album Filter photos from a specific album.
Keywords Filter photos based on keywords.
Privacy level Filter photos visible by everybody, contacts, friends, family or administrators.
Dimensions Filter photos based on their size.
File size Filter photos based on their file size.
Search Filter photos based on advanced search results. Can be the title, tag, file name, author, creation date, post date, width, height, file size, ratio, and so on.

Manage albums

Log in as administrator and browse to Admin ‣ Album ‣ Manage ‣ List. To create a new album, click on Add album. To edit existing an album, hover the mouse over it and click on Edit. You are now able to modify the album's:

  • Properties: edit the name & description, define a parent album, lock the album (it's only visible to administrators), add photos, manage sub-albums, and so on.
  • Sort order: set automatic ordering or define a manual order
  • Permissions: make the album public (it's visible to anyone with the link) or private (it's only visible to logged in users with appropriate permissions)
Show me a summary video

In this example, administrator Georg adds a description to the album Holidays.

Manage permissions

Piwigo has two systems to manage access permissions, which can be used independently or combined:

  • User/group permissions apply to albums, users and groups
  • Privacy levels apply to photos and users

This rather complex permission system opens up possibilities to fine tune access rights for multiple users. If you don't share Piwigo with others, keep it simple: make all your albums private and limit access to yourself.

Let's start with album-level permissions. By default, albums are public and can be viewed by any user. Administrators can make albums private and limit access to certain users and/or groups. Instructions on how to manage user/group permissions are outlined below.

Show me a step-by-step guide

To make an album private:

Instructions Description
Step 1 Log in as administrator.
Step 2 Browse to Album ‣ Manage ‣ List ‣ Edit ‣ Permissions.
Step 3 Switch access from public to private.

To limit access to private albums to certain users:

Instructions Description
Step 1 Log in as administrator.
Step 2 Either browse to Album ‣ Manage ‣ List ‣ Edit ‣ Permissions and add users which can view the private album to the box Permissions granted.

Or browse to Users ‣ Manage ‣ Edit User ‣ Permissions and define which private albums the user can see (Authorised) or not (Forbidden).

Access rights can also be defined for a set of users, called groups. This allows to set permissions for entire groups, which facilitates permission management if there are many users. To limit access to private albums to certain groups:

Instructions Description
Step 1 Create groups by browsing to Users ‣ Groups ‣ Add Group.
Step 2 Add users to a group by browsing to Users ‣ Manage ‣ Edit User ‣ Groups.
Step 3 Finally, define album access rights for entire groups by browsing to Users ‣ Groups ‣ Permissions.

Privacy levels are defined on a per-photo and per-user level. It allows to precisely define which user can access which photos. Instructions on how to manage these privacy levels are outlined below.

Show me a step-by-step guide

Piwigo manages permissions with five privacy levels. Here is how it works:

  • each photo has a privacy level
  • each user has a privacy level
  • a user must have a privacy level greater or equal to the one of the photos he wants to view. Or put differently, the higher a users privacy level, the more photos he can see

The privacy level of photos can be specified by logging in as administrator and browsing to Photos ‣ Batch Manager ‣ Global Mode. Apply filters as needed, and select the relevant photos. Choose the action Who can see these photos and define the appropriate privacy level:

Privacy level Description
1 Everybody
2 Admins, Family, Friends, Contacts
3 Admins, Family, Friends
4 Admins, Family
5 Admins

The privacy level of a user is defined by logging in as administrator and browsing to Users ‣ Manage ‣ Edit User ‣ Privacy level:

Privacy level Description
1 None
2 Contacts
3 Friends
4 Family
5 Admins

Let's wrap up with a concrete example, applying all concept explained so far. Notice that the same result could have been achieved in a lot of different ways. Piwigo is quite flexible, choose your preferred approach.

Show me the example

Piwigo permissions

Circle Description
1 Georg's user status is set to Administrator. This means he can add, edit and remove photos, albums, users, groups, and so on. Georg's privacy level is set to Admins. Georg therefore has access to all albums and photos.
2 Georg uploaded four photos from a recent hiking trip to the album Holidays: tree.png, lake.png, moutain.png and sunset.png. He doesn't want to share these photos with anyone but Lenina. Lenina status is set to User, meaning that she can only view public albums, or files for which she obtains the right permissions. Georg therefore makes the album Holidays private, and limits access to a group called Hiking, to which only himself and Lenina are assigned.
3 Georg also uploaded four pictures to the album Gofoss: logo.png, georg.png, lenina.png and tom.png. Since it's a public album, everybody can access the picture logo.png.
4 However, Georg set the pictures georg.png, lenina.png and tom.png to the privacy level Family. This means only users with privacy levels Family and above (Admins) have access to these pictures. In this example, it would be Georg (Admins), Lenina (Family) and Tom (Family). RandomUser has no access to those pictures, since his privacy level is Friends.

Show me a summary video

Add plugins & themes

Piwigo's functionalities can be extended with over 350 plugins. Some popular ones:

Plugin Description
Fotorama Full screen slideshow.
Batch downloader Download photo selections as zip file.
Piwigo-Openstreetmap Geolocate your pictures. More info available on the Wiki page.
Grum Plugin Classes Required to run some other plugins.
AStat Extends the statistics generated by Piwigo, e.g. which pages or photos have been visited, for how long, from which IP address, etc.
EXIF view Add EXIF metadata to your photos.
Piwigo-Videojs Support videos in Piwigo: mp4, m4v, ogg, ogv, webm, webmv, etc. More info available on the Wiki page.

Show me a step-by-step guide

Instructions Description
Display plugins To display all installed plugins, log in as webmaster piwigoadmin@gofoss.today (adjust accordingly) and browse to Admin ‣ Plugins ‣ Plugins List:
Piwigo plugins


Active plugins are installed and currently running

Inactive plugins are installed but currently disabled.

• Note that deactivating an active plugin will keep most of its configuration saved, while deleting an inactive plugin will remove any trace (files, configurations, etc).
Update plugins Browse to Admin ‣ Plugins ‣ Check for updates.
Add plugins Browse to Admin ‣ Plugins ‣ Other plugins available. Search for a plugin and click on Install. Browse to Admin ‣ Plugins ‣ Plugins list and activate the installed plugin.

Show me a summary video

Piwigo's layout can be customised with over 140 themes. Log in as webmaster piwigoadmin@gofoss.today (adjust accordingly) and browse to Admin ‣ Configuration ‣ Themes. Download, activate or configure themes of your choice. Some popular ones:

Themes Description
Modus Default theme, comes with several skins.
Bootstrap Darkroom Another modern, feature-rich and mobile-friendly theme.
SimpleNG Based on Bootstrap, responsive theme.

Show me a summary video

Upgrade

Start by backing up all your photos in case anything goes wrong during the update. One possible way is to connect via FTP (FileZilla) as described previously and backup the folders /var/www/galleries and /var/www/upload.

You can also backup Piwigo's database using MySQL dump or server backups. Piwigo's MySQL database is usually stored in /var/lib/mysql.

Upgrading is pretty straight forward. Log in as webmaster piwigoadmin@gofoss.today (adjust accordingly) and browse to Admin ‣ Tools ‣ Updates ‣ Piwigo Update. Click on Update to Piwigo xx.x.x and confirm.

Show me a summary video

Piwigo upgrade


Piwigo support

Support

For further details, refer to Piwigo's documentation or request support from the Piwigo community.


Piwigo