Piwigo is a robust, open-source photo management application designed for self-hosting. It’s an excellent solution for users seeking full control over their photo libraries, offering extensive customization, plugins, and API support. This guide will walk you through installing, configuring, and managing Piwigo, with actionable steps tailored to developers and system administrators.
Installing Piwigo
📦 Using Docker and Docker Compose
Docker simplifies the deployment of Piwigo by providing an isolated environment for the app. Use the following docker-compose.yml file to get started.
version: '3.8'
services:
piwigo:
image: linuxserver/piwigo
container_name: piwigo
ports:
- "8080:80" # Map HTTP traffic to port 8080
volumes:
- ./config:/config # Persistent configuration and data
- ./photos:/photos # Photo library storage
environment:
- PUID=1000 # User ID for permissions
- PGID=1000 # Group ID for permissions
- TZ=Etc/UTC # Timezone configuration
restart: unless-stopped
Run the following commands to deploy Piwigo using Docker Compose:
mkdir -p ~/piwigo && cd ~/piwigo
## Create the docker-compose.yml file
nano docker-compose.yml
## Start the Piwigo container
docker-compose up -d
## Verify the container is running
docker ps
Access Piwigo by visiting http://<your-server-ip>:8080 in your web browser.
🚀 Manual Installation
If you prefer a direct installation on a Linux server, follow these steps:
- Install required dependencies:
sudo apt update && sudo apt install -y apache2 mariadb-server php php-mysql php-gd php-xml php-curl unzip
- Download and extract Piwigo:
wget https://piwigo.org/download/dlcounter.php?code=latest -O piwigo.zip
unzip piwigo.zip -d /var/www/html
sudo mv /var/www/html/piwigo /var/www/html/piwigo-app
- Set permissions and ownership:
sudo chown -R www-data:www-data /var/www/html/piwigo-app
sudo chmod -R 755 /var/www/html/piwigo-app
- Configure the database:
sudo mysql -u root -p
CREATE DATABASE piwigo_db;
CREATE USER 'piwigo_user'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON piwigo_db.* TO 'piwigo_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;
- Restart Apache and access Piwigo:
sudo systemctl restart apache2
Visit http://<your-server-ip>/piwigo-app and follow the setup wizard.
Configuring Nginx as a Reverse Proxy
🌐 Nginx Configuration
To route traffic through Nginx, create a server block configuration file:
sudo nano /etc/nginx/sites-available/piwigo
Insert the following configuration:
server {
listen 80;
server_name piwigo.example.com;
location / {
proxy_pass http://127.0.0.1:8080; # Change port if running manually
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
client_max_body_size 100M; # Allow larger file uploads
}
Enable the configuration and restart Nginx:
sudo ln -s /etc/nginx/sites-available/piwigo /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
🔒 SSL/TLS Setup
Secure Piwigo with Let's Encrypt:
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d piwigo.example.com
Automate certificate renewals:
sudo systemctl enable certbot.timer
Logging and Debugging Piwigo
🗃️ Enabling Debug Logs
Activate debug logging in Piwigo by editing the local/config/config.inc.php file:
$conf['debug_mode'] = true;
📄 Viewing Logs
For Docker deployments, use:
docker logs piwigo
For manual installations, check Apache logs:
sudo tail -f /var/log/apache2/error.log
🛠️ Troubleshooting Common Issues
If Piwigo fails to load, verify permissions:
sudo chown -R www-data:www-data /var/www/html/piwigo-app
Ensure the database credentials in local/config/database.inc.php match your setup.
Backup and Restore
🗂️ File-Based Backups
Create a backup of Piwigo’s critical files:
tar -czf piwigo-files-backup.tar.gz /var/www/html/piwigo-app
🔄 Database Backups
Export the database:
mysqldump -u piwigo_user -p piwigo_db > piwigo-db-backup.sql
Restore using:
mysql -u piwigo_user -p piwigo_db < piwigo-db-backup.sql
📅 Automated Backup Scripts
Set up a cron job for regular backups:
crontab -e
## Add the following line for daily backups at midnight
0 0 * * * tar -czf ~/piwigo-files-$(date +\%F).tar.gz /var/www/html/piwigo-app && mysqldump -u piwigo_user -p'password' piwigo_db > ~/piwigo-db-$(date +\%F).sql
Updating and Upgrading Piwigo
⬆️ Updating Docker Images
Pull the latest image and redeploy:
docker-compose pull
docker-compose up -d
🛠️ Manual Updates
Download the newest version and replace files, preserving local and upload directories to retain custom data.
wget https://piwigo.org/download/dlcounter.php?code=latest -O piwigo-update.zip
unzip piwigo-update.zip -d /tmp
cp -r /tmp/piwigo/* /var/www/html/piwigo-app/
🔍 Checking for Updates
Access the Piwigo admin dashboard and navigate to the "Updates" section to check for available updates.
Leveraging Piwigo’s Unique Features
🔧 Enabling APIs
Enable Piwigo’s REST API by ensuring ws.php is accessible. Test an API call using cURL:
curl "http://<your-server-ip>/piwigo/ws.php?method=pwg.session.login&username=admin&password=your_password"
🌟 Advanced Configurations
Customize themes and plugins by uploading them to the plugins or themes directory. For example, to install a new plugin:
wget https://example.com/plugin.zip
unzip plugin.zip -d /var/www/html/piwigo-app/plugins/
sudo chown -R www-data:www-data /var/www/html/piwigo-app/plugins/
Wrapping Up
Piwigo empowers users with full control over their photo libraries, making it a versatile solution for self-hosting. By following this guide, you’ve installed, secured, and configured Piwigo for optimal performance. With its API support, plugins, and advanced configurations, Piwigo offers endless possibilities for customization and integration. Start exploring today!
