Skip to content

PiGallery2 Docker Installation

Docker with docker-compose is the official and recommended way of installing and running PiGallery2.

You can use docker to run PiGallery2. See all available docker tags here. available tags:

  • v* (stable): built from the release with the same version name.
  • latest (stable): same as the latest v*, built with debian trixie.
  • edge : built from the current state of master. This might break from time to time.

The latest release's images (latest, latest-alpine and its version tags) are rebuilt every week on fresh base images, so OS and Node security fixes arrive without a new release. The app inside stays the same; pull the image again to get them.

Note: Some changes may require database reset or config changes, see #317 (If you want to reduce the frequency of those, use stable builds (latest)

We support the amd64 and arm64v8 architectures. 32-bit ARM (arm32v7) images are no longer built, as Node.js dropped official support for it; use a 64-bit OS on your Raspberry Pi to run the arm64v8 image (see).

It contains all necessary dependencies, auto-restarts on reboot, supports HTTPS, and is easy to upgrade.

Official installation guide here, but this will most likely do the trick on a Raspberry Pi (source):

curl -sSL https://get.docker.com | sh

I. Docker Compose

It is recommended to use docker-compose to run PiGallery2.

I.0 Install Docker Compose

Official installation guide here, or try this (source): Install dependencies:

sudo apt-get install libffi-dev libssl-dev
sudo apt-get install -y python3 python3-pip
sudo apt-get remove python-configparser
Install docker-compose:
sudo pip3 install docker-compose
Check success with docker-compose --version.

I.1 Get docker-compose.yml file

Download docker-compose/default/docker-compose.yml and docker-compose/default/nginx.conf.

Edit docker-compose.yml at the # CHANGE ME lines to point the volumes to the right image and tmp directories. Edit nginx.conf at the # CHANGE ME lines by replacing yourdomain.com with your domain address.

Note: Do not change the image and tmp paths in the config.json or UI; only use Docker volume settings. See here and here.

Note: We are using nginx as reverse proxy to handle https and do proper HTTP queuing, gzipping, rate limiting, etc. Full nginx-based docker-compose tutorial here.

Note 2: You can skip nginx, by using docker-compose/pigallery2-only/docker-compose.yml.

Warning: PiGallery2 does not limit the request rate itself: nothing slows down password guessing on the login page or on a password protected sharing link, and nothing stops a client from flooding the server with requests. The nginx.conf above does both (see its limit_req lines). If you skip nginx or use another reverse proxy, set up rate limiting there before making the gallery reachable from the internet.

Note 3: To log the real client IP of failed logins (e.g. for fail2ban) instead of the IP of the nginx container, set Server.trustProxy (Settings, "Under the hood" mode) to uniquelocal. See the Fail2Ban guide.

I.1.a Get SSL Certificate with Certbot

Install Certbot: https://certbot.eff.org/. (Certbot uses letsencrypt to get free certificate). Then get your certificate:

certbot certonly --standalone -d yourdomain.com
Note: if you get an error like Problem binding to port 80: Could not bind to IPv4 or IPv6. then a service is running on port 80. If it's a fresh raspberry install, it's potentially nginx, you can disable it with sudo systemctl disable nginx details here.

I.1.b Start Docker Compose

In the folder that has docker-compose.yml:

docker-compose up -d
-d runs it as a daemon. Remove it, so you will see the logs.

After the containers are up and running, go to yourdomain.com and log in with user: admin pass: admin and set up the page in the settings. Full list of configuration options are available at the MANPAGE.md.

Note: docker-compose.yml contains restart:always, so the containers will be automatically started after reboot (read more here).

I.2 Upgrade to newer version

docker-compose pull # get new version
docker-compose down # stop running container
docker system prune # from time to time its nice to clean up docker
docker-compose up -d # start containers

II. Without Docker Compose

If you want to run the container by yourself, here you go:

docker run \
   -p 80:80 \
   -e NODE_ENV=production \
   -v <path to your config file folder>:/app/data/config \
   -v <path to your db file folder>:/app/data/db \
   -v <path to your images folder>:/app/data/images \
   -v <path to your temp folder>:/app/data/tmp \
   bpatrik/pigallery2:latest

After the container is up and running, go to http://localhost and log in with user: admin pass: admin and set up the page in the settings.

Note: even with memory db, pigallery2 creates a db file for storing user credentials (if enabled), so mounting (with -v) the /app/data/db folder is recommended.

Note 2: Do not change the image and tmp paths in the config.json or UI; only use Docker volume settings. See here and here.

II.a before v1.7.0

There was a breaking change in Docker files after v1.7.0. Use this to run earlier versions:

docker run \
   -p 80:80 \
   -e NODE_ENV=production \
   -v <path to your config file folder>/config.json:/pigallery2-release/config.json \
   -v <path to your db file folder>/sqlite.db:/pigallery2-release/sqlite.db \
   -v <path to your images folder>:/pigallery2-release/demo/images \
   -v <path to your temp folder>:/pigallery2-release/demo/TEMP \
   bpatrik/pigallery2:1.7.0-stretch
Make sure that a file at <path to your config file folder>/config.json and sqlite.db files exists before running it.

You do not need the <path to your db file folder>/sqlite.db line if you don't use the sqlite database.

Build the Docker image on your own

You can clone the repository and build the image, or you can just use the 'self-contained' Dockerfile: debian-trixie/selfcontained/Dockerfile Note: 'self-contained' is not well tested, bug fix PRs are welcome.

Older browsers

The frontend supports the browsers that Angular supports. An older browser (e.g. Safari on iOS 15) shows "This browser is too old" instead of the gallery. If you need such a browser, you can build the image for it yourself with the 'self-contained' Dockerfile. Its BROWSERSLIST build argument sets the browsers that the frontend is built for:

curl -O https://raw.githubusercontent.com/bpatrik/pigallery2/master/docker/debian-trixie/selfcontained/Dockerfile
docker build --build-arg BROWSERSLIST="defaults, iOS >= 15.4" -t pigallery2-old-browsers .

Then use pigallery2-old-browsers instead of bpatrik/pigallery2:latest in your docker-compose.yml or docker run command. This is not supported: it builds the latest development version (master), only changes the JavaScript syntax (missing browser APIs are not added), and a later version may need a newer browser again. iOS 15.4 is the oldest Safari that works this way; earlier versions lack APIs that the app uses.

Contributing to Docker

See the Docker Contribution Guide.