Photos intermediate ⏱ 45 minutes

Piwigo: Photo Gallery Software

Feature-rich photo gallery. Plugins, themes, and batch management.

By Homelab Team • 2025-01-15
#piwigo#photos#gallery#plugins#docker

Introduction

Piwigo is a mature, open-source photo gallery software that has been actively developed since 2002. With over two decades of continuous improvement, Piwigo offers a stable, feature-rich platform for organizing and sharing photos with extensive customization through plugins and themes.

What is Piwigo?

Piwigo (pronounced “pee-wee-go”) is a web-based photo gallery application written in PHP that emphasizes flexibility, extensibility, and multi-user management. It’s designed to handle everything from small personal galleries to large institutional collections with hundreds of thousands of photos.

Core Strengths:

Mature and Stable With 20+ years of development, Piwigo has proven stability and reliability. Regular security updates and a conservative approach to new features mean your gallery remains stable and secure.

Extensive Plugin Ecosystem Over 350 community-developed plugins extend Piwigo’s functionality, adding features like watermarking, social media integration, advanced statistics, video support, and much more.

Multi-User Management Sophisticated permission system allows creating user groups with granular access controls, making Piwigo ideal for team environments, photography clubs, or family sharing.

Professional Features

  • Hierarchical album organization (unlimited nesting)
  • Advanced batch operations
  • Multiple theme support
  • Watermark protection
  • Guest and member access levels
  • Detailed statistics and analytics
  • EXIF data management
  • Geolocation mapping
  • Mobile apps (iOS and Android)
  • API for third-party integration

Why Choose Piwigo?

For Organizations: Piwigo excels in multi-user environments where different groups need different permission levels. Schools, non-profits, photography clubs, and small businesses benefit from its robust access control system.

For Photographers: Professional photographers appreciate Piwigo’s batch operations, watermarking capabilities, and client delivery features. The plugin ecosystem provides tools for selling prints, managing bookings, and presenting portfolios.

For Families: Families value Piwigo’s simple sharing capabilities, guest access for relatives, and mobile apps that make viewing photos easy for less technical family members.

For Archivists: Organizations managing photo archives benefit from Piwigo’s proven scalability, handling libraries of 500,000+ photos with proper optimization.

Piwigo vs. Alternatives

FeaturePiwigoLycheePhotoPrism
Maturity20+ years8+ years5+ years
Plugins350+FewNone
Themes100+LimitedFew
Multi-UserExcellentGoodGood
Mobile AppsNativeWebNative
AI FeaturesVia pluginsNoneBuilt-in
Resource UsageLowVery LowMedium-High
CustomizationExtensiveLimitedLimited
Learning CurveModerateEasyModerate

Prerequisites

Hardware Requirements

Minimum Configuration:

  • CPU: 1 core (2+ cores recommended)
  • RAM: 512MB (1GB recommended)
  • Storage: 10GB + photo library size
  • Network: 100Mbps connection

Recommended Configuration:

  • CPU: 2-4 cores
  • RAM: 2-4GB
  • Storage: 100GB+ SSD for operating system and database
  • Storage: Separate drive/mount for photo library
  • Network: Gigabit ethernet

Scaling Considerations:

  • Up to 10,000 photos: Minimum specs sufficient
  • 10,000-50,000 photos: Recommended specs
  • 50,000-100,000 photos: 4GB+ RAM, database tuning
  • 100,000+ photos: Consider dedicated database server

Software Requirements

  • Docker Engine 20.10+
  • Docker Compose v2.0+
  • Compatible with Linux, macOS, Windows (via WSL2)
  • Modern web browser
  • Optional: Reverse proxy for SSL/HTTPS

Supported Image Formats

  • JPEG/JPG (primary format)
  • PNG
  • GIF
  • TIFF
  • BMP
  • WebP (with plugins)
  • RAW formats (with ImageMagick or RAW converter plugins)
  • Video formats (with video extension plugins)

Installation

Step 1: Create Directory Structure

Set up directories for Piwigo’s data and configuration:

# Create main Piwigo directory
mkdir -p ~/piwigo
cd ~/piwigo

# Create subdirectories for organization
mkdir -p gallery
mkdir -p database
mkdir -p config

# Set permissions
chmod -R 755 gallery
chmod 700 database

Directory Layout:

  • gallery: Piwigo application files and uploaded photos
  • database: MySQL/MariaDB data files
  • config: Backup location for configuration files

Step 2: Docker Compose Configuration

Create a docker-compose.yml file:

version: '3.8'

services:
  piwigo-db:
    image: mariadb:11
    container_name: piwigo-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: RootPassword123
      MYSQL_DATABASE: piwigo
      MYSQL_USER: piwigo
      MYSQL_PASSWORD: PiwigoDBPassword456
    volumes:
      - ./database:/var/lib/mysql
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
      - --max_allowed_packet=64M

  piwigo:
    image: linuxserver/piwigo:latest
    container_name: piwigo
    restart: unless-stopped
    depends_on:
      - piwigo-db
    ports:
      - "8888:80"
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - ./gallery:/config
      - ./gallery/photos:/config/www/gallery/upload

networks:
  default:
    name: piwigo-network

Configuration Notes:

  1. Change passwords:

    • MYSQL_ROOT_PASSWORD: Strong root password
    • MYSQL_PASSWORD: Database password for Piwigo

  2. Set timezone:

    • Replace America/New_York with your timezone
    • List timezones: timedatectl list-timezones

  3. User ID configuration:

    • PUID and PGID should match your user ID
    • Find your IDs: id -u and id -g

  4. Port configuration:

    • Default: 8888 (change if conflicts with other services)
    • Internal container port 80 should not be changed

Step 3: Deploy Piwigo

Start the containers:

# Pull images and start services
docker compose up -d

# Monitor initialization
docker compose logs -f piwigo

# Wait for: "Done" or "Server ready"

Verify containers are running:

docker compose ps

Both piwigo and piwigo-db should show “Up” status.

Step 4: Initial Setup Wizard

Navigate to http://YOUR-SERVER-IP:8888 in your browser.

Installation Wizard Steps:

1. Language Selection

  • Choose your preferred language
  • Click “Start installation”

2. Database Configuration

  • Host: piwigo-db
  • User: piwigo
  • Password: PiwigoDBPassword456 (match docker-compose.yml)
  • Database name: piwigo
  • Database prefix: piwigo_ (default, can customize)

3. Admin Account

  • Username: Choose admin username (recommend NOT using “admin”)
  • Password: Strong password (12+ characters)
  • Password confirmation: Re-enter password
  • Email: Your email address

4. Gallery Configuration

  • Gallery title: Name your gallery
  • Description: Optional gallery description

5. Complete Installation

  • Click “Start Installation”
  • Wait for database initialization
  • Redirects to login page upon completion

Step 5: Initial Configuration

Log in with your admin credentials and configure basic settings:

Navigate to Administration (Admin icon in top right)

General Settings:

  1. Configuration > General
  2. Set guest access preferences
  3. Configure timezone
  4. Set default language
  5. Save changes

Photo Display Settings:

  1. Configuration > Options > Display
  2. Number of photos per page
  3. Default display mode (grid, list)
  4. Photo quality settings
  5. Save changes

Upload Settings:

  1. Configuration > Options > Upload
  2. Enable web upload
  3. Set max file size (default: 2MB, increase as needed)
  4. Configure allowed file types
  5. Save changes

Photo Import and Organization

Method 1: Web Upload

The simplest method for adding photos through the web interface:

Single/Multiple Photo Upload:

  1. Navigate to Photos > Add
  2. Select photos from your computer
  3. Choose destination album (or create new)
  4. Optional settings:
    • Photo quality
    • Resize options
    • Privacy level
  5. Click “Start Upload”
  6. Wait for processing to complete

Batch Upload Tips:

  • Maximum files per batch depends on PHP settings
  • For large batches, use FTP method instead
  • Photos process sequentially
  • Don’t close browser until upload completes

Method 2: FTP Upload

For large photo collections, FTP upload is more efficient:

Step 1: Copy Photos via FTP/SFTP

# Using SCP (from local machine)
scp -r /path/to/photos/* user@server-ip:~/piwigo/gallery/photos/upload/

# Or using rsync
rsync -av --progress /path/to/photos/   user@server-ip:~/piwigo/gallery/photos/upload/

Step 2: Synchronize in Piwigo

  1. Log in as admin
  2. Navigate to Photos > Synchronize
  3. Click “Synchronize”
  4. Piwigo scans upload directory
  5. Review found photos
  6. Select all (or specific photos)
  7. Click “Submit”
  8. Photos are added to gallery

Organized FTP Upload:

Create folder structure before uploading:

~/piwigo/gallery/photos/upload/
├── 2023/
│   ├── January/
│   ├── February/
│   └── December/
├── 2024/
│   └── January/
└── Events/
    ├── Birthdays/
    └── Vacations/

Piwigo creates albums matching folder structure automatically during synchronization.

Method 3: Command-Line Import

For advanced users, direct database import:

# Access Piwigo container
docker compose exec piwigo bash

# Use piwigo CLI (if available in your image)
# Or run PHP scripts directly
cd /config/www/gallery/admin

# Synchronize filesystem
php synchronize.php

Album Organization

Creating Albums:

  1. Navigate to Albums > Manage
  2. Click “Create album”
  3. Configure:
    • Album name
    • Description
    • Parent album (for nested structure)
    • Sort order
  4. Click “Submit”

Nested Album Structure:

Piwigo supports unlimited nesting:

Travel Photography
├── Europe
│   ├── France
│   │   ├── Paris
│   │   └── Provence
│   ├── Italy
│   │   ├── Rome
│   │   └── Venice
│   └── Spain
└── Asia
    ├── Japan
    └── Thailand

Album Settings:

For each album, configure:

  • Privacy: Public, private, or restricted to groups
  • Representative: Cover photo for album
  • Position: Sort order among sibling albums
  • Permissions: Who can view/upload
  • Status: Public or private

Moving Photos Between Albums:

  1. Select photos (checkbox on thumbnails)
  2. Choose “Associate to album” from batch actions
  3. Select destination album
  4. Photos can exist in multiple albums (virtual organization)

Physical vs. Virtual Albums:

Piwigo supports both:

  • Physical: Album corresponds to filesystem folder
  • Virtual: Album is database-only, photos can be in multiple virtual albums

Smart Organization Features

Tags:

Apply tags to photos for cross-album organization:

  1. Select photos
  2. Batch manager > Add tags
  3. Create or select existing tags
  4. Tags create virtual groupings across albums

Batch Manager:

Powerful tool for bulk operations:

  1. Photos > Batch Manager
  2. Filter photos by:
    • Album
    • Tag
    • Date
    • Rating
    • Search criteria
  3. Perform actions:
    • Delete photos
    • Add to albums
    • Apply tags
    • Set properties
    • Regenerate thumbnails

Plugin Installation and Configuration

Piwigo’s extensive plugin library extends functionality significantly.

Installing Plugins

Method 1: Via Web Interface (Recommended)

  1. Navigate to Plugins > Manage
  2. Click “Available plugins” tab
  3. Browse or search for desired plugin
  4. Click “Install” on chosen plugin
  5. After installation, click “Activate”
  6. Configure plugin settings

Method 2: Manual Installation

# Download plugin ZIP from piwigo.org
wget https://piwigo.org/ext/download.php?eid=PLUGIN_ID

# Extract to plugins directory
unzip plugin.zip -d ~/piwigo/gallery/plugins/

# Fix permissions
chmod -R 755 ~/piwigo/gallery/plugins/

# Activate via web interface: Plugins > Manage

Essential Plugins

1. Batch Manager Enhancements

  • Name: BatchManagerEnhanced
  • Features: Advanced batch operations, metadata editing
  • Use case: Managing large photo collections

2. Community Plugin

  • Name: community
  • Features: Allow users to upload to their own galleries
  • Use case: Multi-user environments, clubs, organizations

3. Video.js

  • Name: videojs
  • Features: HTML5 video player support
  • Use case: Mixed photo and video galleries

4. Maps (Leaflet)

  • Name: Leaflet Maps
  • Features: Display photos on interactive maps
  • Use case: Travel photography, location-based galleries

5. Extended Description

  • Name: ExtendedDescription
  • Features: Rich text descriptions with formatting
  • Use case: Professional portfolios, educational galleries

6. Batch Download

  • Name: BatchDownload
  • Features: Allow users to download multiple photos as ZIP
  • Use case: Client delivery, family sharing

7. User Collections

  • Name: UserCollections
  • Features: Let users create their own collections
  • Use case: Event photography, allowing guests to favorite photos

8. Watermark

  • Name: Watermark
  • Features: Automatic watermark application
  • Use case: Copyright protection, professional photography

9. Facebook Share

  • Name: facebookShare
  • Features: Social media integration
  • Use case: Public galleries, marketing

10. Statistics

  • Name: Statistics
  • Features: Detailed visitor analytics
  • Use case: Understanding gallery usage, popular photos

Theme Installation

Change Piwigo’s appearance with themes:

Install Theme:

  1. Navigate to Configuration > Themes
  2. Click “Available themes” tab
  3. Browse themes
  4. Click “Install” on chosen theme
  5. Set as default theme

Popular Themes:

  • Bootstrap Default: Modern, responsive design
  • Modus: Clean, minimalist interface
  • Elegant: Professional photography showcase
  • Dark: Dark mode theme
  • Material: Google Material Design inspired

Customize Theme:

  1. Configuration > Themes
  2. Click “Configure” on active theme
  3. Adjust colors, layouts, fonts
  4. Preview changes
  5. Save configuration

User Management and Permissions

Piwigo excels at multi-user management with granular permissions.

Creating User Accounts

Add New User:

  1. Navigate to Users > Manage
  2. Click “Add a user”
  3. Enter details:
    • Username
    • Password
    • Email (optional)
  4. Click “Submit”

User Roles:

Piwigo has flexible role system:

Admin:

  • Full system access
  • Manage users and groups
  • Install plugins and themes
  • Configure all settings

Webmaster:

  • Manage content
  • Create albums
  • Upload photos
  • Limited system settings

Normal User:

  • View assigned albums
  • Comment and rate photos
  • Create favorites
  • Download photos (if permitted)

Guest:

  • View public albums only
  • Limited or no interaction
  • No login required

Groups and Permissions

Create User Groups:

  1. Users > Groups
  2. Click “Create group”
  3. Name the group
  4. Add users to group

Set Group Permissions:

  1. Albums > Manage
  2. Select album
  3. Click “Permissions”
  4. Choose which groups can access
  5. Set permission level:
    • View only
    • View and download
    • View, download, and comment

Example Permission Structure:

Family Photos
├── Public Events (Everyone)
├── Private Family (Family Group)
├── Parents Only (Parents Group)
└── Kids Photos (Family + Grandparents Groups)

Professional Portfolio
├── Public Gallery (Everyone)
├── Client Previews (Clients Group)
└── Unedited Raw (Admin Only)

Advanced Access Control

Private Albums:

  1. Create album
  2. Set status to “Private”
  3. Albums > Permissions
  4. Select specific users or groups
  5. Users must be logged in to view

Time-Limited Access:

Use plugins like “Guest Access” to create temporary viewing links:

  1. Install Guest Access plugin
  2. Create temporary guest account
  3. Set expiration date
  4. Share credentials with client/guest
  5. Access automatically revoked after expiration

Mobile Apps and Access

Official Mobile Apps

Piwigo provides native mobile applications:

iOS App (Piwigo NG)

  • Available on Apple App Store
  • Features:
    • Browse albums and photos
    • Upload photos from camera roll
    • Create and manage albums
    • Batch operations
    • Offline viewing
    • Touch ID/Face ID authentication

Android App

  • Available on Google Play Store
  • Features:
    • Full gallery browsing
    • Photo upload from device
    • Album management
    • Cache management
    • Auto-upload capability
    • Share to Piwigo from other apps

Mobile App Setup

Configure Server Connection:

  1. Install Piwigo app on mobile device
  2. Open app
  3. Add new server:
    • Server URL: http://YOUR-SERVER-IP:8888 or https://photos.yourdomain.com
    • Username: Your Piwigo username
    • Password: Your Piwigo password
  4. Test connection
  5. Save configuration

Enable Mobile Uploads:

  1. In Piwigo web interface: Plugins > Manage
  2. Install “Community” plugin
  3. Activate plugin
  4. Configure upload permissions
  5. Mobile app can now upload to designated albums

Auto-Upload Configuration (Android):

  1. Open Piwigo app
  2. Settings > Auto Upload
  3. Configure:
    • Enable auto upload
    • Choose upload album
    • WiFi only or cellular allowed
    • Delete after upload option
  4. Select folders to monitor (Camera, Screenshots, etc.)

Responsive Web Interface

Piwigo’s web interface is mobile-responsive:

Mobile Browser Access:

  • Navigate to your Piwigo URL
  • Interface automatically adapts to screen size
  • Touch gestures for navigation
  • Swipe to navigate photos
  • Pinch to zoom

Progressive Web App:

Add Piwigo to home screen for app-like experience:

iOS:

  1. Open Piwigo in Safari
  2. Tap Share button
  3. “Add to Home Screen”

Android:

  1. Open Piwigo in Chrome
  2. Menu > “Add to Home Screen”
  3. Icon appears in launcher

Backup Strategies

Database Backup

Piwigo’s database contains critical metadata, albums, and configuration.

Automated Database Backup Script:

#!/bin/bash
# File: ~/piwigo/backup-db.sh

BACKUP_DIR=~/piwigo/backups/database
DATE=$(date +%Y%m%d_%H%M%S)
DB_PASSWORD="PiwigoDBPassword456"

mkdir -p $BACKUP_DIR

# Backup Piwigo database
docker compose exec -T piwigo-db mysqldump   -u piwigo   -p$DB_PASSWORD   --single-transaction   --routines   --triggers   piwigo | gzip > $BACKUP_DIR/piwigo_db_$DATE.sql.gz

# Keep only last 30 days
find $BACKUP_DIR -name "piwigo_db_*.sql.gz" -mtime +30 -delete

# Log completion
echo "Database backup completed: piwigo_db_$DATE.sql.gz"

Schedule with Cron:

chmod +x ~/piwigo/backup-db.sh

# Edit crontab
crontab -e

# Add daily backup at 2 AM
0 2 * * * ~/piwigo/backup-db.sh >> ~/piwigo/backup.log 2>&1

Photo Library Backup

Method 1: Rsync to External Storage

#!/bin/bash
# File: ~/piwigo/backup-photos.sh

SOURCE=~/piwigo/gallery/photos
DEST=/mnt/backup/piwigo/photos
DATE=$(date +%Y%m%d)

# Create backup with rsync
rsync -av --delete   --exclude="pwg_high"   --exclude="thumbnail"   --log-file=~/piwigo/backup-photos-$DATE.log   $SOURCE/ $DEST/

echo "Photo backup completed: $DATE"

Method 2: Incremental Backup with Restic

# Initialize repository (one-time)
restic init --repo /mnt/backup/piwigo-restic

# Backup script
#!/bin/bash
# File: ~/piwigo/restic-backup.sh

export RESTIC_REPOSITORY=/mnt/backup/piwigo-restic
export RESTIC_PASSWORD="YourResticPassword"

# Backup photos
restic backup ~/piwigo/gallery/photos   --exclude="thumbnail"   --exclude="pwg_*"   --tag daily

# Backup database
docker compose exec -T piwigo-db mysqldump   -u piwigo   -pPiwigoDBPassword456   piwigo > /tmp/piwigo_backup.sql

restic backup /tmp/piwigo_backup.sql --tag database
rm /tmp/piwigo_backup.sql

# Keep only last 30 daily, 12 monthly snapshots
restic forget --keep-daily 30 --keep-monthly 12 --prune

echo "Restic backup completed"

Method 3: Cloud Backup with Rclone

# Configure rclone (one-time)
rclone config

# Backup script
#!/bin/bash
# File: ~/piwigo/cloud-backup.sh

# Sync photos to cloud storage
rclone sync ~/piwigo/gallery/photos   remote:piwigo-backup/photos   --exclude "thumbnail/**"   --exclude "pwg_*/**"   --progress   --transfers 4

# Backup database to cloud
docker compose exec -T piwigo-db mysqldump   -u piwigo   -pPiwigoDBPassword456   piwigo | gzip |   rclone rcat remote:piwigo-backup/database/piwigo_$(date +%Y%m%d).sql.gz

echo "Cloud backup completed"

Full System Backup

Complete backup including configuration:

#!/bin/bash
# File: ~/piwigo/full-backup.sh

BACKUP_ROOT=/mnt/backup/piwigo
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR=$BACKUP_ROOT/$DATE

mkdir -p $BACKUP_DIR

# Stop containers temporarily (optional, for consistency)
# docker compose stop piwigo

# Backup database
docker compose exec -T piwigo-db mysqldump   -u piwigo   -pPiwigoDBPassword456   piwigo | gzip > $BACKUP_DIR/database.sql.gz

# Backup entire gallery directory
tar -czf $BACKUP_DIR/gallery.tar.gz -C ~/piwigo gallery/

# Backup configuration
cp ~/piwigo/docker-compose.yml $BACKUP_DIR/
cp ~/piwigo/*.sh $BACKUP_DIR/

# Restart containers if stopped
# docker compose start piwigo

# Create manifest
cat > $BACKUP_DIR/manifest.txt << EOF
Piwigo Full Backup
Date: $DATE
Database: database.sql.gz
Gallery: gallery.tar.gz
Configuration: docker-compose.yml
EOF

# Keep only last 14 full backups
cd $BACKUP_ROOT
ls -t | tail -n +15 | xargs rm -rf

echo "Full backup completed: $DATE"

Disaster Recovery

Restore from Backup:

#!/bin/bash
# File: ~/piwigo/restore.sh

BACKUP_DATE="20250115_020000"  # Specify backup date
BACKUP_DIR=/mnt/backup/piwigo/$BACKUP_DATE

# Stop containers
cd ~/piwigo
docker compose down

# Restore gallery
rm -rf ~/piwigo/gallery/*
tar -xzf $BACKUP_DIR/gallery.tar.gz -C ~/piwigo/

# Restore database
gunzip < $BACKUP_DIR/database.sql.gz |   docker compose exec -T piwigo-db mysql   -u piwigo   -pPiwigoDBPassword456   piwigo

# Restore configuration
cp $BACKUP_DIR/docker-compose.yml ~/piwigo/

# Restart containers
docker compose up -d

echo "Restoration completed from: $BACKUP_DATE"
echo "Verify gallery at: http://YOUR-SERVER-IP:8888"

Test Recovery Procedure:

Regularly test your backups:

# Create test environment
mkdir -p ~/piwigo-test
cd ~/piwigo-test

# Copy compose file
cp ~/piwigo/docker-compose.yml .

# Modify ports to avoid conflicts
sed -i 's/8888:80/8889:80/' docker-compose.yml

# Deploy test instance
docker compose up -d

# Restore backup to test instance
# ... (restoration steps) ...

# Verify gallery works
# Open: http://YOUR-SERVER-IP:8889

# Cleanup test instance
docker compose down -v
cd ~
rm -rf ~/piwigo-test

Troubleshooting

Upload Issues

Problem: Photos fail to upload or upload stops midway.

Solutions:

  1. Increase PHP upload limits:
# Access container
docker compose exec piwigo bash

# Edit PHP configuration
cat >> /config/php/php-local.ini << EOF
upload_max_filesize = 100M
post_max_size = 100M
max_execution_time = 300
memory_limit = 256M
EOF

# Restart container
docker compose restart piwigo
  1. Check available disk space:
df -h ~/piwigo/gallery
  1. Verify permissions:
chmod -R 755 ~/piwigo/gallery/photos

Slow Performance

Problem: Gallery loads slowly or times out.

Solutions:

  1. Optimize database:
docker compose exec piwigo-db mysqlcheck -u root -p --optimize --all-databases

  1. Regenerate thumbnails with optimized settings:

    • Photos > Batch Manager
    • Select all photos
    • Actions > Regenerate thumbnails
    • Use medium quality settings

  2. Enable caching:

    • Configuration > Options
    • Enable “Cache management”
    • Set cache lifetime appropriately

  3. Increase database memory:

# In docker-compose.yml
command:
  - --innodb-buffer-pool-size=512M
  - --query-cache-size=32M

Thumbnail Generation Failures

Problem: Thumbnails not generating or showing broken images.

Solutions:

  1. Check ImageMagick/GD availability:
docker compose exec piwigo php -m | grep -i imagick
docker compose exec piwigo php -m | grep -i gd

  1. Manually regenerate:

    • Photos > Batch Manager
    • Filter problematic photos
    • Actions > Delete thumbnails
    • Actions > Regenerate thumbnails

  2. Adjust thumbnail quality:

    • Configuration > Options
    • Lower thumbnail quality to 85%
    • Reduce maximum dimensions

Database Connection Issues

Problem: Cannot connect to database.

Solutions:

  1. Verify database container is running:
docker compose ps piwigo-db
  1. Test database connection:
docker compose exec piwigo-db mysql -u piwigo -p -e "SELECT 1;"

  1. Check credentials match in docker-compose.yml

  2. Restart both containers:

docker compose restart piwigo-db
sleep 10
docker compose restart piwigo

Plugin Installation Failures

Problem: Plugins fail to install or activate.

Solutions:

  1. Check write permissions:
chmod -R 755 ~/piwigo/gallery/plugins
  1. Manually install plugin:
# Download plugin ZIP
cd ~/piwigo/gallery/plugins
wget https://piwigo.org/ext/download.php?eid=PLUGIN_ID -O plugin.zip
unzip plugin.zip
rm plugin.zip

# Fix permissions
chmod -R 755 .
  1. Clear Piwigo cache:
    • Configuration > Maintenance
    • Clear compiled templates
    • Restart container

Mobile App Connection Issues

Problem: Mobile app cannot connect to server.

Solutions:

  1. Verify server URL is accessible from mobile device
  2. Check firewall allows connections on port 8888
  3. Test in mobile browser first
  4. For HTTPS: Ensure valid SSL certificate
  5. Check Piwigo API is enabled:
    • Configuration > Options
    • Enable Web Services access

Advanced Configuration

Reverse Proxy with SSL

Nginx Proxy Manager Configuration:

  1. Add new proxy host
  2. Configure:
    • Domain: photos.yourdomain.com
    • Scheme: http
    • Forward Hostname/IP: piwigo or server IP
    • Forward Port: 8888
  3. SSL tab:
    • Request SSL certificate (Let’s Encrypt)
    • Force SSL enabled
    • HTTP/2 Support enabled

Update Piwigo configuration:

Edit ~/piwigo/gallery/local/config/config.inc.php:

$conf['site_url'] = 'https://photos.yourdomain.com';

Traefik Configuration:

Add labels to docker-compose.yml:

services:
  piwigo:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.piwigo.rule=Host(`photos.yourdomain.com`)"
      - "traefik.http.routers.piwigo.entrypoints=websecure"
      - "traefik.http.routers.piwigo.tls=true"
      - "traefik.http.routers.piwigo.tls.certresolver=letsencrypt"
      - "traefik.http.services.piwigo.loadbalancer.server.port=80"

Performance Optimization

Enable Memcached:

Add to docker-compose.yml:

services:
  memcached:
    image: memcached:alpine
    container_name: piwigo-memcached
    restart: unless-stopped

  piwigo:
    depends_on:
      - memcached

Edit Piwigo configuration:

$conf['cache_driver'] = 'memcached';
$conf['memcached_servers'] = array(
  array('host' => 'memcached', 'port' => 11211)
);

Custom Domain and CDN

Use CDN for static assets:

  1. Install “CDN” plugin
  2. Configure CDN URL
  3. Static assets served from CDN
  4. Reduces server bandwidth
  5. Improves load times globally

Conclusion

Piwigo stands out as a mature, feature-complete photo gallery solution with proven reliability over two decades of active development. Its extensive plugin ecosystem, sophisticated multi-user management, and native mobile apps make it particularly suitable for organizations, photography professionals, and families who need robust photo management with granular control.

Key Strengths:

  • Mature, stable platform with 20+ years development
  • 350+ plugins for extensive customization
  • Excellent multi-user and permission management
  • Native iOS and Android apps
  • Low resource requirements
  • Professional features for photographers

Ideal Use Cases:

  • Photography clubs and organizations
  • Schools and educational institutions
  • Professional photographer client delivery
  • Family photo sharing with access controls
  • Small business photo galleries
  • Archive management

When to Choose Piwigo Over Alternatives:

  • Need sophisticated permission systems
  • Want extensive plugin customization
  • Prefer mature, proven technology
  • Require native mobile apps
  • Managing multi-user environments
  • Running on resource-constrained hardware

For homelabbers seeking a reliable, flexible photo gallery solution with professional features and extensive community support, Piwigo delivers a time-tested platform that balances power with usability.

Next steps to enhance your Piwigo installation:

  • Explore plugin marketplace for your specific needs
  • Configure automated backups
  • Set up reverse proxy with SSL
  • Install mobile apps for easy access
  • Customize theme to match your branding
  • Create user groups and permission structure

Your photo gallery should be as unique as your photos. Piwigo provides the flexibility to make it exactly what you need.