Author	Nejat Hakan
eMail	nejat.hakan@outlook.de
PayPal Me	https://paypal.me/nejathakan

Photo Management Piwigo

Introduction

Welcome to this comprehensive guide on self-hosting Piwigo, a powerful and versatile open-source photo gallery software. In an era where cloud storage often comes with privacy concerns and recurring fees, taking control of your own photo management solution offers significant advantages. Piwigo provides a feature-rich platform for organizing, sharing, and showcasing your digital photo collection, entirely on your own terms and infrastructure.

This guide is designed for university students and self-hosting enthusiasts who want a deep dive into setting up, managing, and mastering Piwigo. We will progress from fundamental concepts and basic setup to intermediate configuration, customization, and finally, advanced administration, optimization, and automation techniques.

What is Piwigo?

Piwigo is a web-based application built primarily using PHP and requiring a database (like MySQL or MariaDB). It allows you to create your own photo gallery website. Key characteristics include:

Self-Hosted: You install and run it on your own server (or a server you control), giving you complete ownership of your data and the application's configuration.
Open Source: The code is freely available, meaning a large community contributes to its development, and you can inspect or even modify it if needed. It's distributed under the GPL license.
Extensible: Piwigo boasts a rich ecosystem of plugins and themes, allowing you to tailor its functionality and appearance precisely to your needs.
Scalable: It can handle galleries ranging from a few hundred personal photos to vast collections with hundreds of thousands or even millions of images.
Feature-Rich: Core features include album management, tagging, user/group management with granular permissions, search capabilities, comments, ratings, batch processing, and much more.

Why Self-Host Piwigo?

Data Privacy and Control: Your photos remain on your server, under your control. You decide who sees what, without third-party data scanning or policy changes affecting your access.
Cost-Effectiveness: While requiring an initial setup effort and potentially server costs, it eliminates recurring subscription fees associated with many commercial cloud photo services, especially for large collections.
Customization: Tailor the look, feel, and functionality exactly how you want it using themes and plugins.
Learning Opportunity: Setting up and managing Piwigo is an excellent way to gain practical experience with web servers, databases, PHP applications, and general server administration – valuable skills in many IT fields.
Longevity: Open-source solutions often have greater longevity than commercial products that might shut down or change business models.

Throughout this guide, we will provide detailed explanations and practical, hands-on workshops to solidify your understanding and empower you to build and maintain your own robust Piwigo instance. Let's begin this journey into the world of self-hosted photo management!

1. Getting Started with Piwigo

This first section covers the essential groundwork needed before you can install and run Piwigo. We'll explore its core concepts, the resources it requires, and the different ways you can get it installed on your server.

Understanding Piwigo Core Concepts

Before diving into installation, it's crucial to grasp the fundamental building blocks of Piwigo. Understanding these concepts will make configuration and daily use much more intuitive.

Photos: The primary content item. Piwigo stores information about each photo (metadata) in its database and links this to the actual image file stored on the server's filesystem. It can handle various formats (JPG, PNG, GIF are standard; others like RAW or TIFF might require plugins or external tools for thumbnail generation).
Albums: The primary way to organize photos. Albums are like folders and can be nested hierarchically to create a structured gallery (e.g., Travel -> Europe -> Italy 2023 -> Rome). Photos can typically reside in one album at a time (though some plugins might alter this). Albums control visibility and inheritance of permissions.
Tags: A more flexible way to categorize photos. Unlike albums, a photo can have multiple tags (e.g., landscape, sunset, beach, person:John Doe). Tags allow users to find related photos across different albums.
Users: Individuals who can log in to Piwigo. Each user has a username, password, and a status (Guest, Generic, Normal, Admin).
- Guest: The default status for anonymous visitors (if allowed). Permissions are usually read-only and defined globally or per album.
- Generic: A special user often used for simplified sharing scenarios, typically with limited rights.
- Normal: Regular registered users who can manage their profile, potentially upload photos (if permitted), and have specific permissions assigned via groups or individually.
- Admin: Has full control over the Piwigo installation, including configuration, user management, plugin/theme installation, and all photos/albums.
Groups: Collections of users. Assigning permissions to groups is much more efficient than managing permissions for individual users, especially with many users. A user can belong to multiple groups.
Permissions: Control who can see which albums and photos. Permissions can be set per album and assigned to users or groups. Piwigo uses a system of private albums and authorization keys. Permissions typically cascade down through nested albums unless explicitly overridden.
Themes: Control the visual appearance (layout, colors, fonts) of your Piwigo gallery. You can switch between installed themes easily.
Plugins: Extend Piwigo's core functionality. They can add features like video support, different upload methods, social media integration, advanced search, metadata editing, security enhancements, and much more. Piwigo's power lies heavily in its extensive plugin library.
Metadata: Information about your photos. Piwigo can read standard metadata embedded in image files (like EXIF data captured by cameras – date, time, camera model, GPS coordinates) and IPTC data (often used for captions, keywords, copyright). This metadata can be displayed alongside photos and used for searching/filtering.

Understanding how these elements interact is key. For instance, you might create a private album, add photos to it, assign a group permission to view that album, and then add specific users to that group.

System Requirements

Ensuring your server meets the necessary requirements is crucial for a smooth installation and optimal performance. Piwigo's requirements can be broken down into hardware and software components.

Hardware:

CPU: While Piwigo itself isn't extremely CPU-intensive for basic browsing, tasks like thumbnail generation, batch processing, and handling many simultaneous users benefit significantly from a moderately powerful processor. A dual-core CPU is a reasonable minimum for personal use; quad-core or more is recommended for larger galleries or more users.
RAM: This is often more critical than CPU. PHP and the database server (MySQL/MariaDB) consume memory.
- Minimum: 1GB RAM might work for a very small, personal gallery with low traffic, but expect potential slowness, especially during uploads or thumbnail generation.
- Recommended: 2GB RAM is a better starting point for comfortable performance for personal/small group use.
- Optimal: 4GB+ RAM is advisable for larger galleries, frequent uploads, multiple users, or when running additional services (like Docker) on the same machine. More RAM allows for better database caching and smoother PHP operation.
Storage: This depends entirely on the size and quantity of your photos and their generated thumbnails/multiple sizes.
- Operating System & Software: Allocate at least 10-20GB for the OS, web server, PHP, database, and Piwigo application files.
- Photos: Calculate the total size of your photo library. Remember that Piwigo often generates multiple smaller versions (thumbnails, medium size, etc.) for each original image, potentially doubling or tripling the storage needed per photo within the Piwigo structure. Therefore, if your original photos total 100GB, you might need 200-300GB allocated for the Piwigo gallery data (_data and galleries directories).
- Database: The database itself is usually relatively small compared to the photo files, storing metadata, user info, album structures, etc. A few gigabytes should suffice unless you have millions of photos with extensive metadata/tags/comments.
- Recommendation: Start with ample space and monitor usage. Using technologies like LVM (Logical Volume Management) on Linux can make resizing partitions easier later. Fast storage (SSD) significantly improves database performance and thumbnail access speed compared to traditional HDDs.

Software:

Operating System: Piwigo runs best on a Linux-based OS (Debian, Ubuntu, CentOS, Fedora are common choices). It can technically run on Windows or macOS using appropriate server stacks (like WAMP/MAMP), but Linux is the most common deployment environment.
Web Server: Required to serve the Piwigo web pages.
- Apache: A popular, robust choice. Requires mod_php or PHP-FPM. .htaccess files are often used for configuration (like rewrite rules).
- Nginx: Known for high performance and low resource usage, especially under load. Typically used with PHP-FPM (FastCGI Process Manager). Configuration is done in Nginx's own config files.
PHP: The scripting language Piwigo is written in.
- Version: Check the official Piwigo website for the specific compatible PHP versions for the Piwigo version you intend to install. Requirements change over time. As of late 2023/early 2024, PHP 7.4, 8.0, 8.1, or 8.2 are typically supported, but always verify.
- Required Extensions: Piwigo needs several PHP extensions. The installer usually checks for these, but common requirements include:
  - gd or imagick: For image processing (thumbnail generation, resizing). Imagick is generally more powerful and supports more formats but might require separate installation of the ImageMagick library.
  - mysqli or pdo_mysql: To connect to the MySQL/MariaDB database.
  - json: For handling JSON data (used extensively in modern web apps).
  - xml: For XML parsing.
  - mbstring: For multi-byte string handling (important for international characters).
  - exif: To read EXIF metadata from photos (highly recommended).
  - session: For managing user sessions.
- PHP Configuration: Pay attention to settings in php.ini, especially:
  - memory_limit: Set high enough to handle large image uploads and processing (e.g., 128M, 256M, or even 512M+ depending on image size and server RAM).
  - upload_max_filesize: Maximum size for a single uploaded file.
  - post_max_size: Maximum size of POST data (must be >= upload_max_filesize).
  - max_execution_time: Maximum time a script can run. Thumbnail generation for large files might require increasing this.
Database: Stores all metadata, user information, albums, tags, comments, etc.
- MySQL: Versions 5.x or later are typically required.
- MariaDB: A popular open-source fork of MySQL, generally fully compatible. Versions 10.x or later are recommended.
- PostgreSQL: Support might be available via specific plugins or forks but is less common for standard Piwigo installations compared to MySQL/MariaDB.
Image Processing Library (Optional but Recommended):
- ImageMagick: A powerful command-line image manipulation suite. If installed, Piwigo (often via the imagick PHP extension) can use it for more advanced image processing and wider format support (like RAW conversion, PDF previews, etc.) compared to the GD library.
- GD Library: Usually included with PHP, provides basic image manipulation capabilities sufficient for standard JPEG/PNG/GIF handling.

Meeting these requirements, especially the PHP version and extensions, is critical for a successful installation.

Choosing an Installation Method

There are several ways to install Piwigo, each with its own advantages and disadvantages. The best method depends on your technical expertise, existing server setup, and desired level of control.

Manual Installation (LAMP/LEMP Stack):
- Description: This involves manually setting up the required components: Linux OS, Apache/Nginx (Web Server), MySQL/MariaDB (Database), and PHP. You then download the Piwigo archive, extract it to the web server's document root, create a database and user, and run the web-based installer.
- Pros:
  - Full Control: You manage every component directly.
  - Resource Efficiency: Can be more resource-efficient than containerized solutions if properly optimized, as there's no virtualization overhead.
  - Flexibility: Easy to integrate with other manually installed web applications on the same server.
  - Learning: Provides deep understanding of the underlying stack.
- Cons:
  - Complexity: Requires knowledge of Linux server administration, web server configuration, database management, and PHP setup.
  - Time-Consuming: Initial setup and ongoing maintenance (updates for OS, web server, PHP, database) can take significant time.
  - Dependency Management: Ensuring correct PHP versions and extensions are installed and configured can be tricky.
  - Potential Conflicts: Installing multiple applications manually can lead to dependency conflicts.
Docker / Docker Compose:
- Description: This method uses containers to package Piwigo and its dependencies (like the database and potentially a web server/PHP-FPM). You define the services in a docker-compose.yml file, and Docker handles downloading the necessary images, creating containers, and linking them. Official or community-maintained Piwigo Docker images are available.
- Pros:
  - Simplified Setup: Significantly easier and faster to get started, especially for beginners. docker-compose up often brings up the entire stack.
  - Isolation: Dependencies are contained within the Docker environment, preventing conflicts with other applications on the host system.
  - Reproducibility: The docker-compose.yml file defines the exact environment, making it easy to replicate the setup elsewhere.
  - Easier Updates: Updating Piwigo or its dependencies often involves just pulling a newer Docker image and restarting the containers (though data migration considerations still apply).
  - Clean Uninstallation: Removing Piwigo is as simple as stopping and removing the containers and associated volumes.
- Cons:
  - Learning Curve: Requires understanding basic Docker and Docker Compose concepts (images, containers, volumes, networking).
  - Resource Overhead: Docker introduces a small layer of abstraction, which can consume slightly more RAM and disk space compared to a bare-metal install, although this is often negligible on modern hardware.
  - Configuration Abstraction: Configuration (like PHP settings or web server tweaks) might need to be done through environment variables or by mounting custom configuration files into the containers, which can feel less direct than editing files on a manual install.
Shared Hosting (with Piwigo Support):
- Description: Some web hosting providers offer "one-click" installers (like Softaculous or Fantastico) that include Piwigo. You use the hosting control panel (e.g., cPanel) to install Piwigo automatically.
- Pros:
  - Easiest Setup: Often just a few clicks.
  - Managed Environment: The hosting provider manages the underlying server, OS, web server, PHP, and database updates.
- Cons:
  - Less Control: Limited control over server configuration, PHP settings (memory_limit, upload_max_filesize are often restricted), and component versions.
  - Performance: Shared hosting environments can suffer from performance issues due to shared resources ("noisy neighbors").
  - Limited Access: Usually no SSH access or limited command-line capabilities, making advanced troubleshooting or customization difficult.
  - Not Truly "Self-Hosted": While you manage the Piwigo application, you don't control the underlying infrastructure. This guide focuses on true self-hosting (Manual or Docker).
Virtual Private Server (VPS) or Dedicated Server:
- Description: You rent a virtual or physical server from a provider (like DigitalOcean, Linode, Hetzner, OVH). You get full root access and can choose your OS. You would then typically use either the Manual Installation or Docker method on this server.
- Pros: Combines the control of self-hosting with the convenience of not managing physical hardware. Scalable resources.
- Cons: Requires server administration skills. You are responsible for security, updates, and backups. Costs associated with the server rental.

Recommendation for this Guide:

While manual installation offers the most control, the Docker/Docker Compose method provides the best balance of ease of use, reproducibility, and control for most self-hosters, especially those learning. The workshops in this guide will primarily focus on the Docker approach, assuming you have Docker and Docker Compose installed on your host system (which could be a Linux machine, a VPS, or even Windows/macOS with Docker Desktop).

Workshop Basic Setup via Docker Compose

This workshop guides you through setting up a basic Piwigo instance using Docker Compose. This assumes you have Docker and Docker Compose installed on your Linux server or machine.

Objective: Launch Piwigo and a MariaDB database using Docker Compose, access the web installer, and complete the basic setup.

Prerequisites:

A Linux system (or VPS) with Docker and Docker Compose installed.
Basic command-line familiarity.
Internet access to download Docker images.

Steps:

Create a Project Directory:
- Choose a location on your server to store the Piwigo configuration files. Let's use /opt/piwigo.
- Open your terminal and create the directory:
```
sudo mkdir -p /opt/piwigo/database /opt/piwigo/gallery
cd /opt/piwigo
```
- We create subdirectories for the database data and the Piwigo gallery data to keep things organized. Docker volumes will be mapped here.

Create the docker-compose.yml File:

Inside the /opt/piwigo directory, create a file named docker-compose.yml using a text editor (like nano or vim):
```
sudo nano docker-compose.yml
```

Paste the following configuration into the file. Read the comments carefully and adjust passwords and ports if necessary.

version: '3.7' # Specify docker-compose version

services:
  piwigo-db: # Service name for the database container
    image: mariadb:10.9 # Use MariaDB version 10.9 image
    container_name: piwigo_db # Explicit container name
    command: --transaction-isolation=READ-COMMITTED --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci # Recommended DB settings for Piwigo
    volumes:
      - ./database:/var/lib/mysql # Mount local directory for persistent DB data
    environment:
      MYSQL_ROOT_PASSWORD: 'CHANGEME_ROOT_DB_PASSWORD' # CHANGE THIS! Strong password for DB root
      MYSQL_DATABASE: 'piwigo_gallery' # Database name Piwigo will use
      MYSQL_USER: 'piwigo_user' # Database user Piwigo will use
      MYSQL_PASSWORD: 'CHANGEME_PIWIGO_DB_PASSWORD' # CHANGE THIS! Strong password for Piwigo DB user
    restart: unless-stopped # Restart container if it stops unexpectedly
    networks:
      - piwigo-net

  piwigo-app: # Service name for the Piwigo application container
    image: linuxserver/piwigo:latest # Use the linuxserver.io image (popular & well-maintained)
    container_name: piwigo_app # Explicit container name
    depends_on:
      - piwigo-db # Ensure DB starts before the app
    volumes:
      - ./gallery:/config/www/gallery # Mount local directory for photos (IMPORTANT!)
      - ./piwigo-config:/config # Mount local directory for Piwigo config files (plugins, themes, local config)
    environment:
      PUID: '1000' # CHANGE THIS to your user's ID (run `id -u` in terminal)
      PGID: '1000' # CHANGE THIS to your user's group ID (run `id -g` in terminal)
      TZ: 'Europe/Berlin' # CHANGE THIS to your timezone (e.g., America/New_York)
      DB_HOST: piwigo-db # Hostname to reach the DB container (matches DB service name)
      DB_PORT: 3306 # Standard MySQL/MariaDB port
      DB_NAME: 'piwigo_gallery' # Must match MYSQL_DATABASE above
      DB_USER: 'piwigo_user' # Must match MYSQL_USER above
      DB_PASSWORD: 'CHANGEME_PIWIGO_DB_PASSWORD' # Must match MYSQL_PASSWORD above
    ports:
      - "8080:80" # Map host port 8080 to container port 80 (Change 8080 if needed)
      # - "8443:443" # Uncomment and configure if setting up HTTPS directly in container (less common)
    restart: unless-stopped
    networks:
      - piwigo-net

networks: # Define the network for containers to communicate
  piwigo-net:
    driver: bridge # Use the default bridge network driver

volumes: # Define named volumes (alternative to bind mounts shown above)
    # If you prefer named volumes over bind mounts:
    # database:
    # gallery:
    # piwigo-config:
    # And change the 'volumes:' sections in services accordingly, e.g.:
    # volumes:
    #   - database:/var/lib/mysql
    #   - gallery:/config/www/gallery
    #   - piwigo-config:/config
    # Named volumes are managed by Docker and often preferred for simplicity.
    # Bind mounts (like in the example above) map directly to host paths, giving easier direct access. Choose one style.
    # For this example, we use bind mounts for easier direct access to gallery files.

Important:
- Change Passwords: Replace CHANGEME_ROOT_DB_PASSWORD and CHANGEME_PIWIGO_DB_PASSWORD with unique, strong passwords. Ensure the Piwigo user password matches in both piwigo-db and piwigo-app environment sections.
- PUID/PGID: Replace 1000 with the actual User ID (UID) and Group ID (GID) of the user running Docker on the host machine. Find these by running id -u and id -g in your terminal. This ensures correct file permissions for the mounted volumes (gallery and piwigo-config).
- TZ: Set your correct timezone. Find yours from the list usually found in /usr/share/zoneinfo.
- Port Mapping: The ports: - "8080:80" line maps port 8080 on your host machine to port 80 inside the Piwigo container. If port 8080 is already in use on your host, change 8080 to an available port (e.g., 8181).
- Volumes: We are using bind mounts here (./database:/var/lib/mysql, etc.). This maps directories from your host (/opt/piwigo/database, /opt/piwigo/gallery, /opt/piwigo/piwigo-config) directly into the containers. Ensure the host directories exist and have appropriate permissions (Docker might create them, but it's good practice to pre-create them). The gallery volume is crucial – this is where Piwigo will store your uploaded photos. The piwigo-config volume stores Piwigo's configuration, installed plugins, themes, etc.
Save and close the file (e.g., in nano, press Ctrl+X, then Y, then Enter).

Set Permissions (If Necessary):
- Ensure the user defined by PUID/PGID has write permissions to the ./database, ./gallery, and ./piwigo-config directories you created or that Docker will create/use. If you created them with sudo, you might need to change ownership:
```
# Example: If your user ID and group ID are 1000
sudo chown -R 1000:1000 /opt/piwigo/database
sudo chown -R 1000:1000 /opt/piwigo/gallery
sudo mkdir /opt/piwigo/piwigo-config # Create config dir if it doesn't exist yet
sudo chown -R 1000:1000 /opt/piwigo/piwigo-config
```
- Replace 1000:1000 with your actual UID:GID.
Launch the Containers:
- While still in the /opt/piwigo directory (where your docker-compose.yml file is), run:
```
sudo docker-compose up -d
```
- up tells Docker Compose to start the services defined in the file.
- -d runs the containers in detached mode (in the background).
- Docker will now download the mariadb:10.9 and linuxserver/piwigo:latest images if you don't have them locally. This might take a few minutes depending on your internet speed.
- You'll see output as it creates the network and the containers.
Check Container Status:
- Verify that both containers are running:
```
sudo docker-compose ps
```
- You should see piwigo_db and piwigo_app listed with a state of Up.
- You can also view logs (especially if something seems wrong):
```
sudo docker-compose logs -f # View logs for both containers (Ctrl+C to exit)
sudo docker-compose logs -f piwigo-app # View logs for just the app
```
Access the Piwigo Web Installer:
- Open your web browser and navigate to the IP address or hostname of your server, followed by the port you specified in the docker-compose.yml file (e.g., http://YOUR_SERVER_IP:8080).
- You should be greeted by the Piwigo installation screen.
Complete the Installation:
- Database Configuration: The values should be pre-filled based on the environment variables you set in docker-compose.yml:
  - Host: piwigo-db (the service name of the database container)
  - User: piwigo_user
  - Password: The password you set for MYSQL_PASSWORD / DB_PASSWORD.
  - Database name: piwigo_gallery
  - Table prefix: piwigo_ (you can leave this as default).
- Administration Configuration: Create your Piwigo admin account:
  - Username: Choose an admin username (e.g., admin).
  - Password: Set a strong password for the Piwigo admin user.
  - Email address: Enter your email address.
- Click "Start Installation". Piwigo will connect to the database, create the necessary tables, and set up the basic configuration.
- If successful, you'll see a confirmation message.
First Login:
- Click the button or link to go to your gallery.
- Log in using the Piwigo admin username and password you just created.

Congratulations! You have successfully installed Piwigo using Docker Compose. Your Piwigo instance is running, and the database data and gallery files are persistently stored in the /opt/piwigo/database and /opt/piwigo/gallery directories on your host machine, respectively. Configuration files are in /opt/piwigo/piwigo-config. You can now proceed to configure Piwigo further.

To Stop Piwigo:

cd /opt/piwigo
sudo docker-compose down # Stops and removes the containers, but data in volumes persists

To Restart Piwigo:

cd /opt/piwigo
sudo docker-compose up -d

2. Core Configuration and Management

With Piwigo installed, the next step is to configure it to suit your needs and start managing your users and photos effectively. This section covers the essential administrative tasks you'll perform regularly.

Initial Configuration Walkthrough

After your first login as the administrator, you'll land on the Piwigo dashboard. The administration interface is typically accessed by clicking the "Administration" link (often in the header or footer, depending on the theme). Let's explore the key configuration areas found under Administration -> Configuration -> Options.

General:
- Gallery title: The main title displayed in the browser tab and potentially in the theme header. Make it descriptive (e.g., "John Doe's Photo Gallery").
- Page banner: The text or HTML displayed at the top of gallery pages.
- Default theme: Select the active theme for users who haven't chosen a specific one (we'll cover themes later).
- Default language: Set the language for guests and new users. Piwigo supports many languages.
- Recent period: Defines how many days photos are considered "recent" (e.g., for display on the homepage or in feeds).
- Expand all albums: Whether the album menu should show all sub-albums by default or be collapsed. Recommended to keep collapsed for large galleries.
- Allow user registration: Enable/disable the ability for visitors to register themselves as users. For private galleries, you'll likely want to disable this and create users manually.
Display:
- Number of photos per page: Controls pagination on album pages. Adjust based on preference and performance.
- Number of albums per page: Controls pagination for sub-album lists.
- Default thumbnail size: Choose the default size for thumbnails displayed on album pages. Themes might offer different sizes.
- Default sort order: Set how photos are sorted within albums by default (e.g., by date created, date posted, title, randomly). Users can often override this.
- Display photo information: Select which metadata fields (like date, dimensions, file size, EXIF data) are shown below the photo on the picture page.
Upload:
- Via Web Form:
  - Use HTML5 uploader: Generally recommended for modern browsers, allows drag-and-drop and multiple file selection.
  - Resize photos upon upload: Crucial setting. You can configure Piwigo to automatically resize uploaded images to a maximum width/height. This saves storage space and improves loading times, especially if users upload very large originals. Set reasonable limits (e.g., 1920px or 2560px width/height) unless you absolutely need to store originals at full resolution within the accessible Piwigo gallery structure. Note: The original file might still be kept depending on configuration or plugins, often in an upload directory separate from the main galleries directory structure where processed images reside. Understand how your chosen upload method/plugins handle originals vs. web-viewable versions.
  - Image quality: Set the JPEG compression quality (e.g., 85-95) for resized images. Higher quality means larger file sizes.
- Via External Applications (like Shotwell, Lightroom, Mobile Apps): Piwigo has remote sync capabilities. Some settings here might relate to default album assignments or permissions for remotely added photos. We'll touch on this more in automation.
Watermark: (Optional)
- If you want to protect your images, you can configure Piwigo to automatically add a watermark (text or an image file) to your photos.
- Configure the text, font, opacity, position, and choose whether to apply it to newly uploaded photos.
- Important: Applying watermarks is a processing step. It usually applies to the web-viewable sizes (medium, large), not necessarily the original file (depending on setup). You can often choose to re-apply watermarks to existing photos, but this can be resource-intensive. Test thoroughly on a few images first.
Comments:
- Allow user comments: Enable/disable the commenting feature on photos.
- Guests can post comments: Decide if anonymous users can comment. Requires moderation if enabled.
- Email administrators upon new comment: Receive notifications for moderation.
- Validate comments before display: Recommended, especially if guests can comment, to prevent spam or abuse.
Default Permissions:
- Default permissions for new albums: Set the default privacy level when a new album is created (e.g., accessible to Admins only, accessible to all users, accessible to guests). Setting this to Admins only is often safer, forcing you to explicitly grant access later.

Take your time exploring these options. Hovering over setting labels often provides helpful tooltips explaining their purpose. Remember to click "Submit" or "Save Settings" on each relevant page after making changes.

User and Group Management

Managing who can access your Piwigo gallery and what they can do is fundamental, especially for private or multi-user galleries. Piwigo offers a flexible system based on users, groups, and permissions. Access these settings under Administration -> Users and Administration -> Groups.

Users: (Administration -> Users -> Manage)

Creating Users: Click "Add a user". You'll need to provide:
- Username: A unique identifier for login.
- Password: Set a strong password.
- Email (Optional but recommended): Used for notifications and password resets.
- Status:
  - Guest: Cannot log in. Represents anonymous visitors.
  - Generic: A special status, less commonly used. Can log in but often has limited, pre-defined rights.
  - Normal: A standard registered user. Permissions are primarily determined by group memberships or specific individual permissions. Can potentially upload photos if granted rights.
  - Admin: Full control over the entire Piwigo instance. Use sparingly.
- Level: (Deprecated in some views, largely replaced by Status/Groups) Historically represented permission levels (0-8). Primarily relevant if using older plugins or configurations. Focus on Status and Group permissions.
Managing Existing Users: You can edit user details, change passwords, modify status, add/remove users from groups, and delete users.
Special Users:
- webmaster: Often the initial admin account created during installation. Has Admin status.
- guest: Represents anonymous visitors. You don't manage this user directly but configure guest access via default permissions and album/group permissions.

Groups: (Administration -> Groups -> Manage)

Why Use Groups? Assigning permissions directly to dozens or hundreds of users is tedious and error-prone. Groups allow you to define a set of permissions once and then simply add or remove users from that group. Examples: "Family", "Friends", "Clients Project X", "Photography Club Members".
Creating Groups: Click "Create a new group", give it a meaningful name.
Managing Groups:
- Assign Users: Select a group, then click "Add users to group". Choose users from the list.
- Assign Permissions: This is the most critical part. Permissions in Piwigo are primarily managed per album. You grant groups (or individual users) access to specific albums. Go to Administration -> Albums -> Manage. Select an album, then look for a "Permissions" or "Properties" tab/button. Here you can associate groups (or users) with that album, granting them viewing rights. If an album is marked as "private", only users/groups explicitly granted permission (and administrators) can see it. Permissions usually cascade down to sub-albums unless overridden.

Permissions System Explained:

Album Privacy: Each album can be Public (visible to guests if guest access is enabled globally) or Private (visible only to logged-in users with specific permissions or admins).
Granting Access: For Private albums, you must grant access. This is done by associating users or groups with the album in the album's permission settings.
Cascading: If you grant the "Family" group access to the main "Family Photos" album, users in the "Family" group will typically also be able to see sub-albums like "Family Photos -> Christmas 2023" unless you specifically restrict access to the sub-album.
Multiple Groups: A user can be in multiple groups. They gain the combined permissions of all groups they belong to. If Group A grants access to Album X and Group B grants access to Album Y, a user in both groups can see both albums.
Individual Permissions: While less common for management, you can sometimes assign permissions directly to a specific user for an album, overriding or supplementing their group permissions. Relying on groups is generally better practice.

Best Practices:

Use the Admin status only for trusted administrators who need full control.
Create Normal users for everyone else.
Leverage Groups extensively for managing permissions. Create groups based on relationships or access needs.
Set newly created albums to be Private by default (Administration -> Configuration -> Options -> Default Permissions) and explicitly grant access via groups. This prevents accidental public exposure.
Regularly review group memberships and album permissions.

Organizing Photos Albums and Tags

A well-organized gallery is easier to navigate and use. Piwigo offers two primary organization methods: hierarchical albums and flexible tags.

Albums (Administration -> Albums -> Manage):

Structure: Think about a logical hierarchy before uploading thousands of photos. Common structures include:
- By Event/Date: Events -> 2024 -> Birthday Party, Holidays -> Summer 2023 -> Beach Trip
- By Subject: Landscapes, Portraits -> Family, Portraits -> Friends, Projects -> Client A
- By Source: Phone Uploads, DSLR Photos -> Nature, DSLR Photos -> Studio
- A combination often works best.
Creating Albums: Click the "Add an album" button. You can create top-level albums or sub-albums within existing ones. Give them clear, concise names. You can also add descriptions.
Moving Albums: You can drag and drop albums in the management interface to rearrange them or change their parent album.
Virtual vs. Physical Albums: Piwigo primarily uses a "physical" album structure by default. When you upload photos via the web interface, Piwigo typically organizes the files on the server's filesystem within the galleries directory, mirroring your album structure. However, Piwigo also supports synchronization with existing directory structures on your server (more on this later), effectively creating "virtual" albums linked to those directories. For now, focus on the albums you create within Piwigo itself.
Album Thumbnails: Choose a representative photo from within an album to be its thumbnail (cover image). This is done via the album properties/settings.

Tags (Administration -> Tags -> Manage):

Purpose: Tags provide a non-hierarchical way to label and find photos across different albums. A photo of a sunset on a beach during a trip to Italy could be tagged sunset, beach, landscape, travel, Italy.
Creating Tags: You can often create tags directly when editing a photo's details or manage them centrally via Administration -> Tags.
Assigning Tags:
- Individually: Go to a photo's page, click "Edit photo information", and add tags in the relevant field (often comma-separated).
- Batch Manager: This is essential for efficiency. Go to Administration -> Photos -> Batch Manager. Select multiple photos (e.g., all photos in an album or search results). In the action dropdown, choose "Associate tags" or "Dissociate tags". Select the tags you want to add or remove and apply the action.
Tagging Strategies:
- Be Consistent: Use sunset, not sunset, sun set, sundown.
- Be Specific but Relevant: Tag key subjects, locations, people, or themes. Avoid overly generic tags unless useful for broad filtering.
- Consider Hierarchical Tags (via Plugins): Some plugins allow creating tag hierarchies (e.g., Location > Country > City). This can be very powerful but adds complexity. The core supports flat tags.
- Use Cases: Finding all photos tagged John Doe, finding all photos tagged landscape across all albums, finding photos tagged project_alpha.

Batch Management (Administration -> Photos -> Batch Manager):

This tool is indispensable for managing large numbers of photos efficiently.

Selection: Select photos based on album, date, tags, search results, etc.
Actions: Perform actions on the selected photos:
- Move to album: Relocate photos.
- Associate/Dissociate tags: Add or remove tags.
- Set representative: Mark photos as album thumbnails (if applicable in context).
- Edit author, title, description: Modify metadata (though individual editing might be better for unique descriptions).
- Set permissions: Apply permissions (less common here, usually done at the album level).
- Delete: Remove photos (use with caution!).
- Synchronize metadata: Re-read metadata from files if needed.

Mastering albums, tags, and the batch manager is key to maintaining a usable and organized Piwigo gallery as your collection grows.

Workshop Organizing Your First Photo Collection

This workshop simulates organizing a small set of photos for a fictional event, applying the concepts of albums, tags, user groups, and permissions.

Objective: Create a specific album structure, upload photos, tag them, create a dedicated user group, and grant that group access to the newly created albums.

Prerequisites:

A running Piwigo instance (from the previous workshop or similar setup).
Admin access to Piwigo.
A small collection of sample photos (5-10 JPGs, ideally with varied subjects/content). You can download royalty-free images if needed (e.g., from Unsplash, Pexels).

Steps:

Create the Album Structure:
- Log in to Piwigo as the administrator.
- Navigate to Administration -> Albums -> Manage.
- Click "Add an album". Name it Events and click "Add album".
- Select the Events album in the list on the left. Now, with Events selected, click "Add an album" again. Name this one 2024 and click "Add album". This creates 2024 as a sub-album of Events.
- Select the 2024 album. Click "Add an album" again. Name this one Community Picnic and click "Add album".
- You should now have the structure: Home -> Events -> 2024 -> Community Picnic.
Set Album Permissions (Make it Private Initially):
- While still in Administration -> Albums -> Manage, select the Community Picnic album.
- Look for a "Properties" or "Edit" button/tab associated with the selected album.
- Find the setting for album privacy or access. Set it to Private (meaning only admins and specifically authorized users/groups can see it). The exact wording might vary slightly by Piwigo version/theme. Ensure this setting applies. Alternatively, if you set the default for new albums to private earlier, this might already be done.
- Optional: You might want to make the parent albums (Events, 2024) private as well, unless you intend to have other public sub-albums under them later. For this exercise, let's make Events and 2024 private too using the same method.
Upload Photos:
- Navigate to the Community Picnic album in the main gallery view (you might need to go back to the gallery from Administration).
- Look for an "Add Photos" or "Upload" link/button (often available when viewing an album as admin).
- Use the web uploader (HTML5 recommended) to select your 5-10 sample photos.
- Ensure they are uploaded successfully into the Community Picnic album. You might need to configure upload settings (like resizing) under Administration -> Configuration -> Options -> Upload if you encounter issues or want to enforce resizing. For this exercise, default settings are likely fine.
Add Tags using Batch Manager:
- Navigate to Administration -> Photos -> Batch Manager.
- In the filter/selection area, choose the Community Picnic album to display only the photos you just uploaded.
- Select all the photos in the batch manager view (there's usually a "Select all" checkbox).
- In the "Action" dropdown menu at the bottom, select "Associate tags".
- In the text box that appears, type the following tags, separated by commas: event, picnic, community, 2024.
- Click the "Submit" or "Apply" button next to the action dropdown. The tags should now be associated with all selected photos.
- Optional: Select a few specific photos (e.g., those showing food) and associate an additional tag like food. Select photos showing people and add a tag like people. This demonstrates adding multiple, relevant tags.
Create a User Group:
- Navigate to Administration -> Groups -> Manage.
- Click "Create a new group".
- Enter the name Picnic Attendees and click "Submit".
Create a Test User (Optional but Recommended):
- If you don't have any non-admin users, create one for testing:
- Go to Administration -> Users -> Manage.
- Click "Add a user".
- Username: testuser
- Password: someSecurePassword123 (use a better one!)
- Status: Normal
- Click "Add user".
Add User to Group:
- Go back to Administration -> Groups -> Manage.
- Select the Picnic Attendees group.
- Click the "Add users to group" button/link.
- Find testuser (or another non-admin user) in the list, check the box next to their name, and click "Submit" or "Add selected users".
Grant Group Permissions to the Album:
- Navigate back to Administration -> Albums -> Manage.
- Select the Community Picnic album.
- Go to its "Properties" or "Edit" section again, specifically looking for "Permissions".
- You should see lists of users and groups. Find the Picnic Attendees group.
- Click the button/link to grant this group access to the album (often an "Add" or "+" icon, or moving it to an "Authorized Groups" list).
- Save the permission changes for the album.
- Important: For the user to navigate to the Community Picnic album, they also need viewing permission on the parent albums (Events and 2024). Repeat this step for the Events album and the 2024 album, granting Picnic Attendees group access to them as well.
Verify Permissions:
- Log out from your admin account.
- Log in as testuser (or the user you added to the Picnic Attendees group).
- You should now be able to see the Events album, navigate into 2024, and then into Community Picnic to view the uploaded photos.
- Try accessing other parts of the gallery – you should only see what testuser has permission for (which might only be the picnic photos if all other albums are private or restricted).
- Try searching for tags like picnic or community. The photos should appear in the search results.
- Log out from testuser and log back in as admin.

This workshop demonstrates the core workflow of organizing content and managing access in Piwigo. By creating structured albums, applying relevant tags, and using groups for permissions, you can effectively manage even large and complex photo collections.

3. Enhancing Piwigo with Themes and Plugins

One of Piwigo's greatest strengths is its extensibility. Core Piwigo provides a solid foundation, but themes and plugins unlock a vast potential for customization and added functionality, allowing you to tailor your gallery precisely to your aesthetic preferences and functional requirements.

Understanding the Plugin Ecosystem

Plugins are packages of code that add new features or modify existing behaviors in Piwigo without altering the core application code. This modular approach makes it easy to enhance your gallery and keeps the core system cleaner and easier to update.

How Plugins Work:

When installed and activated, a plugin's code integrates with Piwigo through defined "hooks" or APIs.
They can add new menu items in the administration area for configuration.
They might add new features to the gallery front-end (e.g., social sharing buttons, slideshow viewers).
They can perform actions in the background (e.g., synchronizing files, processing metadata).
They reside in the plugins directory of your Piwigo installation (within the piwigo-config volume in our Docker setup: /opt/piwigo/piwigo-config/plugins).

Plugin Categories (Examples):

Uploaders: Provide alternative ways to upload photos (e.g., via FTP sync, Lightroom publisher, mobile apps, drag-and-drop from desktop).
- Examples: Community (for FTP sync), Piwigo Upload Plugin for Lightroom.
Media Support: Add support for video playback, RAW file previews, PDF viewing.
- Examples: VideoJS, RAW File Decoder (may require server-side tools like dcraw), PDF Viewer.
Metadata & Tagging: Enhance metadata handling (EXIF/IPTC editing), offer advanced tagging features (hierarchical tags, AI-based tagging).
- Examples: Admin Tools (includes metadata sync), User Tags Edit, Tag Manager, potential AI tagging integrations (often external/paid).
Security: Add features like Two-Factor Authentication (2FA), CAPTCHAs, IP address blocking.
- Examples: Google Authenticator Plugin, Stop Spammers.
User Experience & Display: Offer different ways to view photos (slideshows, maps based on GPS data), improve navigation, add social features (ratings, favorites, sharing).
- Examples: Fotorama (slideshow), RV Maps & Earth (GPS maps), User Collections (favorites), Social Connect.
Administration & Tools: Provide batch management enhancements, database maintenance tools, statistics viewers.
- Examples: Admin Tools (essential!), DB Checks, Piwigo Statistics.
Integration: Connect Piwigo with other services or platforms.
- Examples: LDAP Login (for corporate environments), external authenticators.

Finding Plugins:

The primary source is the official Piwigo Extensions directory (accessible via a link on the Piwigo website or directly).
You can also browse and install plugins directly from within the Piwigo administration interface (Administration -> Plugins -> Manage -> Add a plugin).

Important Considerations:

Compatibility: Always check if a plugin is compatible with your specific Piwigo version. Installing incompatible plugins can break your site. The Piwigo admin interface usually indicates compatibility.
Maintenance: Prefer plugins that are actively maintained and have been updated relatively recently. Abandoned plugins can become security risks or stop working after Piwigo updates.
Conflicts: Sometimes, two plugins might try to modify the same part of Piwigo, leading to conflicts. If you encounter issues after activating a new plugin, try deactivating it to see if the problem resolves.
Performance: Some plugins, especially those performing complex operations on many photos, can impact server performance. Monitor resource usage after installing resource-intensive plugins.
Security: Be cautious when installing third-party plugins, especially those not from the official repository. Ensure they come from trusted sources.

The plugin ecosystem is vast and constantly evolving. Exploring the available plugins is key to unlocking Piwigo's full potential.

Installing and Managing Plugins

Piwigo makes installing and managing plugins relatively straightforward through its administration interface.

Location: Navigate to Administration -> Plugins -> Manage.

The Plugin Management Screen:

Installed Plugins Tab: This lists all plugins currently present in your plugins directory. For each plugin, you typically see:
- Name and Thumbnail/Icon
- Version number
- Author(s)
- Description
- Action Buttons:
  - Activate/Deactivate: Turns the plugin on or off. Only active plugins affect your gallery.
  - Configure (or a gear icon): If the plugin has configurable settings, this link takes you to its configuration page.
  - Uninstall: Deactivates the plugin AND removes its database tables and configuration data. Use with caution, as this data is usually unrecoverable unless you have a backup.
  - Delete: Removes the plugin's files from the plugins directory. You must deactivate (and optionally uninstall) a plugin before deleting its files.
Add a Plugin Tab: This allows you to browse and install plugins directly from the official Piwigo Extensions repository.
- You can search by keyword or browse categories.
- Each available plugin will show its name, description, author, last update date, and compatibility information.
- Click the Install button to download and install the plugin files into your plugins directory. After installation, the plugin will appear in the "Installed Plugins" tab, usually deactivated by default.
Check for Updates Tab: Piwigo can check if newer versions are available for your installed plugins. It's crucial to keep plugins updated for security and compatibility. Click the "Check for updates" button, and Piwigo will list any plugins with available updates, providing an "Update" button for each.

Installation Workflow:

Find Plugin: Go to Add a plugin, search/browse for the desired plugin (e.g., "VideoJS").
Check Compatibility: Ensure it's compatible with your Piwigo version.
Install: Click Install. Wait for the download and installation process to complete.
Go to Installed Plugins: Navigate back to the Installed Plugins tab.
Activate: Find the newly installed plugin and click Activate. The page will reload, and the plugin should now be active.
Configure (If Necessary): If the plugin has a Configure link or adds a new menu item under Administration -> Plugins, visit its configuration page and adjust settings as needed.

Manual Installation (Alternative, Less Common):

If you cannot use the web-based installer (e.g., due to server restrictions) or want to install a plugin not listed in the official repository:

Download the plugin archive (usually a .zip file).
Extract the archive. You should get a directory named after the plugin (e.g., videojs).
Upload this directory and its contents to the plugins directory on your server (within Docker, this maps to /opt/piwigo/piwigo-config/plugins on the host). Ensure file permissions are correct so the web server can read the files.
Go to Administration -> Plugins -> Manage. The manually uploaded plugin should appear in the list.
Activate and configure it as described above.

Potential Issues:

Permissions: If Piwigo cannot write to the plugins directory (or its subdirectories), installation or updates might fail. Ensure the user running the web server process (or the PUID/PGID user in Docker) has write permissions to /opt/piwigo/piwigo-config/plugins.
PHP Errors/White Screen: An incompatible or faulty plugin can sometimes cause PHP errors, potentially leading to a blank white screen (the "White Screen of Death"). If this happens immediately after activating a plugin:
- You might need to manually deactivate it by renaming the plugin's folder inside the plugins directory (e.g., rename badplugin to badplugin_disabled).
- Check PHP error logs and web server logs for specific error messages to diagnose the problem.
Update Failures: Ensure Piwigo can reach the Piwigo extensions server (piwigo.org) for checking and downloading updates. Firewall rules could potentially block this.

Regularly check for and apply plugin updates to keep your gallery secure and functional.

Customizing Appearance with Themes

Themes control the visual presentation of your Piwigo gallery – its layout, colors, fonts, and overall look and feel. Switching themes is an easy way to give your gallery a fresh appearance without affecting your photos, albums, or core data.

How Themes Work:

Themes consist of template files (often using Smarty templating engine), CSS stylesheets, JavaScript files, and images.
They define the HTML structure and styling for different parts of the gallery (homepage, album view, photo page, menus, etc.).
They reside in the themes directory of your Piwigo installation (within the piwigo-config volume in our Docker setup: /opt/piwigo/piwigo-config/themes).

Managing Themes:

Navigate to Administration -> Configuration -> Themes.
This screen lists all themes available in your themes directory.
Active Theme: One theme is marked as the "Active theme". This is the theme currently displayed to visitors (and yourself, unless you override it in your user profile).
Activating a Theme: Simply click the Activate button next to the theme you want to use. The gallery's appearance will change immediately.
Installing New Themes: Similar to plugins, you can install themes from the official Piwigo Extensions repository:
1. Click the Add a theme tab.
2. Browse or search for themes. Check compatibility.
3. Click Install.
4. Go back to the Installed Themes tab.
5. Activate the newly installed theme if desired.
Configuring Themes: Some themes offer configuration options (e.g., color schemes, layout variations, custom headers/footers). If a theme is configurable, you'll usually find a Configure link next to it on the Themes management page, or it might add its own entry under the Configuration menu.
Updating Themes: Similar to plugins, use the Check for updates tab to find and apply newer versions of your installed themes.
Deleting Themes: You can delete inactive themes using the Delete button. You cannot delete the currently active theme.

Popular Themes (Examples - check current availability/popularity):

Modus: Often the default theme, clean and functional.
Bootstrap Darkroom: A popular, responsive theme based on the Bootstrap framework, often with good customization options.
Elegant: Another clean, minimalist theme.
Smart Pocket: Designed with mobile devices in mind.

Choosing a Theme:

Responsiveness: Ensure the theme works well on different screen sizes (desktops, tablets, phones). Most modern themes are responsive.
Compatibility: Check compatibility with your Piwigo version and any essential plugins you use (some plugins might have display elements that need theme support).
Customizability: If you want to tweak colors or layout, look for themes with built-in configuration options.
Performance: Simple, lightweight themes generally perform better than complex ones with heavy JavaScript or large images.
Maintenance: Prefer actively maintained themes.

Child Themes (Advanced):

If you want to make significant modifications to a theme's appearance (e.g., custom CSS, template overrides) but still want to be able to update the original parent theme easily, you can create a "child theme".

A child theme inherits most of its files and styles from a parent theme.
You only add the specific files (e.g., template-extension.css, modified template files) that you want to change in the child theme's directory.
Activate the child theme. Piwigo will load the parent theme first and then apply your modifications from the child theme.
This way, when the parent theme is updated, your customizations in the child theme are preserved and applied on top of the updated parent.
Creating child themes requires a deeper understanding of Piwigo's theme structure and potentially HTML/CSS/Smarty.

Experimenting with different themes is risk-free, as activating a theme doesn't change your underlying data. Find one that matches your desired aesthetic and functional needs.

Workshop Extending Functionality

In this workshop, we'll enhance our Piwigo installation by installing and configuring a couple of useful plugins and changing the default theme.

Objective: Install and activate the VideoJS plugin for video support and the Admin Tools plugin for enhanced administration. Switch the gallery theme to Bootstrap Darkroom.

Prerequisites:

A running Piwigo instance with admin access.
Internet connectivity from the Piwigo server/container to download extensions.
(Optional) A sample video file (e.g., a short MP4) to test video playback later.

Steps:

Install VideoJS Plugin:
- Log in as admin.
- Navigate to Administration -> Plugins -> Manage.
- Click the Add a plugin tab.
- In the search box, type VideoJS and press Enter or click Search.
- Locate the "VideoJS" plugin in the search results. Verify its compatibility with your Piwigo version.
- Click the Install button next to VideoJS. Wait for it to download and install.
- Go back to the Installed Plugins tab.
- Find VideoJS in the list and click Activate.
Configure VideoJS (Basic):
- After activating VideoJS, a Configure link or a new menu item under Administration -> Plugins -> VideoJS might appear. Click it.
- Explore the available options. Common settings include:
  - Supported file extensions (e.g., mp4, mov, webm, ogg). Ensure the extensions of the video files you intend to use are listed.
  - Player skin/appearance options.
  - Autoplay settings (usually best left off).
  - Preload settings.
- For now, the default settings are likely sufficient. Save any changes if you made them.
- (Self-Study Task): Upload a sample video file (e.g., MP4) to one of your albums just like you uploaded photos. Check if Piwigo now displays a playable video thumbnail and if the video plays correctly on the photo/item page.
Install Admin Tools Plugin:
- Go back to Administration -> Plugins -> Manage -> Add a plugin.
- Search for Admin Tools.
- Locate the "Admin Tools" plugin, check compatibility, and click Install.
- Go to the Installed Plugins tab and Activate the Admin Tools plugin.
Explore Admin Tools:
- A new menu item, Admin Tools, should appear under Administration -> Plugins (or sometimes directly under Administration -> Tools). Click on it.
- Briefly explore the sub-sections. Admin Tools often provides functionalities like:
  - Orphan photos/albums: Find items not correctly linked.
  - Metadata Synchronization: Force update metadata from files.
  - Thumbnail Management: Check for missing thumbnails, regenerate them (can be resource-intensive).
  - Database Maintenance: Optimize tables, check integrity.
- This plugin is very powerful for maintenance and troubleshooting, especially in larger galleries. We won't perform any major actions now, but be aware of its capabilities.
Install Bootstrap Darkroom Theme:
- Navigate to Administration -> Configuration -> Themes.
- Click the Add a theme tab.
- Search for Bootstrap Darkroom.
- Locate the theme, check compatibility, and click Install.
- Go back to the Installed Themes tab (or the main Themes tab).
Activate Bootstrap Darkroom Theme:
- Find "Bootstrap Darkroom" in the list of installed themes.
- Click the Activate button next to it.
- The page will reload, confirming Bootstrap Darkroom is now the active theme.
View the New Theme:
- Navigate to your main gallery page (click the "Visit the gallery" link).
- Observe the new look and feel provided by the Bootstrap Darkroom theme. Notice the different layout, colors, and possibly different menu structures.
- Explore album and photo pages to see how the theme presents them.
Configure Bootstrap Darkroom (Optional):
- Go back to Administration -> Configuration -> Themes.
- Find Bootstrap Darkroom and see if it has a Configure link. Click it if available.
- Explore the theme's specific options. Bootstrap Darkroom often allows choosing color schemes, enabling/disabling features like social sharing buttons, adjusting thumbnail types, customizing the banner, etc.
- Make a small change (e.g., switch to a different color scheme if available) and save it to see the effect.

You have now successfully extended your Piwigo gallery by adding video support and powerful admin tools via plugins, and completely changed its appearance by switching to the Bootstrap Darkroom theme. This demonstrates the flexibility offered by Piwigo's extension system.

4. Advanced Administration and Optimization

Once your Piwigo gallery is set up and populated, focusing on performance, reliability, and security becomes crucial, especially as your collection grows or user traffic increases. This section delves into advanced topics for maintaining a robust and efficient Piwigo instance.

Performance Tuning

A slow gallery frustrates users and consumes unnecessary server resources. Performance tuning involves optimizing various components of your Piwigo stack.

Image Optimization:

Thumbnail Generation Strategy:
- Piwigo generates multiple image sizes (thumbnail, medium, large, etc.) for display. Generating these on-the-fly when first requested can cause initial delays.
- Consider pre-generating thumbnails, especially after large uploads. The Admin Tools plugin often has features for finding missing thumbnails and batch-generating them. This shifts the processing load to a time of your choosing rather than during user browsing.
- Administration -> Configuration -> Options -> Photo sizes: Review the sizes Piwigo generates. Do you need all of them? Removing unused sizes saves disk space and generation time. Ensure the chosen sizes match what your theme actually uses.
Image Quality vs. Size:
- Administration -> Configuration -> Options -> Upload: The "Resize photos upon upload" quality setting significantly impacts file size. A lower quality (e.g., 80-85) results in smaller files and faster loading but may introduce visible compression artifacts. Find a balance that works for your visual standards.
- Consider using tools like jpegoptim or optipng (installable on the host or potentially within a custom Docker image) to further optimize images after Piwigo generates them. This requires scripting or manual intervention.
Use ImageMagick: If available (install imagemagick on the host/in container and the imagick PHP extension), Piwigo can often use it instead of the GD library for image processing. ImageMagick is generally faster and more efficient, especially for resizing and handling various formats. Check Piwigo's configuration (Administration -> Configuration -> General or similar, might depend on version/plugins) to see which graphic library is active and if ImageMagick can be enabled.

Database Optimization:

Database Server Tuning:
- Memory Allocation: Ensure your database server (MariaDB/MySQL) has sufficient RAM allocated. Key parameters in my.cnf (or passed as command arguments in Docker) include innodb_buffer_pool_size. A common rule of thumb is to set this to 50-70% of available system RAM if the database is the primary workload, but be cautious on systems running other services. More buffer pool means more data and indexes are cached in memory, reducing disk I/O.
- Query Cache: (Note: Query cache is often deprecated/removed in newer MySQL/MariaDB versions, as it has limitations). If using an older version where it's relevant, query_cache_size and query_cache_type can cache the results of identical SELECT queries. It can be beneficial for read-heavy workloads but has overhead for writes. Modern InnoDB buffer pool improvements often make it less critical.
Piwigo Database Maintenance:
- Use the Admin Tools plugin or phpMyAdmin (if installed) to periodically run OPTIMIZE TABLE on your Piwigo tables. This reorganizes table data and indexes, potentially reclaiming unused space and improving query performance, especially after many deletions or updates.
- Ensure database tables are using the utf8mb4 character set for full Unicode support, as recommended by Piwigo.

Web Server and PHP Configuration:

Web Server Caching:
- Browser Caching: Configure Nginx or Apache to send appropriate Cache-Control and Expires headers for static assets (CSS, JS, images). This tells browsers to cache these files locally, reducing server load and speeding up subsequent page views.
- Server-Side Caching/Compression: Enable gzip or Brotli compression in your web server configuration to reduce the size of text-based files (HTML, CSS, JS) sent over the network.
PHP Settings:
- memory_limit: As mentioned before, ensure this is high enough in php.ini (or via Docker environment variables/custom php.ini) to handle image processing without errors (e.g., 256M or 512M).
- max_execution_time: May need increasing if thumbnail generation for very large files times out.
- OPcache: Ensure PHP's OPcache extension is enabled and properly configured. OPcache compiles PHP scripts into bytecode and stores it in memory, significantly speeding up execution by avoiding recompilation on every request. Check opcache.enable=1, opcache.memory_consumption (e.g., 128M), opcache.interned_strings_buffer (e.g., 16M), and opcache.revalidate_freq (e.g., 60 seconds for development, potentially higher for production).
PHP-FPM Tuning (if using Nginx/PHP-FPM):
- Adjust the number of PHP-FPM worker processes (pm.max_children, pm.start_servers, pm.min_spare_servers, pm.max_spare_servers) based on your server's RAM and CPU capacity and expected traffic. Too few workers will queue requests; too many will exhaust RAM. Monitor resource usage to find optimal values.

Network and Infrastructure:

Content Delivery Network (CDN): For high-traffic public galleries, consider using a CDN (like Cloudflare, AWS CloudFront) to cache static assets (images, CSS, JS) closer to your visitors, reducing latency and server load.
Server Location: Host your server geographically close to your primary audience if possible.
Hardware: As discussed in System Requirements, sufficient RAM and fast storage (SSD) are fundamental for good performance.

Performance tuning is an ongoing process. Use browser developer tools (Network tab) to identify slow-loading resources, monitor server load (using tools like htop, docker stats), and analyze database query performance (using slow query logs) to pinpoint bottlenecks.

Backup and Recovery Strategies

Data loss is a significant risk with any self-hosted service. Implementing a robust backup strategy for your Piwigo instance is non-negotiable. A complete backup requires saving both the database and the photo files/configuration.

What to Back Up:

Database: Contains all metadata, users, albums, tags, comments, configuration settings stored by Piwigo. Losing this means losing your entire gallery structure and metadata.
Piwigo Files/Configuration:
- galleries directory: This directory (mapped to ./gallery in our Docker Compose setup) contains the actual photo files organized by Piwigo, including different sizes (thumbnails, medium, etc.). This is usually the largest part of the backup.
- _data directory (or equivalent config volume): Contains local configuration files (config.inc.php), installed plugins, themes, cache, etc. In our Docker setup, this corresponds to the ./piwigo-config volume. Backing this up ensures you can restore plugins, themes, and specific local settings.
- (Optional but recommended): The docker-compose.yml file itself, so you can easily recreate the service structure.

Backup Methods:

Manual Backup:

Database: Use a database administration tool like phpMyAdmin (if installed) to export the Piwigo database to an SQL file (.sql). Alternatively, use the command-line mysqldump utility:

# If DB is running on the host
mysqldump -u piwigo_user -p'YOUR_PIWIGO_DB_PASSWORD' piwigo_gallery > piwigo_backup_$(date +%Y%m%d).sql

# If DB is running in Docker (execute command inside the DB container)
sudo docker exec piwigo_db sh -c 'exec mysqldump --all-databases -uroot -p"$MYSQL_ROOT_PASSWORD"' > piwigo_db_backup_$(date +%Y%m%d).sql
# OR dump specific DB as piwigo user:
sudo docker exec piwigo_db sh -c 'exec mysqldump -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' > piwigo_db_backup_$(date +%Y%m%d).sql
# Replace placeholders with actual credentials from docker-compose.yml

Remember to handle the password securely, potentially using a .my.cnf file or prompting.

Files: Use rsync, tar, or simply copy the relevant directories (/opt/piwigo/gallery, /opt/piwigo/piwigo-config, potentially /opt/piwigo/database if using bind mount for DB data, though dumping the SQL is generally safer for DB consistency) to a separate backup location (e.g., external hard drive, network share, cloud storage).
```
# Example using tar
sudo tar czvf piwigo_files_backup_$(date +%Y%m%d).tar.gz /opt/piwigo/gallery /opt/piwigo/piwigo-config
```
Pros: Simple for one-off backups.
Cons: Prone to human error, easy to forget, not suitable for regular protection.

Automated Backup Script (using Cron):

Concept: Create a shell script that performs the database dump and file archiving, then schedule it to run automatically using cron.

Example Script (backup_piwigo.sh):

#!/bin/bash

# --- Configuration ---
BACKUP_DIR="/mnt/backups/piwigo" # Destination for backups (MUST exist and be writable)
PIWIGO_APP_DIR="/opt/piwigo" # Directory containing docker-compose.yml and volumes
DB_CONTAINER="piwigo_db"
DB_USER="piwigo_user" # From docker-compose.yml
DB_PASS="CHANGEME_PIWIGO_DB_PASSWORD" # From docker-compose.yml
DB_NAME="piwigo_gallery" # From docker-compose.yml
KEEP_DAYS=7 # How many days of backups to keep

# --- Timestamp ---
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
TODAY=$(date +%Y%m%d)

# --- Ensure backup directory exists ---
mkdir -p "$BACKUP_DIR"

# --- Backup Database ---
echo "Backing up Piwigo database..."
DB_FILENAME="${BACKUP_DIR}/piwigo_db_backup_${TIMESTAMP}.sql.gz"
sudo docker exec "$DB_CONTAINER" sh -c 'exec mysqldump -u"$MYSQL_USER" -p"$DB_PASS" "$DB_NAME"' | gzip > "$DB_FILENAME"

if [ $? -ne 0 ]; then
    echo "ERROR: Database backup failed!"
    exit 1
fi
echo "Database backup saved to ${DB_FILENAME}"

# --- Backup Files ---
echo "Backing up Piwigo files (gallery, config)..."
FILES_FILENAME="${BACKUP_DIR}/piwigo_files_backup_${TIMESTAMP}.tar.gz"
# Note: Ensure paths match your setup (gallery and piwigo-config bind mounts)
# Exclude cache directories if desired to save space/time
sudo tar czvf "$FILES_FILENAME" \
    --exclude="${PIWIGO_APP_DIR}/piwigo-config/template_c" \
    --exclude="${PIWIGO_APP_DIR}/piwigo-config/_data/cache" \
    -C "$PIWIGO_APP_DIR" gallery piwigo-config # Use -C to change directory, avoiding leading paths in archive

if [ $? -ne 0 ]; then
    echo "ERROR: File backup failed!"
    # Optional: remove failed DB backup?
    # rm "$DB_FILENAME"
    exit 1
fi
echo "File backup saved to ${FILES_FILENAME}"

# --- Prune Old Backups ---
echo "Pruning backups older than ${KEEP_DAYS} days..."
find "$BACKUP_DIR" -name "piwigo_db_backup_*.sql.gz" -mtime +$KEEP_DAYS -exec echo "Deleting old DB backup: {}" \; -exec rm {} \;
find "$BACKUP_DIR" -name "piwigo_files_backup_*.tar.gz" -mtime +$KEEP_DAYS -exec echo "Deleting old file backup: {}" \; -exec rm {} \;

echo "Piwigo backup completed successfully."
exit 0

Save the script (e.g., /usr/local/bin/backup_piwigo.sh), make it executable (sudo chmod +x /usr/local/bin/backup_piwigo.sh). Crucially, replace password placeholders and adjust paths.
Schedule with Cron: Edit the crontab (sudo crontab -e) and add a line to run the script, e.g., daily at 2 AM:
```
0 2 * * * /usr/local/bin/backup_piwigo.sh > /var/log/piwigo_backup.log 2>&1
```
Pros: Automated, regular protection.
Cons: Requires scripting knowledge, need to manage backup storage and rotation. Password handling in script needs care (better: use Docker secrets or my.cnf in container).

Docker Volume Backups:
- Some backup tools are designed specifically for Docker volumes (e.g., restic, duplicati run in a container with access to Docker socket and volumes). These can sometimes simplify the process, especially if using named volumes instead of bind mounts.
- Alternatively, the script method above works well with bind mounts.
Backup Storage:
- 3-2-1 Rule: Keep at least 3 copies of your data, on 2 different media types, with 1 copy off-site.
- Local: External HDD/SSD, separate internal drive, NAS.
- Off-site: Cloud storage (Backblaze B2, AWS S3, Google Cloud Storage, Hetzner Storage Box, etc.), another physical location. Use tools like rclone to sync your local backups to cloud storage. Encrypt backups stored off-site.

Recovery Process:

Setup Fresh Instance (if needed): If restoring to a new server, set up the basic OS, Docker, Docker Compose, and create the necessary directory structure (/opt/piwigo etc.).
Stop Piwigo Containers: sudo docker-compose down in /opt/piwigo.
Restore Files:
- Delete the current contents of /opt/piwigo/gallery and /opt/piwigo/piwigo-config.
- Extract your file backup (piwigo_files_backup_...tar.gz) into /opt/piwigo, ensuring the gallery and piwigo-config directories are recreated with the correct contents and ownership/permissions.
- sudo tar xzvf /path/to/backup/piwigo_files_backup_....tar.gz -C /opt/piwigo
- Verify permissions/ownership (sudo chown -R 1000:1000 /opt/piwigo/gallery /opt/piwigo/piwigo-config, using your correct PUID/PGID).

Restore Database:

Start only the database container: sudo docker-compose up -d piwigo-db.

Import the SQL backup into the running container:

# Decompress first if it's gzipped
gunzip < /path/to/backup/piwigo_db_backup_....sql.gz | sudo docker exec -i piwigo_db sh -c 'exec mysql -u"$MYSQL_USER" -p"$DB_PASS" "$DB_NAME"'
# OR using root:
# gunzip < /path/to/backup/piwigo_db_backup_....sql.gz | sudo docker exec -i piwigo_db sh -c 'exec mysql -uroot -p"$MYSQL_ROOT_PASSWORD"'

Replace placeholders. Ensure the database defined in MYSQL_DATABASE exists before importing if using the non-root command.

Verify the import completed without errors.

Restart Piwigo: sudo docker-compose up -d piwigo-app.
Test: Access your Piwigo instance and verify that albums, photos, users, tags, and configurations are restored correctly. You might need to clear browser cache or Piwigo template cache (Administration -> Tools -> Maintenance -> Purge compiled templates).

Regularly test your recovery process! A backup is useless if you can't restore it.

Security Hardening

Securing your self-hosted Piwigo instance is critical to protect your photos and prevent unauthorized access or compromises. Implement security measures at multiple levels.

HTTPS Encryption:
- Absolutely Essential: Encrypts traffic between users' browsers and your server, protecting login credentials and preventing eavesdropping.
- Method: Use a reverse proxy like Nginx Proxy Manager, Traefik, or Caddy in front of your Piwigo container. These tools can automatically obtain and renew free SSL certificates from Let's Encrypt and handle HTTPS termination.
- Configuration: The reverse proxy listens on ports 80 and 443, redirects HTTP to HTTPS, and forwards traffic to Piwigo's internal port (e.g., 8080 in our Docker setup). Piwigo itself runs on plain HTTP inside the Docker network, but all external communication is encrypted.
- Avoid exposing Piwigo directly to the internet on port 80/443 unless you have a specific reason and configure HTTPS within the container itself (more complex).
Strong Credentials:
- Use strong, unique passwords for the Piwigo admin account, all user accounts, and the database user.
- Consider using a password manager.
User Management:
- Limit the number of Admin users.
- Disable public user registration (Administration -> Configuration -> Options -> General) unless specifically needed for your use case. Create users manually.
- Regularly review user accounts and remove inactive ones.
Keep Everything Updated:
- Piwigo Core: Regularly check for and apply Piwigo updates (Administration -> Tools -> Updates). Updates often contain security patches.
- Plugins and Themes: Keep all extensions updated (Administration -> Plugins/Themes -> Check for updates). Outdated extensions are a common vulnerability vector.
- Server Software: Keep the host OS, Docker, web server (if manual install), PHP, and database server updated with security patches.
File Permissions:
- Ensure file permissions are set correctly. The web server process needs read access to most files and write access only to specific directories (_data/config, galleries/upload, cache directories). Using the correct PUID/PGID in Docker helps manage this. Avoid overly permissive settings like 777.
Web Server Security:
- Reverse Proxy: Configure security headers in your reverse proxy (Nginx, Apache, Traefik, Caddy): Strict-Transport-Security, Content-Security-Policy, X-Frame-Options, X-Content-Type-Options. Tools like Nginx Proxy Manager often have easy toggles for these.
- Limit Access (Optional): If your gallery is private, consider restricting access at the firewall or reverse proxy level to specific IP addresses or ranges.
PHP Security:
- Disable dangerous PHP functions in php.ini if not needed by Piwigo or its plugins (e.g., exec, shell_exec, passthru, system). This requires careful testing. Check Piwigo documentation or forums for recommended disable_functions lists. (This is harder to manage in standard Docker images unless you build your own or mount a custom php.ini).
Database Security:
- Ensure the database is not directly accessible from the internet. In the Docker setup, it's only accessible within the piwigo-net Docker network.
- Use a strong root password for the database server.
- The Piwigo database user (piwigo_user) should only have permissions on the Piwigo database (piwigo_gallery), not global privileges. The docker-compose.yml setup generally handles this correctly.
Security Plugins:
- Consider plugins that add security features like Two-Factor Authentication (2FA) or activity logging/auditing.
Regular Audits:
- Periodically review your configuration, user lists, and permissions. Check server logs for suspicious activity.
Web Application Firewall (WAF):
- Consider using a WAF (like ModSecurity for Apache/Nginx, or services like Cloudflare's WAF) to filter malicious requests before they reach Piwigo.

Security is not a one-time setup but an ongoing process of vigilance, updates, and configuration reviews.

Workshop Implementing Backup and HTTPS

This workshop focuses on setting up essential security and reliability features: automated backups and enabling HTTPS access via a reverse proxy.

Part 1: Automated Backup Script

Objective: Implement and schedule the automated backup script created earlier.

Prerequisites:

A running Piwigo instance (Docker setup from Workshop 1).
Root/sudo access to the host machine.
A designated backup location (e.g., /mnt/backups/piwigo) writable by the user who will run the cron job (likely root).

Steps:

Create Backup Directory:

sudo mkdir -p /mnt/backups/piwigo
# Adjust permissions if necessary, but root running cron should have access

Save the Backup Script:
- Copy the example backup_piwigo.sh script provided in the "Backup and Recovery Strategies" section.
- Save it to /usr/local/bin/backup_piwigo.sh.
- bash sudo nano /usr/local/bin/backup_piwigo.sh # (Paste the script content here)
Customize the Script:
- Crucially, edit the script (sudo nano /usr/local/bin/backup_piwigo.sh) and replace CHANGEME_PIWIGO_DB_PASSWORD with the actual Piwigo database user password from your docker-compose.yml.
- Verify BACKUP_DIR, PIWIGO_APP_DIR, DB_CONTAINER, DB_USER, and DB_NAME match your setup precisely.
- Adjust KEEP_DAYS as desired.
- Save and close the file.

Make Script Executable:

sudo chmod +x /usr/local/bin/backup_piwigo.sh

Perform a Manual Test Run:
```
sudo /usr/local/bin/backup_piwigo.sh
```
- Check the output for any errors.
- Verify that a .sql.gz database backup and a .tar.gz file backup appear in /mnt/backups/piwigo. Check their sizes – they shouldn't be zero bytes.
Schedule with Cron:
- Edit root's crontab: sudo crontab -e (select an editor if prompted).
- Add the following line to schedule the backup (e.g., daily at 2:05 AM):
```
5 2 * * * /usr/local/bin/backup_piwigo.sh >> /var/log/piwigo_backup.log 2>&1
```
  (Using >> appends to the log file)
- Save and close the crontab.
Verify Cron Setup:
- Wait until after the scheduled time (e.g., the next day after 2:05 AM).
- Check the log file: sudo tail /var/log/piwigo_backup.log. It should show the output from the script execution.
- Check the backup directory (/mnt/backups/piwigo) for new backup files.

Part 2: Setting up HTTPS with Nginx Proxy Manager

Objective: Secure Piwigo access using HTTPS via Nginx Proxy Manager (NPM). NPM itself will run as a Docker container.

Prerequisites:

A running Piwigo instance (Docker setup from Workshop 1, accessible via http://YOUR_SERVER_IP:8080).
A domain name (e.g., piwigo.yourdomain.com) pointing to your server's public IP address (DNS A record).
Ports 80 and 443 open on your server's firewall and forwarded from your router if behind NAT. Docker/NPM needs these ports.
Docker and Docker Compose installed.

Steps:

Stop Piwigo Temporarily (Optional but Safer):

cd /opt/piwigo
sudo docker-compose down

Create Nginx Proxy Manager Docker Compose File:
- Create a separate directory for NPM, e.g., /opt/npm.
- bash sudo mkdir -p /opt/npm/data /opt/npm/letsencrypt cd /opt/npm
- Create a docker-compose.yml for NPM:
```
sudo nano docker-compose.yml
```
- Paste the following:
```
version: '3.7'
services:
  npm-app:
    image: 'jc21/nginx-proxy-manager:latest'
    container_name: npm_app
    restart: unless-stopped
    ports:
      # Public HTTP Port:
      - '80:8080'
      # Public HTTPS Port:
      - '443:4443'
      # Admin Web Port:
      - '8181:81' # Map host 8181 to internal NPM admin UI port 81 (Change 8181 if needed)
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
    # Optional: Add to piwigo-net if Piwigo is not exposed on host IP
    # networks:
    #  - piwigo-net # Assumes piwigo-net is defined elsewhere or globally

# If Piwigo is ONLY on the Docker network 'piwigo-net', NPM also needs
# to be attached to it. Define it here if not defined globally.
# networks:
#   piwigo-net:
#     external: true # If created by Piwigo's compose file
```
  - Note: We map host ports 80/443 to NPM's internal proxy ports (8080/4443) and host port 8181 to NPM's admin UI port (81).
  - Networking: For NPM to proxy to piwigo_app:80 (Piwigo's internal Docker network address), NPM's container must be on the same Docker network (piwigo-net). Uncomment the networks sections in NPM's compose file and ensure piwigo-net is defined (either here or in Piwigo's compose file, potentially marked as external: true if defined elsewhere). Alternatively, if Piwigo's port 8080 is mapped to the host IP, NPM can proxy to HOST_IP:8080. For better security and simplicity within Docker, connecting both containers to the same network (piwigo-net) and proxying to the container name (piwigo_app) is generally preferred. Let's assume we add NPM to piwigo-net.
Adjust Piwigo's docker-compose.yml:
- Go back to /opt/piwigo: cd /opt/piwigo
- Edit Piwigo's docker-compose.yml: sudo nano docker-compose.yml
- Remove/Comment out Port Mapping: Since NPM will handle external access, we no longer need to expose Piwigo's port directly. Comment out or remove the ports: section under piwigo-app:
```
# ports:
#  - "8080:80"
```
- Ensure Network Definition: Make sure the piwigo-net network is defined at the bottom of the file so NPM can connect to it:
```
networks:
  piwigo-net:
    driver: bridge
```
- Save the file.

Adjust NPM's docker-compose.yml for Network:

Go back to /opt/npm: cd /opt/npm
Edit NPM's docker-compose.yml: sudo nano docker-compose.yml

Add the networks sections to connect NPM to Piwigo's network:

version: '3.7'
services:
  npm-app:
    # ... (image, container_name, restart, ports, volumes sections as before) ...
    networks: # Add this network section under npm-app service
      - piwigo-net # Connect this service to piwigo-net

networks: # Define the external network at the bottom
  piwigo-net:
    external: true # Assume piwigo-net is created by the other compose file

Save the file.

Start Services:
- Start Piwigo (it won't be accessible externally yet):
```
cd /opt/piwigo
sudo docker-compose up -d
```
- Start Nginx Proxy Manager:
```
cd /opt/npm
sudo docker-compose up -d
```
Configure Nginx Proxy Manager:
- Access the NPM admin UI in your browser: http://YOUR_SERVER_IP:8181 (use the host port you mapped).
- Default login:
  - Email: admin@example.com
  - Password: changeme
- You'll be forced to change the email and password immediately. Use a strong password!
- Navigate to Hosts -> Proxy Hosts.
- Click Add Proxy Host.
- Details Tab:
  - Domain Names: Enter your domain (e.g., piwigo.yourdomain.com).
  - Scheme: http (NPM talks to Piwigo container over plain HTTP).
  - Forward Hostname / IP: piwigo_app (the service name of the Piwigo container in its docker-compose.yml).
  - Forward Port: 80 (the internal port Piwigo listens on inside the container).
  - Cache Assets: Toggle ON (optional, improves performance).
  - Block Common Exploits: Toggle ON (recommended).
  - Websockets Support: Toggle ON (might be needed by some Piwigo plugins/features).
- SSL Tab:
  - SSL Certificate: Select "Request a new SSL Certificate".
  - Force SSL: Toggle ON (redirects HTTP to HTTPS).
  - HTTP/2 Support: Toggle ON (improves performance).
  - Email Address for Let's Encrypt: Enter your valid email address.
  - Agree to the Let's Encrypt Terms.
- Click Save.
Wait and Test:
- NPM will attempt to obtain the Let's Encrypt certificate. This requires your domain's DNS to be correctly pointed and ports 80/443 to be open and reachable from the internet. You can check the status in NPM (SSL Certificates section).
- Once the certificate is obtained (status should show as valid/online), try accessing your Piwigo instance via HTTPS: https://piwigo.yourdomain.com.
- You should be redirected to HTTPS, see a valid lock icon in your browser, and access your Piwigo gallery securely.
- Also test if http://piwigo.yourdomain.com automatically redirects to HTTPS.

You now have an automated backup system running nightly and secure HTTPS access to your Piwigo gallery, significantly improving its reliability and security. Remember to also back up your NPM configuration (/opt/npm/data, /opt/npm/letsencrypt).

5. Integration and Automation

Beyond basic usage, Piwigo can be integrated into larger workflows and automated to streamline tasks like photo uploads. This section explores using the Piwigo API and setting up automated upload processes.

Using the Piwigo API

Piwigo offers a comprehensive web Application Programming Interface (API) that allows external applications and scripts to interact with your gallery programmatically. This opens up possibilities for automation, integration with other services, and building custom tools.

What is the API?

It's a set of web services based on REST principles (though not strictly RESTful in all aspects) or XML-RPC.
You send HTTP requests (usually GET or POST) to a specific API endpoint (webservice/rest/server.php or ws.php) with parameters defining the method to call and any required data.
Piwigo processes the request and returns data, typically in formats like JSON, XML, or PHP serialized arrays.

Key Concepts:

Endpoint: The URL where API requests are sent (e.g., http://piwigo.yourdomain.com/ws.php).
Methods: Specific actions you want to perform (e.g., pwg.session.login, pwg.categories.getList, pwg.images.addSimple). A full list is available in the Piwigo documentation or often explorable via the API itself (pwg.reflection.getMethodList).
Parameters: Data sent with the request, including the method name, authentication details (if required), and method-specific arguments (e.g., album ID, image data).
Formats: You can usually specify the desired response format using a parameter (e.g., format=json). JSON is commonly preferred for modern web development.
Authentication: Most methods that modify data or access private content require authentication. This is typically done by:
1. Calling pwg.session.login with username and password to get a session cookie. Subsequent requests must include this cookie.
2. Alternatively, some methods might support token-based authentication (less common in core, might be plugin-dependent). API keys might also be used for specific integrations.

Use Cases:

Automated Uploads: Scripts can use pwg.images.addSimple or pwg.images.add to upload photos directly without using the web UI.
Metadata Updates: Scripts can fetch image lists (pwg.categories.getImages) and update metadata (pwg.images.setInfo).
User/Group Management: Automate user creation or group assignments (pwg.users.add, pwg.groups.addUser).
Custom Frontends/Apps: Build mobile apps or alternative web interfaces that use Piwigo as the backend photo storage and management system.
Integration with Other Tools: Sync data between Piwigo and other systems (e.g., digital asset management, blogging platforms).

Exploring the API:

Documentation: The official Piwigo website has documentation detailing the available API methods, parameters, and examples.
API Test Tools: Use tools like curl (command-line), Postman, or Insomnia to manually send requests to the API endpoint and inspect the responses. This is invaluable for learning and debugging.

Example using curl (Listing Albums):

This example assumes your gallery allows guest access to see some albums and uses the REST endpoint with JSON format.

# Replace with your Piwigo URL
PIWIGO_URL="https://piwigo.yourdomain.com"

# Call the pwg.categories.getList method
# - method: Specifies the API method
# - format: Requests JSON output
# - recursive: Get all albums recursively
# - public: Only show public albums (useful for unauthenticated requests)
curl "${PIWIGO_URL}/ws.php?method=pwg.categories.getList&format=json&recursive=true&public=true"

# Expected Output (simplified JSON):
# {
#   "stat": "ok",
#   "result": {
#     "categories": [
#       { "id": 1, "name": "Landscapes", "comment": "...", "nb_images": 50, ... },
#       { "id": 2, "name": "Portraits", "comment": "...", "nb_images": 30, ... },
#       { "id": 5, "name": "Sub Album", "id_uppercat": 1, ... }
#       // ... more albums
#     ]
#   }
# }

Example using curl (Login and List Private Albums):

This requires username/password and uses session cookies.

# Replace with your Piwigo URL, username, and password
PIWIGO_URL="https://piwigo.yourdomain.com"
USERNAME="testuser"
PASSWORD="someSecurePassword123"
COOKIE_JAR="/tmp/piwigo_cookie.txt"

# 1. Login and save the session cookie
echo "Logging in..."
curl -X POST -c "$COOKIE_JAR" \
     -d "method=pwg.session.login" \
     -d "username=${USERNAME}" \
     -d "password=${PASSWORD}" \
     -d "format=json" \
     "${PIWIGO_URL}/ws.php"

# Check login response (optional)
cat "$COOKIE_JAR"
echo # Newline

# 2. Use the cookie to call a method requiring authentication
echo "Listing categories (including private)..."
curl -b "$COOKIE_JAR" \
     "${PIWIGO_URL}/ws.php?method=pwg.categories.getList&format=json&recursive=true"

# Cleanup cookie file
# rm "$COOKIE_JAR"

The API is a powerful tool for advanced users and developers. While exploring its full potential is beyond a basic guide, understanding its existence and basic principles is crucial for automation and integration tasks. Refer to the official Piwigo documentation for detailed method references.

Automating Uploads

Manually uploading photos via the web interface can become tedious, especially for large batches or frequent additions. Piwigo and its ecosystem offer several ways to automate or streamline this process.

Methods for Automated/Streamlined Uploads:

Synchronization Feature (Built-in or via Admin Tools):
- Concept: You upload photo files directly to a specific directory on the server (often named upload or galleries/import within the Piwigo structure), and then trigger a synchronization process within the Piwigo admin interface. Piwigo scans the directory, finds new photos, reads their metadata, generates thumbnails, and adds them to the database, associating them with a designated album or creating albums based on the directory structure.
- How it Works:
  - Use tools like scp, rsync, FTP/SFTP clients, or file synchronization software (like Syncthing, Nextcloud sync client) to transfer your photos from your computer/phone to a designated "import" directory on the Piwigo server. This directory needs to be accessible within the Piwigo environment (e.g., a sub-directory within the /opt/piwigo/gallery volume).
  - Navigate to Administration -> Tools -> Synchronize (or similar path, might be under Admin Tools plugin).
  - Configure options like whether to create albums based on directory structure, which album to associate photos with if no structure exists, whether to simulate first, and whether to read metadata.
  - Run the synchronization. Piwigo processes the files in the import directory.
- Pros: Relatively simple to set up file transfer. Leverages Piwigo's robust processing (metadata, thumbnails). Good control over the import process via the admin UI. Can often be triggered via cron using a script that calls a specific Piwigo CLI/API endpoint if available.
- Cons: Requires a two-step process (transfer files, then trigger sync). Might not be fully "real-time". Requires server access to upload files to the import directory.
FTP/SFTP Upload + Sync:
- Concept: Similar to the above, but uses FTP or SFTP as the transfer method. Set up an FTP/SFTP server on the host (or potentially via a dedicated container) whose root directory points to the Piwigo import/upload directory.
- How it Works: Use an FTP/SFTP client (FileZilla, WinSCP) or tools/apps that support FTP/SFTP uploads to transfer photos. Then, trigger the Piwigo synchronization process manually or via a scheduled task.
- Pros: Uses standard, widely supported protocols. Many applications can upload via FTP/SFTP.
- Cons: Requires setting up and securing an FTP/SFTP server. Still needs the separate synchronization step in Piwigo. FTP is insecure (use SFTP).
Dedicated Uploader Applications (Desktop/Mobile):
- Concept: Use applications specifically designed to upload photos to Piwigo, often leveraging the Piwigo API.
- Examples: Check the Piwigo website/forums for current recommended desktop uploaders (may vary over time) or mobile apps (e.g., "Piwigo NG" for Android, potentially others for iOS).
- How it Works: Install the app, configure it with your Piwigo URL and login credentials. The app provides an interface to select photos/folders and upload them directly. It handles communication with the API (pwg.images.add, etc.).
- Pros: Often more user-friendly than manual file transfer + sync. Integrates directly with Piwigo's API for potentially faster processing/feedback. May offer features like background uploads, album selection during upload.
- Cons: Dependent on the availability and quality of third-party applications. May require API access to be correctly configured/working.
Folder Synchronization Tools (e.g., Syncthing):
- Concept: Use a peer-to-peer file synchronization tool like Syncthing to directly sync a folder on your local machine with the Piwigo import directory on the server.
- How it Works:
  - Install Syncthing on your local computer and on the Piwigo server (can run as a Docker container).
  - Configure Syncthing to sync a local "Piwigo Upload" folder with the /opt/piwigo/gallery/upload (or equivalent import directory) on the server.
  - As you add photos to the local folder, Syncthing automatically transfers them to the server's import directory.
  - Combine this with a scheduled Piwigo synchronization task (using cron and potentially a script invoking the sync via command line or API) to process the newly arrived photos periodically.
- Pros: Fully automated file transfer. Syncthing is efficient and secure (peer-to-peer, encrypted). Works well for continuous, unattended uploads.
- Cons: Requires setting up and managing Syncthing. Still needs the scheduled Piwigo sync process to integrate the photos into the gallery database.
Custom Scripts using the API:
- Concept: Write your own scripts (e.g., in Python, Bash with curl) that watch a local directory and use the Piwigo API (pwg.images.addSimple or pwg.images.add) to upload new photos directly.
- Pros: Maximum flexibility and control over the upload process (e.g., custom metadata handling, conditional uploads). Fully automated, single-step process (script handles transfer and API call).
- Cons: Requires programming skills. Need to handle authentication, error checking, potentially large file uploads reliably.

Choosing the Right Method:

Simple Batch Uploads: Manual transfer (SCP/SFTP) + Manual Sync in Admin UI is often sufficient.
Regular Automated Uploads: Syncthing + Scheduled Piwigo Sync offers a robust, automated solution.
User-Friendly Uploads from Desktop/Mobile: Dedicated Uploader Apps are often the most convenient if good ones are available for your platform.
Advanced Integration/Workflows: Custom API scripts provide the most power.

For most self-hosters looking for automation, the combination of a file synchronization tool like Syncthing pointing to an import directory, coupled with a scheduled cron job that triggers Piwigo's internal synchronization process, strikes a good balance between automation, reliability, and ease of management.

Integrating with Other Services (Optional)

While Piwigo is primarily a standalone gallery, its API and web nature allow for some level of integration with other services, although deep integrations often require custom development.

Embedding Galleries: Many themes or plugins might offer ways to generate HTML/JavaScript snippets to embed specific albums or photo streams into other websites (e.g., a personal blog, a company website). This usually involves an <iframe> or a JavaScript-based widget. Check theme/plugin documentation for embedding capabilities.
Using Piwigo as an Image Backend: For developers, Piwigo could potentially serve as a backend image management system for other applications. The other application would use the Piwigo API to upload images, manage albums (perhaps corresponding to posts or products), and retrieve image URLs or metadata for display. This requires significant custom development on the integrating application's side.
Authentication Integration (LDAP/SSO): For corporate or educational environments, plugins like LDAP Login allow users to log into Piwigo using their existing institutional credentials, integrating Piwigo into a Single Sign-On (SSO) ecosystem.
Sharing to Social Media: Some plugins might facilitate sharing photos directly from Piwigo to social media platforms, though this often depends on the APIs and policies of those platforms.

Deep, seamless integration is less common out-of-the-box compared to some cloud platforms, but the API provides the foundation for building custom solutions if needed. For most users, Piwigo excels as a dedicated, self-contained photo management platform.

Workshop Automated Upload Workflow

This workshop sets up an automated workflow where photos added to a local directory are automatically synced to the Piwigo server using Syncthing, and then periodically ingested into the Piwigo gallery using a scheduled synchronization task.

Objective: Configure Syncthing to sync a local folder to a Piwigo import directory, and set up a cron job to run Piwigo's synchronization process.

Prerequisites:

A running Piwigo instance (Docker setup).
Admin access to Piwigo.
Root/sudo access to the host machine running Piwigo.
Syncthing installed on your local computer (where your photos originate). Download from https://syncthing.net/.
Syncthing installed on the Piwigo server. We'll run it as a Docker container for easy management.
Sample photos on your local computer.

Part 1: Setting up Syncthing

Create Piwigo Import Directory on Server:
- Choose a location within Piwigo's accessible file structure for imports. Using a sub-directory of the gallery volume is common.
- bash sudo mkdir -p /opt/piwigo/gallery/00-Imports # Set correct ownership for Piwigo/PHP process (use PUID/PGID from piwigo compose) sudo chown 1000:1000 /opt/piwigo/gallery/00-Imports # Replace 1000:1000 if needed
- We use 00-Imports so it potentially sorts to the top in file listings.

Run Syncthing Container on Server:

Create a directory for Syncthing's config:

sudo mkdir -p /opt/syncthing/config
cd /opt/syncthing

Create a docker-compose.yml for Syncthing:
```
sudo nano docker-compose.yml
```

Paste the following configuration:

version: "3.7"
services:
  syncthing:
    image: syncthing/syncthing:latest
    container_name: syncthing
    hostname: piwigo-server-syncthing # Optional: Set a recognisable hostname
    environment:
      - PUID=1000 # CHANGE to your user's ID on HOST (must match owner of import dir)
      - PGID=1000 # CHANGE to your user's group ID on HOST
    volumes:
      - ./config:/var/syncthing/config # Syncthing config
      - /opt/piwigo/gallery/00-Imports:/var/syncthing/piwigo-imports # Mount Piwigo import dir
    ports:
      - "8384:8384" # Web UI (access via http://SERVER_IP:8384)
      - "22000:22000/tcp" # TCP file transfers
      - "22000:22000/udp" # UDP file transfers
      - "21027:21027/udp" # Local discovery
    restart: unless-stopped
    networks: # Optional: Add to Piwigo network if needed for direct comms (usually not)
#      - piwigo-net
# networks:
#   piwigo-net:
#     external: true

Important: Change PUID and PGID to match the owner of the /opt/piwigo/gallery/00-Imports directory on the host (which should be the same PUID/PGID used for the Piwigo container). This ensures Syncthing running in the container can write files that Piwigo can later read.
We mount the Piwigo import directory (/opt/piwigo/gallery/00-Imports) to /var/syncthing/piwigo-imports inside the Syncthing container.

Save the file.
Start Syncthing:
```
sudo docker-compose up -d
```

Configure Syncthing on Server:
- Access the Syncthing Web UI on the server: http://YOUR_SERVER_IP:8384.
- It might ask if you want to allow anonymous usage reporting. Choose according to your preference.
- Set up authentication: Click Actions -> Settings -> GUI. Set a GUI Authentication User and GUI Authentication Password. Save. You'll need to log in.
- Add the Piwigo Import Folder: Click + Add Folder.
  - Folder Label: Piwigo Imports (or any name you like).
  - Folder Path: /var/syncthing/piwigo-imports (this is the path inside the Syncthing container).
  - Go to the Advanced tab. Set Watch for Changes to enabled (usually default).
  - Save.
Configure Syncthing on Local Computer:
- Start the Syncthing application you installed locally. Access its Web UI (usually http://127.0.0.1:8384).
- Set up GUI authentication locally as well (recommended).
- Create a folder on your local computer where you will place photos to be uploaded (e.g., C:\Users\YourUser\Pictures\PiwigoUploads or /home/youruser/Pictures/PiwigoUploads).
- Add this local folder in the local Syncthing UI: Click + Add Folder.
  - Folder Label: Local Piwigo Uploads.
  - Folder Path: Browse to or enter the path you created locally.
  - Save.
Connect Local and Server Syncthing Instances:
- Get Server's Syncthing ID: In the server's Syncthing UI (http://YOUR_SERVER_IP:8384), click Actions -> Show ID. Copy the long ID string.
- Add Server Device Locally: In your local Syncthing UI, click + Add Remote Device. Paste the server's ID. Give it a recognisable name (e.g., Piwigo Server). Go to the Sharing tab, check the box next to Local Piwigo Uploads to share this folder with the server. Save.
- Approve Local Device on Server: Back in the server's Syncthing UI, you should see a notification banner asking to approve the connection from your local computer. Click Add Device. Give your local computer a name. Go to the Sharing tab. Check the box next to Piwigo Imports. Click Save.
Share Folder from Server to Local (Confirm Sync):
- You might get another prompt on the local machine asking if you want to accept the Piwigo Imports folder shared by the server. Click Add. You'll be asked where to sync it locally – you likely DON'T want to sync the server's import folder back to your local machine, so you can either carefully configure it as "Send Only" on the local machine for the Local Piwigo Uploads folder, or configure the Piwigo Imports folder on the server as "Receive Only" (safer).
- Recommendation: On the Server Syncthing UI, edit the Piwigo Imports folder, go to the Advanced tab, and set Folder Type to Receive Only. This prevents accidental changes in the server's import folder from syncing back locally.
- On the Local Syncthing UI, edit the Local Piwigo Uploads folder, go to the Advanced tab, and ensure Folder Type is Send & Receive or Send Only (if you only want to send, Send Only is safest).
Test Syncthing:
- Place a few sample photos into your local PiwigoUploads folder.
- Watch the Syncthing UIs on both local and server. After a short delay, you should see the devices connect and the files start syncing.
- Verify that the photos appear in the /opt/piwigo/gallery/00-Imports directory on the server. You can check via SSH: ls -l /opt/piwigo/gallery/00-Imports.

Part 2: Scheduling Piwigo Synchronization

Now that files arrive automatically in the import directory, we need Piwigo to process them.

Identify Synchronization Method: Piwigo's synchronization can sometimes be triggered via a command-line script (tools/sync.php or similar within the Piwigo structure) or potentially an API call. The exact method can vary slightly between Piwigo versions or depend on plugins like Admin Tools. We need a command that can be run from the host server via cron. A common approach is to execute the PHP script using docker exec.
Find the Sync Script: Look inside the Piwigo container's file structure or documentation for a command-line synchronization script. Often it's located in a tools or cli directory relative to the Piwigo web root. Let's assume it's /config/www/piwigo/tools/sync.php inside the piwigo_app container (adjust path if different).
Create Cron Job:
- Edit root's crontab: sudo crontab -e.
- Add a line to execute the sync script periodically (e.g., every hour at 15 minutes past the hour).
```
# Synchronize Piwigo imports directory every hour at HH:15
# Adjust path to sync.php if necessary. Check script parameters for options (e.g., target directory, add_new_photos).
15 * * * * sudo docker exec piwigo_app php /config/www/piwigo/tools/sync.php --directory=./galleries/00-Imports --add-date=file --add --no-metadata > /var/log/piwigo_sync.log 2>&1
```
- Explanation of potential sync.php options (these might vary - check the script or docs!):
  - --directory=./galleries/00-Imports: Specifies the directory relative to the Piwigo root inside the container to synchronize. Our Syncthing target /opt/piwigo/gallery/00-Imports on the host maps to /config/www/gallery/00-Imports inside the container, so this path should work relative to Piwigo's base if galleries is the main photo dir. Double-check the exact relative path needed by the script.
  - --add-date=file: Use file modification time for photo date if EXIF is missing.
  - --add: Add new photos found.
  - --no-metadata: Optionally skip reading metadata if you handle it differently (usually you want metadata). --metadata might be the default or required.
  - (You might need other options like --recursive, --album=<id> to assign to a default album, or --privacy-level=<level>). Research the exact parameters for your Piwigo version's sync.php or the equivalent function in Admin Tools if using that.
- Save and close the crontab.
Test the Workflow:
- Add a new photo to your local Syncthing folder.
- Wait for Syncthing to transfer it to /opt/piwigo/gallery/00-Imports on the server.
- Wait for the next scheduled cron job execution (or run the docker exec ... php ... sync.php ... command manually from the terminal to test immediately).
- Check the Piwigo gallery. The new photo should appear, likely in an album structure mirroring the import directory (if configured that way) or in a default album. It should have its thumbnails generated.
- Check the log file: sudo tail /var/log/piwigo_sync.log.

You have now set up a fully automated pipeline: Photos added locally -> Synced via Syncthing -> Processed into Piwigo via scheduled task. This significantly streamlines adding new photos to your self-hosted gallery. Remember to monitor logs (piwigo_sync.log, Syncthing logs, Piwigo admin logs) occasionally to ensure everything runs smoothly.

6. Troubleshooting Common Issues

Even with careful setup, you might encounter issues with your Piwigo installation. This section covers common problems and how to diagnose and resolve them. Effective troubleshooting involves checking logs, understanding component interactions, and isolating the cause.

Installation Problems

Problem: Blank white screen or HTTP 500 error immediately after installation or during setup steps.
- Cause: Often PHP errors (syntax errors, missing extensions, fatal errors), incorrect file permissions preventing Piwigo from reading core files, or resource limits being hit.
- Troubleshooting:
  1. Check PHP Error Logs: Locate your PHP error log file. The location depends on your setup (check php.ini for error_log directive, or common locations like /var/log/php/error.log, /var/log/apache2/error.log, /var/log/nginx/error.log, or within the Docker container logs if PHP errors are sent to stderr). Look for Fatal error: or Parse error: messages occurring around the time of the failure.
  2. Check Web Server Logs: Examine Apache/Nginx error logs for related messages.
  3. Check Docker Logs: If using Docker, check the Piwigo container logs: sudo docker logs piwigo_app. PHP errors might be logged here.
  4. PHP Extensions: During installation, Piwigo checks for required PHP extensions (gd/imagick, mysqli, json, session, xml, mbstring, exif). Ensure all required extensions are installed and enabled for the PHP version used by the web server/PHP-FPM. Use php -m on the command line or create a phpinfo.php file (<?php phpinfo(); ?>) accessible via the web server to verify loaded extensions.
  5. File Permissions: Ensure the web server user (or PUID/PGID user in Docker) has read access to all Piwigo application files (index.php, include, admin directories, etc.) and write access to necessary directories (_data/config volume, cache directories, galleries directory). Incorrect permissions can prevent scripts from loading. Use ls -l to check and chown/chmod to fix.
  6. PHP memory_limit: A low memory limit might cause crashes during initial setup steps. Try temporarily increasing it in php.ini or via Docker environment variables.
Problem: Database Connection Error during installation ("Cannot connect to database", "Access denied for user...").
- Cause: Incorrect database credentials, database server not running or not accessible, incorrect database host specified.
- Troubleshooting:
  1. Verify Credentials: Double-check the Database Host, User, Password, and Database Name entered during installation match exactly what you configured (e.g., in docker-compose.yml environment variables or when creating the user manually in MySQL/MariaDB). Remember passwords are case-sensitive.
  2. Check DB Server Status: Ensure the MySQL/MariaDB server is running (systemctl status mariadb or sudo docker ps to check the piwigo_db container).
  3. Check DB Host:
    - Docker: If Piwigo and the DB are in the same Docker Compose file/network, the hostname should be the service name of the database container (e.g., piwigo-db), not localhost or 127.0.0.1. Docker's internal DNS resolves service names.
    - Manual Install: If DB is on the same server, localhost or 127.0.0.1 is usually correct. If DB is remote, use its IP address or hostname.
  4. Network Accessibility: Ensure no firewall rules (on the host or within Docker networks) are blocking the connection between the Piwigo application server/container and the database server/container on the necessary port (usually 3306). Try connecting manually from the Piwigo server/container using mysql-client: mysql -h <db_host> -u <piwigo_user> -p<piwigo_password> <piwigo_database>.
  5. User Permissions: Verify the Piwigo database user has the necessary privileges (SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, DROP) on the Piwigo database.

Upload Failures

Problem: Uploads fail, possibly with errors like "HTTP error", "File too large", or simply stalling.
- Cause: File size limits (PHP, web server), execution timeouts, incorrect permissions on upload/gallery directories, temporary space issues.
- Troubleshooting:
  1. Check File Size Limits: There are multiple limits to check:
    - PHP: upload_max_filesize (max size for single file) and post_max_size (max size of total POST request data, must be >= upload_max_filesize) in php.ini. Increase these values to accommodate your largest expected photo uploads (e.g., upload_max_filesize = 100M, post_max_size = 110M). Remember to restart PHP-FPM or Apache after changing php.ini. In Docker, these might be configurable via environment variables or a custom php.ini file mounted into the container.
    - Web Server: Nginx has client_max_body_size (set in nginx.conf within http, server, or location block). Apache might have LimitRequestBody. Ensure these are also set large enough (e.g., client_max_body_size 110m;). Restart the web server after changes. If using a reverse proxy like Nginx Proxy Manager, check its settings too.
  2. Check Execution Timeouts: Large file uploads and subsequent processing (resizing, thumbnailing) can take time. Check PHP's max_execution_time and max_input_time in php.ini. Also check web server/reverse proxy timeout settings (e.g., proxy_read_timeout, proxy_send_timeout in Nginx). Increase them if uploads of large files consistently fail after some time.
  3. Check Directory Permissions: The web server user (or PUID/PGID user) needs write permissions on the target galleries directory (or the specific album subdirectory Piwigo is trying to write to) and any temporary upload directories Piwigo might use (often within the _data/config volume). Use ls -ld /opt/piwigo/gallery /opt/piwigo/piwigo-config/_data/upload (adjust paths as needed) and chown/chmod if necessary.
  4. Check Disk Space: Ensure the filesystem hosting the galleries directory and the temporary directory has sufficient free space. Use df -h.
  5. Browser Developer Tools: Open your browser's developer tools (usually F12), switch to the "Network" tab, and try the upload again. Look for failed HTTP requests (often shown in red). Click on the failed request and examine the "Response" or "Preview" tab for specific error messages from the server. Check the "Console" tab for JavaScript errors.
  6. Piwigo Logs: Check Administration -> Tools -> Logs (if available) or look for specific log files within the _data directory for clues.

Performance Bottlenecks

Problem: Gallery pages (especially albums with many photos) load slowly, thumbnail generation is slow, searches take a long time.
- Cause: Insufficient server resources (RAM, CPU), unoptimized database/queries, slow storage, lack of caching, inefficient thumbnail generation, too many high-resolution images being loaded.
- Troubleshooting:
  1. Monitor Server Resources: Use tools like htop, top, vmstat, iostat on the host (or docker stats for containers) during periods of slowness.
    - High CPU: Could indicate heavy image processing (thumbnailing) or complex database queries. Identify the process consuming CPU (PHP-FPM, MySQL/MariaDB, ImageMagick's convert).
    - High RAM Usage/Swapping: Insufficient RAM is a common cause. The database (InnoDB buffer pool) and PHP processes are primary consumers. Consider adding RAM or tuning memory allocation (e.g., reducing innodb_buffer_pool_size if overallocated, adjusting PHP-FPM pm.max_children). Swapping (using disk as slow RAM) severely degrades performance.
    - High Disk I/O (Wait Time): Indicates the storage is a bottleneck. This is common with slow HDDs, especially during thumbnail generation or database-intensive operations. Consider upgrading to SSDs. Check iostat -x 1 for high %iowait or await times.
  2. Database Performance:
    - Enable Slow Query Log: Configure MySQL/MariaDB to log queries taking longer than a specified threshold (e.g., 1-2 seconds). Analyze the logged queries to identify problematic ones. Use EXPLAIN <query> to see how the database executes the query and if indexes are being used effectively.
    - Optimize Tables: Run OPTIMIZE TABLE periodically via Admin Tools or phpMyAdmin.
    - Check innodb_buffer_pool_size: Ensure it's appropriately sized for your available RAM.
  3. Image Loading:
    - Browser Developer Tools (Network Tab): Analyze page load times. Are specific images taking very long? Are too many thumbnails being loaded at once?
    - Photo Sizes: Review Administration -> Configuration -> Options -> Photo sizes. Ensure the sizes generated match those used by your theme. Avoid displaying unnecessarily large images on album pages.
    - Pre-generate Thumbnails: Use Admin Tools or sync scripts to generate thumbnails proactively rather than on-the-fly.
  4. Caching:
    - PHP OPcache: Verify OPcache is enabled and adequately configured (php -i | grep opcache).
    - Web Server Caching: Ensure browser caching headers (Expires, Cache-Control) are set correctly for static assets (CSS, JS, images) in your web server/reverse proxy config. Enable gzip/Brotli compression.
    - Piwigo Template Cache: Purge compiled templates occasionally (Administration -> Tools -> Maintenance).
  5. Plugin/Theme Impact: Temporarily switch to the default theme (like Modus) and disable non-essential plugins to see if performance improves. A specific plugin or complex theme could be the cause.

Plugin/Theme Conflicts

Problem: Errors, broken layout, or missing functionality occurs after activating a new plugin or theme, or after updating Piwigo/plugins/themes. Sometimes results in a "White Screen of Death" (WSOD).
- Cause: Incompatible code, JavaScript conflicts, two plugins trying to modify the same Piwigo function/hook, outdated extension after core update.
- Troubleshooting:
  1. Identify the Culprit: If the issue occurred immediately after activating/updating a specific extension, that's the prime suspect.
  2. Deactivate Suspect:
    - Via Admin UI: If you can still access Administration -> Plugins or Themes, deactivate the suspected plugin/theme.
    - Manually (if UI inaccessible/WSOD): Access the server's filesystem (via SSH or Docker volume mapping). Navigate to the plugins or themes directory (e.g., /opt/piwigo/piwigo-config/plugins). Rename the directory of the suspect plugin/theme (e.g., rename badplugin to badplugin_DISABLED). This effectively deactivates it, often restoring access to the admin UI.
  3. Check Logs: Check PHP, web server, and Piwigo logs for specific error messages pointing to the conflicting plugin/theme files.
  4. Check Compatibility: Ensure the plugin/theme version is explicitly compatible with your Piwigo version. Check the Piwigo extensions directory or the plugin/theme's documentation.
  5. Disable Extensions Systematically: If unsure which extension is causing the problem, disable all non-core plugins. If the problem disappears, re-enable them one by one, testing after each activation, until the issue reappears. The last one enabled is likely the culprit (or part of a conflict between multiple extensions).
  6. Browser Console: Check the browser's JavaScript console (F12 -> Console) for errors, which often indicate JS conflicts between extensions or the theme.
  7. Report the Issue: If you identify a conflict or bug, report it to the plugin/theme author (e.g., via the Piwigo forums or their GitHub repository) providing details about your Piwigo version, other active extensions, and the specific error messages.

Upgrade Issues

Problem: Piwigo fails to upgrade correctly, shows errors during the database update step, or behaves unexpectedly after an upgrade.
- Cause: Incomplete file transfer, permission issues preventing script execution, database update script errors, incompatibilities with older plugins/themes, PHP version incompatibility with the new Piwigo version.
- Troubleshooting:
  1. BACKUP FIRST! Always perform a full backup (database + files) before starting any upgrade.
  2. Check Requirements: Verify that your server environment (PHP version, required extensions) meets the requirements for the new Piwigo version before upgrading.
  3. Follow Upgrade Instructions: Adhere strictly to the official Piwigo upgrade guide for your method (manual, Docker image update, etc.). This usually involves replacing files, then running a database update script via the web UI.
  4. File Permissions: Ensure all new/updated Piwigo files have the correct ownership and permissions for the web server/PHP process to read them. The upgrade script itself might also need write permissions in some areas temporarily.
  5. Database Update Step: If the upgrade stalls or fails during the database update (often accessed via yourpiwigo.com/upgrade.php), check PHP and database logs for specific errors related to SQL statements. Insufficient database user permissions could be a cause.
  6. Plugin/Theme Compatibility: Deactivate potentially incompatible plugins/themes before running the upgrade process. After a successful core upgrade, update plugins/themes to versions compatible with the new Piwigo release before reactivating them.
  7. Clear Cache: After upgrading, clear Piwigo's template cache (Administration -> Tools -> Maintenance) and your browser cache.
  8. Rollback: If the upgrade fails catastrophically and you cannot easily fix it, restore your pre-upgrade backup (database and files).

Workshop Diagnosing an Upload Issue

This workshop simulates a common upload failure due to PHP's file size limit and guides you through the diagnostic process.

Objective: Experience an upload failure, use logs and developer tools to identify the cause (PHP's upload_max_filesize), and fix it.

Prerequisites:

A running Piwigo instance (Docker setup recommended).
Admin access to Piwigo.
Access to the server's command line to edit PHP configuration or Docker environment variables.
A photo file that is moderately large (e.g., 5-10MB). Check its exact size.
Browser with developer tools.

Steps:

Simulate the Problem Artificially Lower PHP Limit:
- We need to set PHP's upload_max_filesize and post_max_size lower than the size of your test photo.
- If using Docker (linuxserver/piwigo image often allows php.ini mods):
  - Connect to the Piwigo app container: sudo docker exec -it piwigo_app bash
  - Find the relevant php.ini or configuration file. It might be under /etc/php/ or /etc/php8/ (adjust version). Look for php.ini or files in conf.d. A common location for custom overrides in linuxserver images is /config/php/php-local.ini. Let's assume this exists or create it.
  - Edit/Create the file: nano /config/php/php-local.ini
  - Add the following lines, setting the limit smaller than your test file (e.g., 2MB if your photo is 5MB):
```
upload_max_filesize = 2M
post_max_size = 3M ; Must be >= upload_max_filesize
```
  - Save the file (Ctrl+X, Y, Enter).
  - Exit the container: exit
  - Restart the Piwigo container to apply changes: cd /opt/piwigo && sudo docker-compose restart piwigo-app
- If using Manual Install:
  - Locate your php.ini file (e.g., /etc/php/8.1/fpm/php.ini or /etc/php/8.1/apache2/php.ini).
  - Edit it (sudo nano ...) and find/change upload_max_filesize and post_max_size to small values (e.g., 2M and 3M).
  - Restart PHP-FPM (sudo systemctl restart php8.1-fpm) or Apache (sudo systemctl restart apache2).
Attempt the Upload:
- Open your Piwigo gallery in your browser and log in as admin.
- Navigate to an album.
- Open Developer Tools: Press F12 and switch to the "Network" tab. Check the "Preserve log" option if available.
- Click "Add Photos" / "Upload".
- Select your test photo file (the one larger than the limit you just set, e.g., the 5-10MB file).
- Start the upload.
Observe the Failure:
- The upload will likely fail. You might see:
  - An error message directly in the Piwigo uploader UI ("HTTP error", "File is too large", or similar).
  - The progress bar might stall and then show an error icon.
  - In the Developer Tools Network tab, you might see the POST request related to the upload turn red, indicating an error. Its HTTP status code might be 413 (Payload Too Large) or another error code (like 500 Internal Server Error or even a generic 200 OK if the error handling is poor, but the response body contains the error).
Diagnose using Developer Tools:
- In the Network tab, click on the failed upload request (usually a POST request to a PHP script like admin.php?page=photos_add or an API endpoint).
- Look at the "Headers" tab. Check the request payload size and the response status code. A 413 Payload Too Large code directly points to a server-side size limit.
- Look at the "Response" or "Preview" tab. Sometimes, even with an error code, the server sends back an HTML page or JSON response containing a more specific error message (e.g., "POST content-length exceeds limit...", "Uploaded file exceeds the upload_max_filesize directive...").
Diagnose using Server Logs:
- Web Server Error Log: Check the Nginx or Apache error log (/var/log/nginx/error.log, /var/log/apache2/error.log, or check docker logs piwigo_app or logs from your reverse proxy container like NPM if applicable). Look for entries occurring at the time of the failed upload. You might see messages like client intended to send too large body... (Nginx) or similar indications that a size limit was exceeded at the web server level.
- PHP Error Log: Check the PHP error log (location varies, check php.ini or /var/log/). Look for warnings like PHP Warning: POST Content-Length of ... bytes exceeds the limit of ... bytes... or PHP Warning: Uploaded file exceeded limit.... This confirms PHP's limits were hit.
Identify the Specific Limit: Based on the Developer Tools response/status code and the server/PHP logs, determine which limit was hit:
- 413 Payload Too Large in Network Tools or client intended to send too large body in Nginx logs usually points to the web server's limit (client_max_body_size).
- PHP warnings about POST Content-Length point to PHP's post_max_size.
- PHP warnings about Uploaded file exceeded limit point to PHP's upload_max_filesize.
- Often, you need to ensure all relevant limits (PHP upload_max_filesize, PHP post_max_size, Web Server client_max_body_size) are large enough.
Fix the Configuration:
- Edit the configuration file(s) identified in step 1 again (e.g., /config/php/php-local.ini in the container or php.ini on the host).
- Increase the values significantly higher than your test file size (e.g., 100M). Remember post_max_size must be greater than or equal to upload_max_filesize.
```
upload_max_filesize = 100M
post_max_size = 110M
```
- Also, if the web server limit was identified (e.g., client_max_body_size in Nginx), ensure that is increased as well (e.g., client_max_body_size 110m;). This might be in /etc/nginx/nginx.conf or a site configuration file, or within Nginx Proxy Manager's advanced settings for the proxy host.
- Save the configuration file(s).
- Restart the relevant services (Piwigo Docker container, PHP-FPM, Nginx/Apache, NPM container if changed).
Retest the Upload:
- Clear your browser cache/cookies for the site (optional but good practice).
- Go back to Piwigo, refresh the page.
- Try uploading the same large photo file again.
- The upload should now complete successfully.

This workshop demonstrated a typical troubleshooting workflow: observe the failure, use browser and server-side tools/logs to gather evidence, identify the specific configuration causing the issue, correct the configuration, and verify the fix. This systematic approach is key to resolving many common self-hosting problems.

Conclusion

Throughout this guide, we have journeyed from the fundamentals of Piwigo to advanced administration, optimization, and automation techniques. You should now have a solid understanding of what Piwigo is, why self-hosting it provides significant benefits in terms of control, privacy, and customization, and how to effectively manage your own instance.

We covered:

Core Concepts: Understanding albums, tags, users, groups, permissions, themes, and plugins.
Installation: Recognizing system requirements and successfully setting up Piwigo using the recommended Docker Compose method.
Configuration: Navigating the admin interface to tailor general settings, display options, upload handling, and more.
Organization: Implementing effective strategies for structuring albums and utilizing tags for flexible photo discovery, leveraging the power of the Batch Manager.
Enhancement: Extending Piwigo's capabilities and customizing its appearance through the vast ecosystem of plugins and themes.
Advanced Management: Tuning performance by optimizing images, databases, and server settings; implementing crucial backup and recovery strategies; and hardening security through HTTPS, updates, and proper configuration.
Automation: Utilizing the Piwigo API and tools like Syncthing to create automated upload workflows, saving time and effort.
Troubleshooting: Developing a systematic approach to diagnose and resolve common issues related to installation, uploads, performance, and extensions.

By completing the workshops, you've gained hands-on experience in setting up, configuring, organizing, extending, securing, and automating your Piwigo gallery. You've built a functional, secure, and personalized home for your digital photo collection.

Self-hosting Piwigo is a rewarding endeavor that puts you firmly in control of your precious memories. While it requires an initial investment in learning and setup, the long-term benefits of data ownership, privacy, and unparalleled flexibility are substantial. The open-source nature of Piwigo ensures a vibrant community, ongoing development, and a wealth of resources to draw upon.

Further Learning:

Official Piwigo Documentation: The definitive source for detailed information on configuration, features, API methods, and troubleshooting (https://piwigo.org/doc/doku.php).
Piwigo Forums: An active community where you can ask questions, share solutions, and learn from other users (https://piwigo.org/forum/).
Piwigo Extensions Directory: Explore the full range of available plugins and themes (https://piwigo.org/ext/).
Docker & Linux Administration Resources: Continue learning about Docker, Linux command line, web server configuration (Nginx/Apache), database management (MySQL/MariaDB), and security best practices to become a more proficient self-hoster.

We encourage you to continue exploring Piwigo's features, experiment with different plugins and themes, and contribute back to the community if you can. Happy photo managing!