# Piwigo

> Photo gallery software for the web.

- Category: Storage & Backup
- Difficulty: intermediate
- Components: piwigo, mariadb
- Tags: piwigo, photos, gallery, web
- Source: https://docker.recipes/storage/piwigo

## Overview

Piwigo is a mature, open-source photo gallery software designed to organize and share digital photo collections through a web interface. Originally launched in 2002 as PhpWebGallery, Piwigo has evolved into a feature-rich platform offering advanced photo management capabilities including metadata handling, batch operations, user permissions, and extensive customization through themes and plugins. The software excels at handling large photo collections with automatic thumbnail generation, EXIF data extraction, and sophisticated album organization.

This Docker stack combines Piwigo with MariaDB to create a robust photo gallery solution that handles both the web application layer and database persistence. MariaDB serves as the backend database storing album structures, user accounts, photo metadata, comments, and configuration settings, while Piwigo manages the web interface, image processing, and file organization. The LinuxServer.io Piwigo image includes PHP-FMP and nginx, providing optimized performance for photo serving and thumbnail generation.

Photographers, families, organizations, and businesses managing substantial photo collections will benefit from this deployment. The combination offers professional-grade photo organization with features like batch metadata editing, watermarking, GPS coordinate mapping, and multi-user collaboration, making it suitable for everything from personal family archives to professional photography studios and corporate media libraries.

## Features

- Automatic EXIF data extraction and display including camera settings, GPS coordinates, and shooting parameters
- Batch photo upload via web interface, FTP, or directory synchronization with automatic thumbnail generation
- Advanced user permission system with album-specific access controls and guest browsing options
- Plugin ecosystem with 300+ extensions including Lightroom synchronization, slideshow generators, and social sharing
- MariaDB Aria storage engine optimization for improved photo metadata indexing and search performance
- Watermark application with customizable positioning, transparency, and batch processing capabilities
- Mobile-responsive interface with touch-friendly navigation and optimized image loading
- Advanced search functionality across EXIF data, keywords, albums, and custom metadata fields

## Use cases

- Professional photography studios organizing client shoots with album-specific access permissions
- Family photo archives with multi-generational access and privacy controls for different album collections
- Real estate agencies managing property photo galleries with location-based organization and client access
- Educational institutions creating visual course materials and student project galleries
- Corporate media libraries for marketing teams managing brand assets and campaign photography
- Event photography businesses providing client galleries with download and sharing capabilities
- Historical societies digitizing and organizing archival photograph collections with metadata preservation

## Prerequisites

- Minimum 1GB RAM for MariaDB database operations and photo thumbnail generation
- Available port 80 for web interface access or alternative port configuration
- Docker environment variables DB_ROOT_PASSWORD and DB_PASSWORD configured in .env file
- Sufficient storage space for original photos, generated thumbnails, and database growth
- Basic understanding of photo file formats and web gallery management concepts
- Network access planning for multi-user environments and potential reverse proxy integration

## docker-compose.yml

```yaml
services:
  piwigo:
    image: lscr.io/linuxserver/piwigo:latest
    container_name: piwigo
    restart: unless-stopped
    environment:
      PUID: 1000
      PGID: 1000
      TZ: UTC
    volumes:
      - piwigo_config:/config
      - piwigo_gallery:/gallery
    ports:
      - "80:80"
    depends_on:
      - mariadb
    networks:
      - piwigo

  mariadb:
    image: mariadb:10.11
    container_name: piwigo-mariadb
    restart: unless-stopped
    environment:
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MARIADB_DATABASE: piwigo
      MARIADB_USER: piwigo
      MARIADB_PASSWORD: ${DB_PASSWORD}
    volumes:
      - mariadb_data:/var/lib/mysql
    networks:
      - piwigo

volumes:
  piwigo_config:
  piwigo_gallery:
  mariadb_data:

networks:
  piwigo:
    driver: bridge
```

## .env

```bash
DB_ROOT_PASSWORD=rootpassword
DB_PASSWORD=piwigo
```

## Usage notes

- Docs: https://piwigo.org/doc/
- Access at http://localhost - follow setup wizard (DB host: mariadb)
- Rich plugin ecosystem: 300+ plugins available
- Batch upload via FTP or web - Piwigo scans /gallery
- Multi-user with permissions, guest access, privacy settings
- Desktop sync: digiKam, Lightroom plugins available

## Troubleshooting

- Database connection failed during setup wizard: Verify mariadb container is running and use 'mariadb' as database host, not 'localhost'
- Photos not appearing after FTP upload: Check file permissions on /gallery volume and trigger manual synchronization through Piwigo admin panel
- Thumbnail generation fails for large images: Increase PHP memory_limit in Piwigo container or resize source images before upload
- MariaDB container crashes with 'insufficient memory': Reduce innodb_buffer_pool_size or increase available container memory allocation
- Plugin installation errors: Ensure Piwigo version compatibility and check plugin dependencies in the administration interface
- Slow gallery loading with large albums: Enable MariaDB query cache and consider implementing album pagination in Piwigo settings

