Photoview with Docker Compose

What Photoview needs

Only figures Photoview's own documentation publishes, each linked to the page it is on. Where the project gives no number, this page does not invent one.

On top of this, Caddy (the reverse proxy in the file) is a single small container. Photoview itself runs as 3 containers: photoview-prepare, photoview, photoview-mariadb.

Which hardware Photoview has images for

Read from each image's manifest list in its registry (anonymous, read-only) when this page was built. An app counts for a CPU only if every one of its images lists it.

• x86-64 PC or NAS (linux/amd64): every image has a build.
• Raspberry Pi 4/5, 64-bit OS (linux/arm64): every image has a build.
• Raspberry Pi 3 or Zero 2 W, 32-bit OS (linux/arm/v7): no image for photoview-prepare, photoview, mariadb. No image for this hardware; the builder leaves the app out.

A manifest says an image exists for a CPU, not how well Photoview runs on it: a build for arm64 or arm/v7 can still be too slow or need more memory than the board has. The RAM and disk Photoview publishes are in the table above and, for a whole set of apps against a Raspberry Pi, on Will it run on my machine?. A tag like latest can move to a new digest after the date checked.

docker-compose.yml

This is exactly what the builder writes for Photoview alone on example.org: the official definition with its published ports removed and Caddy added in front. Every ${VARIABLE} is defined in the .env below.

# docker-compose.yml built at dankhost.com for: Photoview
# Each app block is its official compose definition. Only the names were prefixed with
# the app slug (services, containers, volumes, bind folders, .env variables) so any set of
# apps can share one file; other differences are listed under "Changed:" in each block.
# Only Caddy publishes ports. Secrets live in .env next to this file.

services:
  # ---- Caddy: the one reverse proxy, HTTPS certificates from Let's Encrypt ----
  # Source: https://caddyserver.com/docs/running (checked 2026-09-23)
  # Source: https://github.com/dani-garcia/vaultwarden/wiki/Using-Docker-Compose (checked 2026-09-23)
  # Caddyfile goes in ./caddy/Caddyfile. Fixed address 172.30.0.2 so apps can trust it exactly.
  caddy:
    image: "caddy:2"
    container_name: "caddy"
    restart: "unless-stopped"
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - "./caddy:/etc/caddy"
      - "caddy-data:/data"
      - "caddy-config:/config"
    networks:
      proxy:
        ipv4_address: "172.30.0.2"

  # ---- Photoview (photoview.example.org) ----
  # Source: https://github.com/photoview/photoview/blob/master/docker-compose%20example/docker-compose.minimal.example.yml (checked 2026-10-09)
  # Source: https://github.com/photoview/photoview/blob/master/docker-compose%20example/example.env (checked 2026-10-09)
  # Source: https://photoview.github.io/en/docs/installation-docker/ (checked 2026-10-09)
  # Source: https://photoview.github.io/en/docs/getting-started/ (checked 2026-10-09)
  # Source: https://photoview.github.io/en/docs/faq/ (checked 2026-10-09)
  # Source: https://photoview.github.io/en/docs/installation-reverse-proxies/ (checked 2026-10-09)
  # Changed: Removed the documented '8000:80' port, the hostnames and the container_names; Caddy reaches photoview:80 on the proxy network. The database keeps its documented address photoview-mariadb (its service name here).
  #          HOST_PHOTOVIEW_LOCATION is this folder (./storage for the cache, ./database/mariadb for the database) and HOST_PHOTOVIEW_MEDIA_ROOT is ./photos, mounted read-only as in the file.
  #          The MariaDB passwords, photosecret and superphotosecret in example.env, are generated in .env (letters and digits only, so PHOTOVIEW_MYSQL_URL needs no URL-encoding). The file's values PHOTOVIEW_DATABASE_DRIVER=mysql, MARIADB_DATABASE and MARIADB_USER photoview are written in.
  #          photoview-prepare loses network_mode: "none": it joins this app's internal network instead, which has no route to the internet either. The file's ui_net and internal api_db_net are the proxy network and that internal network.
  #          MAPBOX_TOKEN, empty unless you make one, is left out; add it to photoview's environment for the map and the Places page.
  # ELEVATED ACCESS (cap_add CHOWN, user root): kept from the documented file: this one-shot container starts as root with only the CHOWN capability, gives the media cache folder to the photoview user, and exits before Photoview starts ("Makes sure that the media cache folder is created with the correct permissions").
  # ELEVATED ACCESS (security_opt seccomp:unconfined, apparmor:unconfined): kept from the documented file, where it is marked "Security options for some restricted systems": it turns off the default seccomp and AppArmor profiles for the container. If Photoview starts without it on your host, you can delete the two lines.
  # ELEVATED ACCESS (security_opt seccomp:unconfined, apparmor:unconfined): kept from the documented file, which links a MariaDB image issue about restricted systems: it turns off the default seccomp and AppArmor profiles for the database container. If MariaDB starts without it on your host, you can delete the two lines.
  photoview-prepare:
    image: "photoview/photoview:2"
    container_name: "photoview-prepare"
    user: "root"
    entrypoint: []
    command: "/bin/bash -c \"sleep 1 && chown -R photoview:photoview /home/photoview/media-cache\""
    cap_add:
      - "CHOWN"
    volumes:
      - "/etc/localtime:/etc/localtime:ro"
      - "/etc/timezone:/etc/timezone:ro"
      - "./photoview/storage:/home/photoview/media-cache"
    networks:
      photoview-backend: {}
  photoview:
    image: "photoview/photoview:2"
    container_name: "photoview"
    restart: "unless-stopped"
    stop_grace_period: "10s"
    depends_on:
      photoview-prepare:
        condition: "service_completed_successfully"
      photoview-mariadb:
        condition: "service_healthy"
    security_opt:
      - "seccomp:unconfined"
      - "apparmor:unconfined"
    environment:
      PHOTOVIEW_DATABASE_DRIVER: "mysql"
      PHOTOVIEW_MYSQL_URL: "photoview:${PHOTOVIEW_MARIADB_PASSWORD}@tcp(photoview-mariadb)/photoview"
      PHOTOVIEW_LISTEN_IP: "0.0.0.0"
    volumes:
      - "/etc/localtime:/etc/localtime:ro"
      - "/etc/timezone:/etc/timezone:ro"
      - "./photoview/storage:/home/photoview/media-cache"
      - "./photoview/photos:/photos:ro"
    networks:
      proxy: {}
      photoview-backend: {}
  photoview-mariadb:
    image: "mariadb:lts"
    container_name: "photoview-mariadb"
    restart: "unless-stopped"
    stop_grace_period: "5s"
    command: "mariadbd --innodb-buffer-pool-size=512M --transaction-isolation=READ-COMMITTED --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci --max-connections=512 --innodb-rollback-on-timeout=OFF --innodb-lock-wait-timeout=120"
    security_opt:
      - "seccomp:unconfined"
      - "apparmor:unconfined"
    environment:
      MARIADB_AUTO_UPGRADE: "1"
      MARIADB_DATABASE: "photoview"
      MARIADB_USER: "photoview"
      MARIADB_PASSWORD: "${PHOTOVIEW_MARIADB_PASSWORD}"
      MARIADB_ROOT_PASSWORD: "${PHOTOVIEW_MARIADB_ROOT_PASSWORD}"
    volumes:
      - "/etc/localtime:/etc/localtime:ro"
      - "/etc/timezone:/etc/timezone:ro"
      - "./photoview/database/mariadb:/var/lib/mysql"
    healthcheck:
      test: "healthcheck.sh --connect --innodb_initialized"
      interval: "1m"
      timeout: "5s"
      retries: 5
      start_period: "3m"
    networks:
      photoview-backend:
        aliases:
          - "mariadb"

networks:
  # Pinned so the trusted-proxy address given to each app (172.30.0.2) is exact.
  # If "docker compose up" reports "Pool overlaps", change 172.30.0 here, in Caddy's
  # ipv4_address and in every trusted-proxy value to a free 172.x.0 range.
  proxy:
    ipam:
      config:
        - subnet: "172.30.0.0/24"
          ip_range: "172.30.0.128/25"
          gateway: "172.30.0.1"
  photoview-backend:
    internal: true

volumes:
  caddy-data:
  caddy-config:

Caddyfile save as caddy/Caddyfile

Caddy gets and renews the HTTPS certificate for photoview.example.org by itself once the DNS record points at your server and ports 80 and 443 reach it.

# Caddyfile built at dankhost.com. Save it as ./caddy/Caddyfile next to docker-compose.yml.
# Caddy gets and renews a Let's Encrypt certificate for each name below by itself,
# once the DNS records point at this server and ports 80 and 443 reach it.

# Photoview
photoview.example.org {
	reverse_proxy photoview:80
}

Already running nginx, Nginx Proxy Manager, Caddy or Traefik? The reverse-proxy settings Photoview needs, for all four, each cited to Photoview's own docs.

.env

The secrets are left blank here on purpose: a password printed on a public page is the same for everyone who copies it. The builder fills them with random letters and digits made in your browser.

# .env for Photoview, from dankhost.com/app/photoview/. Fill the blank secrets before starting.
# Keep this file private (chmod 600).

# Photoview
# 32 random letters and digits: the builder fills this in your browser
PHOTOVIEW_MARIADB_PASSWORD=
# 32 random letters and digits: the builder fills this in your browser
PHOTOVIEW_MARIADB_ROOT_PASSWORD=

What Photoview needs beyond the proxy

Photoview asks for more than an ordinary container. The compose file keeps what the project documents and labels each item with an # ELEVATED ACCESS comment; /check/ flags them too, as it would in any file.

• cap_add CHOWN, user root: kept from the documented file: this one-shot container starts as root with only the CHOWN capability, gives the media cache folder to the photoview user, and exits before Photoview starts ("Makes sure that the media cache folder is created with the correct permissions").
• security_opt seccomp:unconfined, apparmor:unconfined: kept from the documented file, where it is marked "Security options for some restricted systems": it turns off the default seccomp and AppArmor profiles for the container. If Photoview starts without it on your host, you can delete the two lines.
• security_opt seccomp:unconfined, apparmor:unconfined: kept from the documented file, which links a MariaDB image issue about restricted systems: it turns off the default seccomp and AppArmor profiles for the database container. If MariaDB starts without it on your host, you can delete the two lines.

Changes from the official file

Besides prefixing every service, container, volume, folder and variable with photoview (so any set of apps can share one file), these are all the differences from what the project documents:

• Removed the documented '8000:80' port, the hostnames and the container_names; Caddy reaches photoview:80 on the proxy network. The database keeps its documented address photoview-mariadb (its service name here).
• HOST_PHOTOVIEW_LOCATION is this folder (./storage for the cache, ./database/mariadb for the database) and HOST_PHOTOVIEW_MEDIA_ROOT is ./photos, mounted read-only as in the file.
• The MariaDB passwords, photosecret and superphotosecret in example.env, are generated in .env (letters and digits only, so PHOTOVIEW_MYSQL_URL needs no URL-encoding). The file's values PHOTOVIEW_DATABASE_DRIVER=mysql, MARIADB_DATABASE and MARIADB_USER photoview are written in.
• photoview-prepare loses network_mode: "none": it joins this app's internal network instead, which has no route to the internet either. The file's ui_net and internal api_db_net are the proxy network and that internal network.
• MAPBOX_TOKEN, empty unless you make one, is left out; add it to photoview's environment for the map and the Places page.

Notes for Photoview behind the proxy

• Put your photos in ./photoview/photos (or point the ./photos mount at the folder that holds them). Then open https://photoview.example.org: the first page creates the admin user and asks for the photo path, which is /photos, the path inside the container.
• The host must have /etc/localtime and /etc/timezone (Debian and Ubuntu do). On a host without /etc/timezone, delete those two lines, or Docker creates an empty folder in its place.
• If the scanner stops with "signal: killed", the FAQ says the server ran out of resources: lower the concurrent workers in Settings to 1.
• The tag is 2, which the docs recommend: newer 2.x releases arrive with docker compose pull, a new major version does not.

Back it up

Photoview publishes no backup procedure for this file. The database holds users, albums, faces and shares; the cache only things it can make again; the photos are yours and mounted read-only.

Below is the BACKUP.md the builder writes next to the compose file above: which of its folders and volumes hold data, the dump command the project documents, rewritten for this file's service names, what to copy with which container stopped, and a restore check. Pick more apps in the builder and it covers them all in one file.

# BACKUP.md built at dankhost.com for: Photoview

What to copy from the docker-compose.yml built with this file, the database dump each project documents (rewritten for the service names in that file), what to copy with which container stopped, and how to check the result. Run every command in the folder that holds docker-compose.yml.

The folders are owned by the containers' users: put sudo in front of tar if it says "Permission denied". Named volumes live under /var/lib/docker/volumes, not next to the compose file, so they are copied through a throwaway ubuntu container (Docker's documented --volumes-from method). tar makes a full copy each run; for large folders an incremental tool (restic, borg, rsync) saves time and space.

Never run "docker compose down -v" on this file: it deletes the named volumes of every app in it.

## Before you start

    BACKUP=/mnt/backup/selfhost   # change this: a disk or machine other than this server's system disk
    mkdir -p "$BACKUP"

## Every time: the three stack files

    tar czf "$BACKUP/stack-files.tar.gz" docker-compose.yml .env caddy

.env holds the database passwords and secret keys the apps were set up with; keep this archive as private as the data.

## Caddy (the reverse proxy)

Caddy's docs: 'The data directory must not be treated as a cache.' It holds the TLS certificates and their private keys; without it Caddy has to ask Let's Encrypt for every certificate again.

- caddy-data (named volume, /data in caddy)
  BACK UP: TLS certificates, private keys, OCSP staples.
- caddy-config (named volume, /config in caddy)
  SKIP: the last active configuration, kept for 'caddy run --resume', which this setup does not use: it starts from the Caddyfile.
- ./caddy (/etc/caddy in caddy)
  IN stack-files.tar.gz: the Caddyfile, copied with the stack files above.

Copy (Caddy keeps serving while you copy):

    docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu tar cvf /backup/caddy-data.tar /data

Restore check:

    tar tf "$BACKUP/caddy-data.tar" > /dev/null && echo OK
    docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu bash -c "cd /data && tar xvf /backup/caddy-data.tar --strip 1"

Sources:
- Caddy docs: Conventions, Data directory: https://caddyserver.com/docs/conventions#data-directory (checked 2026-09-24)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-09-24)

## Photoview

Photoview publishes no backup procedure for this file. The database holds users, albums, faces and shares; the cache only things it can make again; the photos are yours and mounted read-only.

What this compose mounts:
- ./photoview/storage (/home/photoview/media-cache in photoview-prepare)
  SKIP: the media cache: thumbnails and converted videos. The FAQ: if you delete it, "it will be recreated".
- ./photoview/storage (/home/photoview/media-cache in photoview)
  SKIP: the media cache: thumbnails and converted videos. The FAQ: if you delete it, "it will be recreated".
- ./photoview/photos (/photos in photoview)
  BACK UP: your photos and videos. Photoview only reads them; back them up as the originals they are.
- ./photoview/database/mariadb (/var/lib/mysql in photoview-mariadb)
  COVERED BY THE COMMAND BELOW: MariaDB's data files: users, albums, faces, share links. The dump below is the copy to keep.

1. Database dump for photoview-mariadb:

    docker compose exec -T photoview-mariadb sh -c 'mariadb-dump --user="$MARIADB_USER" --password="$MARIADB_PASSWORD" --single-transaction --databases photoview' > "$BACKUP/photoview-mariadb.sql"

   MariaDB's own dump tool, run inside the database container, which already has the user and password in its environment.

2. Copy (Photoview keeps running):
   mariadb-dump --single-transaction takes a consistent copy while Photoview runs.

    tar czf "$BACKUP/photoview-photos.tar.gz" ./photoview/photos

Restore check:

    grep -c 'Dump completed' "$BACKUP/photoview-mariadb.sql"   # 1 means mariadb-dump finished
    tar tzf "$BACKUP/photoview-photos.tar.gz" > /dev/null && echo OK

Put a copy back (with Photoview stopped):

    tar xzf "$BACKUP/photoview-photos.tar.gz"   # recreates ./photoview/photos; move the old folder aside first

Into a fresh install, before Photoview starts against it:

    docker compose up -d photoview-mariadb
    docker compose exec -T photoview-mariadb sh -c 'mariadb --user="$MARIADB_USER" --password="$MARIADB_PASSWORD"' < "$BACKUP/photoview-mariadb.sql"
    docker compose up -d

Sources:
- Photoview docs: FAQ (I forgot the password to the admin user): https://photoview.github.io/en/docs/faq/ (checked 2026-10-09)
- MariaDB docs: mariadb-dump: https://mariadb.com/docs/server/clients-and-utilities/backup-restore-and-import-clients/mariadb-dump (checked 2026-10-09)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-10-09)

Update it

What docker compose pull does depends only on how each image line in the compose file above is tagged. For Photoview as this page writes it:

What Photoview's docs say about updating

Photoview's Setup with Docker page, Updating (written with docker-compose; the same commands with docker compose):

docker compose pull
docker compose up -d

Source: Photoview docs: Setup with Docker (port 80, media mounts read-only, tags, updating) checked 2026-10-09

The steps

1. Back up first, as in Back it up above. An update can migrate Photoview's data on its first start and its database with it; the copy is the way back.
2. Download the new images. Running containers are not touched yet:

   docker compose pull

3. Recreate the containers whose image changed. Volumes and bind-mounted folders stay as they are:

   docker compose up -d

4. Watch Photoview start (Ctrl+C stops following the log, not the app):

   docker compose logs -f photoview

5. Optional: remove the old images the pull left without a tag. This covers every stack on the machine, not only this one:

   docker image prune

Docker's reference for these commands: Docker docs: docker compose pull checked 2026-09-30; Docker docs: docker compose up (recreates changed containers, keeps volumes) checked 2026-09-30; Docker docs: docker image prune checked 2026-09-30

Locked out? Reset the admin password

Photoview's FAQ: "you will have to update the password manually in the database", as a bcrypt hash.

1. Make a bcrypt hash of the new password. The FAQ points to an online generator (bcrypt-generator.com); a bcrypt tool on your own computer does the same without sending the password anywhere. Source: Photoview docs: FAQ (I forgot the password to the admin user) read 2026-10-09
2. Open the database, the FAQ's command with this file's service name. The mariadb:lts image calls its client mariadb, and -p asks for PHOTOVIEW_MARIADB_PASSWORD from .env. Source: Photoview docs: FAQ (I forgot the password to the admin user) read 2026-10-09; Docker Hub: official mariadb image (the client is called mariadb) read 2026-10-09; Docker docs: docker compose exec read 2026-10-09

   docker compose exec -it photoview-mariadb mariadb -u photoview -p photoview

3. SELECT * FROM users; lists the accounts. Set the new hash on the admin, with the FAQ's query: Source: Photoview docs: FAQ (I forgot the password to the admin user) read 2026-10-09

   UPDATE users SET password='<bcrypt hash>' WHERE username='<admin username>';

4. Type exit and sign in with the new password. Source: Photoview docs: FAQ (I forgot the password to the admin user) read 2026-10-09

Run the commands in the folder that holds docker-compose.yml. Words in angle brackets are placeholders: replace them, brackets included. docker compose exec runs the command in the container that is already running: Docker docs: docker compose exec read 2026-10-09

Sources

Every page below was fetched on the date shown.

• Photoview on GitHub (repository description) checked 2026-10-09 (what it does)
• Photoview: docker-compose.minimal.example.yml (photoview-prepare, photoview, mariadb) checked 2026-10-09 (compose definition and proxy settings)
• Photoview: example.env (folders, database driver, MariaDB settings) checked 2026-10-09 (compose definition and proxy settings)
• Photoview docs: Setup with Docker (port 80, media mounts read-only, tags, updating) checked 2026-10-09 (compose definition and proxy settings, update notes)
• Photoview docs: Getting started (initial setup wizard: admin user and photo path) checked 2026-10-09 (compose definition and proxy settings)
• Photoview docs: FAQ (I forgot the password to the admin user) checked 2026-10-09 (compose definition and proxy settings, backup plan)
• Photoview docs: Reverse Proxy (Traefik labels, Caddy, Apache) checked 2026-10-09 (compose definition and proxy settings)
• Caddy docs: Keep Caddy running (Docker Compose section) checked 2026-09-23 (Caddy)
• Vaultwarden wiki: Caddy with HTTP challenge (uses the caddy:2 image) checked 2026-09-23 (Caddy)
• MariaDB docs: mariadb-dump checked 2026-10-09 (backup plan)
• Docker docs: Volumes, Back up, restore, or migrate data volumes checked 2026-10-09 (backup plan)
• Caddy docs: Conventions, Data directory checked 2026-09-24 (backup plan)
• MariaDB Docker Official Image: MARIADB_AUTO_UPGRADE checked 2026-09-30 (database upgrade)
• Docker docs: docker compose pull checked 2026-09-30 (update steps)
• Docker docs: docker compose up (recreates changed containers, keeps volumes) checked 2026-09-30 (update steps)
• Docker docs: docker image prune checked 2026-09-30 (update steps)

Add Photoview to the builder All one hundred apps