Piwigo Docker Deployment: The Veteran Open-Source Family Gallery

Piwigo has been maintained since 2002 and is the veteran of open-source galleries. It does not sell itself on AI; it sells solid album management, group permissions and 200+ plugins and themes. If your family is "one gallery, many members, each sees their own part", Piwigo's permission model is finer than most new projects.

1. Image and ports

Item	Value
Application image	piwigo/piwigo:latest (Docker Hub)
Database	docker.io/library/mariadb:lts
Web port	Container 80, host 8080 by default
Data directories	./piwigo-data/piwigo, ./piwigo-data/mysql

2. Download the official Compose file and .env

mkdir -p /opt/piwigo && cd /opt/piwigo
curl -O https://raw.githubusercontent.com/Piwigo/piwigo-docker/refs/heads/main/compose.yaml
mv compose.yaml docker-compose.yml

Create .env (random passwords, not the sample values):

piwigo_port=8080
db_user_password=replace-with-a-random-strong-password
timezone=Asia/Shanghai
PIWIGO_UID=1000
PIWIGO_GID=1000

The Compose file is straightforward:

services:
  piwigo-main:
    image: piwigo/piwigo:latest
    restart: always
    environment:
      - TZ=${timezone}
      - PIWIGO_UID=${PIWIGO_UID}
      - PIWIGO_GID=${PIWIGO_GID}
    ports:
      - ${piwigo_port}:80
    depends_on:
      - piwigo-db
    volumes:
      - ./piwigo-data/piwigo:/var/www/html/piwigo/
      - ./piwigo-data/scripts:/usr/local/bin/scripts/

  piwigo-db:
    image: docker.io/library/mariadb:lts
    restart: always
    environment:
      - MARIADB_RANDOM_ROOT_PASSWORD=true
      - MARIADB_USER=piwigodb_user
      - MARIADB_DATABASE=piwigodb
      - MARIADB_PASSWORD=${db_user_password}
      - TZ=${timezone}
    volumes:
      - ./piwigo-data/mysql:/var/lib/mysql

3. Start and run the installer

docker compose up -d
docker compose logs -f piwigo-main

Open http://SERVER_IP:8080. Piwigo detects that it is not installed and redirects to the installer. Use these database values:

Field	Value
Host	piwigo-db:3306
User	piwigodb_user
Password	db_user_password from .env
Database name	piwigodb
Table prefix	piwigo_

Then set the administrator account, password and email and click Install. Sign in as the administrator to reach the admin panel.

4. Create albums and permissions

1. Albums → Add album, and create categories such as "Spring Festival 2026" or "Kids growing up".
2. Upload photos through the web UI, or drop files on the server and use Tools → Synchronise for a batch import.
3. Users → Add user to create family accounts, then add them to groups.
4. Albums → Manage → Permissions to grant per-group access: who can view, who can upload.
5. Install a theme (for example Bootstrap Darkroom) and plugins for watermarks or maps as needed.

5. Reverse proxy and HTTPS

server {
    listen 443 ssl http2;
    server_name photos.example.com;
    ssl_certificate     /etc/letsencrypt/live/photos.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/photos.example.com/privkey.pem;

    client_max_body_size 2000M;

    location / {
        proxy_pass http://127.0.0.1:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

If you mount it under a sub-path such as /gallery, add proxy_set_header X-Forwarded-Prefix /gallery;. The official docs have complete examples.

6. Backup and upgrades

• Back up piwigo-data/piwigo (application and uploads) and piwigo-data/mysql (database).
• Upgrade with a backup first, then docker compose pull && docker compose up -d; follow the official Docker update notes for major versions.
• With a large library, put ./piwigo-data/piwigo/_data on a dedicated disk.

7. Troubleshooting

Large uploads fail? Check PHP's upload_max_filesize and post_max_size as well as the proxy client_max_body_size.

Another interface language? After installation, enable it under Administration → Languages and set it as default.

Is there automatic phone backup? Piwigo has no official auto-backup app. Use FTP sync, web upload or a third-party client; choose Immich if automatic backup is the priority.

8. Wrap-up

Piwigo's strength is management: members, albums, permissions and plugins are all adjustable. It is closer to an internal family photo portal than a cloud backup drive for your phone.

Related: Lychee tutorial · 2026 self-hosted album comparison