LibrePhotos with Docker Compose

What LibrePhotos needs

Only figures LibrePhotos'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. LibrePhotos itself runs as 4 containers: librephotos-proxy, librephotos-db, librephotos-frontend, librephotos-backend.

Which hardware LibrePhotos 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 proxy, db, frontend, backend. No image for this hardware; the builder leaves the app out.

A manifest says an image exists for a CPU, not how well LibrePhotos 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 LibrePhotos 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 LibrePhotos 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: LibrePhotos
# 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"

  # ---- LibrePhotos (librephotos.example.org) ----
  # Source: https://github.com/LibrePhotos/librephotos/blob/dev/deploy/compose/docker-compose.yml (checked 2026-10-09)
  # Source: https://github.com/LibrePhotos/librephotos/blob/dev/deploy/compose/librephotos.env (checked 2026-10-09)
  # Source: https://docs.librephotos.com/docs/installation/standard-install/ (checked 2026-10-09)
  # Source: https://docs.librephotos.com/docs/user-guide/managing-users/ (checked 2026-10-09)
  # Source: https://docs.librephotos.com/docs/installation/upgrading/ (checked 2026-10-09)
  # Source: https://docs.librephotos.com/docs/installation/unified-deployment/ (checked 2026-10-09)
  # Source: https://docs.librephotos.com/docs/user-guide/internal-files/ (checked 2026-10-09)
  # Changed: Removed the documented '${httpPort:-3000}:80' port and the four container_names; Caddy reaches the bundled proxy (nginx, port 80), which sends each request on to the frontend or the backend.
  #          The env file's values are written in: tag latest for the three LibrePhotos images, dbName librephotos and dbUser docker, gunniWorkers 2 (WEB_CONCURRENCY). dbPass (AaAa1234 in the file) is a generated DB_PASS in .env.
  #          scanDirectory is ./pictures (your photos, mounted as /data) and data is ./data (database, thumbnails, logs, models) next to this file, the env file's two mandatory settings.
  #          CSRF_TRUSTED_ORIGINS and FRONTEND_BASE_URL are https://librephotos.example.org: the env file asks for the first with a custom domain (it lets the Django admin log in) and for the second whenever email is on (it builds the password-reset link).
  #          Left at the file's defaults by leaving them out: the empty SECRET_KEY (the backend generates one and keeps it in /logs/secret.key), the empty ADMIN_* variables (the setup wizard creates the admin), MAPBOX_API_KEY, the FEATURE_* switches (all on) and the TRANSCODE_* limits.
  librephotos-proxy:
    image: "reallibrephotos/librephotos-proxy:latest"
    container_name: "librephotos-proxy"
    restart: "unless-stopped"
    volumes:
      - "./librephotos/pictures:/data"
      - "./librephotos/data/protected_media:/protected_media"
    depends_on:
      - "librephotos-backend"
      - "librephotos-frontend"
    networks:
      proxy: {}
      librephotos-backend:
        aliases:
          - "proxy"
  librephotos-db:
    image: "pgautoupgrade/pgautoupgrade:latest"
    container_name: "librephotos-db"
    restart: "unless-stopped"
    environment:
      POSTGRES_USER: "docker"
      POSTGRES_PASSWORD: "${LIBREPHOTOS_DB_PASS}"
      POSTGRES_DB: "librephotos"
    volumes:
      - "./librephotos/data/db:/var/lib/postgresql"
    healthcheck:
      test: "psql -U docker -d librephotos -c \"SELECT 1;\""
      interval: "5s"
      timeout: "5s"
      retries: 5
    networks:
      librephotos-backend:
        aliases:
          - "db"
  librephotos-frontend:
    image: "reallibrephotos/librephotos-frontend:latest"
    container_name: "librephotos-frontend"
    restart: "unless-stopped"
    networks:
      librephotos-backend:
        aliases:
          - "frontend"
  librephotos-backend:
    image: "reallibrephotos/librephotos:latest"
    container_name: "librephotos-backend"
    restart: "unless-stopped"
    volumes:
      - "./librephotos/pictures:/data"
      - "./librephotos/data/protected_media:/protected_media"
      - "./librephotos/data/logs:/logs"
      - "./librephotos/data/cache:/root/.cache"
    environment:
      BACKEND_HOST: "backend"
      DB_BACKEND: "postgresql"
      DB_NAME: "librephotos"
      DB_USER: "docker"
      DB_PASS: "${LIBREPHOTOS_DB_PASS}"
      DB_HOST: "db"
      DB_PORT: "5432"
      WEB_CONCURRENCY: "2"
      CSRF_TRUSTED_ORIGINS: "https://librephotos.example.org"
      FRONTEND_BASE_URL: "https://librephotos.example.org"
      DEBUG: "0"
    depends_on:
      librephotos-db:
        condition: "service_healthy"
    networks:
      librephotos-backend:
        aliases:
          - "backend"

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"
  librephotos-backend: {}

volumes:
  caddy-data:
  caddy-config:

Caddyfile save as caddy/Caddyfile

Caddy gets and renews the HTTPS certificate for librephotos.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.

# LibrePhotos
librephotos.example.org {
	reverse_proxy librephotos-proxy:80
}

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

.env

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

# .env for LibrePhotos, from dankhost.com/app/librephotos/. Fill the blank secret before starting.
# Keep this file private (chmod 600).

# LibrePhotos
# 32 random letters and digits: the builder fills this in your browser
LIBREPHOTOS_DB_PASS=

Changes from the official file

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

• Removed the documented '${httpPort:-3000}:80' port and the four container_names; Caddy reaches the bundled proxy (nginx, port 80), which sends each request on to the frontend or the backend.
• The env file's values are written in: tag latest for the three LibrePhotos images, dbName librephotos and dbUser docker, gunniWorkers 2 (WEB_CONCURRENCY). dbPass (AaAa1234 in the file) is a generated DB_PASS in .env.
• scanDirectory is ./pictures (your photos, mounted as /data) and data is ./data (database, thumbnails, logs, models) next to this file, the env file's two mandatory settings.
• CSRF_TRUSTED_ORIGINS and FRONTEND_BASE_URL are https://librephotos.example.org: the env file asks for the first with a custom domain (it lets the Django admin log in) and for the second whenever email is on (it builds the password-reset link).
• Left at the file's defaults by leaving them out: the empty SECRET_KEY (the backend generates one and keeps it in /logs/secret.key), the empty ADMIN_* variables (the setup wizard creates the admin), MAPBOX_API_KEY, the FEATURE_* switches (all on) and the TRANSCODE_* limits.

Notes for LibrePhotos behind the proxy

• Put your photos in ./librephotos/pictures before the first start, one folder per user (the Managing Users page: scan directories of different users must not overlap, so give the admin a folder too). Uploads are written into the same folder.
• Open https://librephotos.example.org: the first-time setup wizard creates the admin account and sets the scan directory.
• The first scan is the heavy part: thumbnails, faces, captions and scene tags for every photo, one worker per CPU core by default. workerConcurrency in the env file, or the FEATURE_* switches, keep a small server usable.
• The backend downloads its machine-learning models from the internet when a feature first needs them (the Internal files page: several GB in /protected_media/data_models), so its network here has outgoing access.
• The tags are latest; the Updating section pulls whatever is newest. pgautoupgrade upgrades the database files to its PostgreSQL version on start, which is why the data folder is mounted at /var/lib/postgresql.

Back it up

LibrePhotos' Upgrading page: "Back up your database before any upgrade", with pg_dump run in the db service. Your photos are your own folder; the data folder holds the rest.

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: LibrePhotos

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)

## LibrePhotos

LibrePhotos' Upgrading page: "Back up your database before any upgrade", with pg_dump run in the db service. Your photos are your own folder; the data folder holds the rest.

What this compose mounts:
- ./librephotos/pictures (/data in librephotos-proxy)
  BACK UP: your photos and videos, and the uploads LibrePhotos writes there. The originals: back them up whatever else you do.
- ./librephotos/data/protected_media (/protected_media in librephotos-proxy)
  BACK UP: the avatars users upload, plus thumbnails, face crops, extracted motion-photo videos and the machine-learning models (several GB), which LibrePhotos can make or download again (the Internal files page).
- ./librephotos/data/db (/var/lib/postgresql in librephotos-db)
  COVERED BY THE COMMAND BELOW: PostgreSQL's data files: users, albums, faces, captions, places. The pg_dump below is the copy to keep.
- ./librephotos/pictures (/data in librephotos-backend)
  BACK UP: your photos and videos, and the uploads LibrePhotos writes there. The originals: back them up whatever else you do.
- ./librephotos/data/protected_media (/protected_media in librephotos-backend)
  BACK UP: the avatars users upload, plus thumbnails, face crops, extracted motion-photo videos and the machine-learning models (several GB), which LibrePhotos can make or download again (the Internal files page).
- ./librephotos/data/logs (/logs in librephotos-backend)
  BACK UP: the logs and secret.key, which the Internal files page says not to delete.
- ./librephotos/data/cache (/root/.cache in librephotos-backend)
  SKIP: the backend's cache folder (/root/.cache).

1. Database dump for librephotos-db:

    docker compose exec -T librephotos-db pg_dump -U docker librephotos > "$BACKUP/librephotos-db.sql"

   The Upgrading page's command, run in this file's database service.

2. Copy (LibrePhotos keeps running):
   pg_dump gives a consistent copy while LibrePhotos runs; the photo folder is only read during a scan, so copy it when no scan is running.

    tar czf "$BACKUP/librephotos-pictures.tar.gz" ./librephotos/pictures
    tar czf "$BACKUP/librephotos-data-protected_media.tar.gz" ./librephotos/data/protected_media
    tar czf "$BACKUP/librephotos-pictures.tar.gz" ./librephotos/pictures
    tar czf "$BACKUP/librephotos-data-protected_media.tar.gz" ./librephotos/data/protected_media
    tar czf "$BACKUP/librephotos-data-logs.tar.gz" ./librephotos/data/logs

Restore check:

    grep -c 'PostgreSQL database dump complete' "$BACKUP/librephotos-db.sql"   # 1 means pg_dump finished
    tar tzf "$BACKUP/librephotos-pictures.tar.gz" > /dev/null && echo OK
    tar tzf "$BACKUP/librephotos-data-protected_media.tar.gz" > /dev/null && echo OK
    tar tzf "$BACKUP/librephotos-pictures.tar.gz" > /dev/null && echo OK
    tar tzf "$BACKUP/librephotos-data-protected_media.tar.gz" > /dev/null && echo OK
    tar tzf "$BACKUP/librephotos-data-logs.tar.gz" > /dev/null && echo OK

Put a copy back (with LibrePhotos stopped):

    tar xzf "$BACKUP/librephotos-pictures.tar.gz"   # recreates ./librephotos/pictures; move the old folder aside first
    tar xzf "$BACKUP/librephotos-data-protected_media.tar.gz"   # recreates ./librephotos/data/protected_media; move the old folder aside first
    tar xzf "$BACKUP/librephotos-pictures.tar.gz"   # recreates ./librephotos/pictures; move the old folder aside first
    tar xzf "$BACKUP/librephotos-data-protected_media.tar.gz"   # recreates ./librephotos/data/protected_media; move the old folder aside first
    tar xzf "$BACKUP/librephotos-data-logs.tar.gz"   # recreates ./librephotos/data/logs; move the old folder aside first

Into a fresh install, before the backend starts against it:

    docker compose up -d librephotos-db
    docker compose exec -T librephotos-db psql -U docker librephotos < "$BACKUP/librephotos-db.sql"

Put ./librephotos/pictures and ./librephotos/data/logs back, then:

    docker compose up -d

Sources:
- LibrePhotos docs: Upgrading (back up the database with pg_dump first): https://docs.librephotos.com/docs/installation/upgrading/ (checked 2026-10-09)
- LibrePhotos docs: Internal files (/logs/secret.key, /protected_media, the models): https://docs.librephotos.com/docs/user-guide/internal-files/ (checked 2026-10-09)
- PostgreSQL docs: SQL Dump (pg_dump, restoring with psql): https://www.postgresql.org/docs/current/backup-dump.html (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 LibrePhotos as this page writes it:

What LibrePhotos's docs say about updating

LibrePhotos' Standard Docker Setup page, Updating: back up the database first (Upgrading page). The page also runs git pull in its checkout to pick up changes to docker-compose.yml; here, compare this file with a new one from the builder instead. Then:

docker compose down
docker compose pull
docker compose up -d

Source: LibrePhotos docs: Standard Docker Setup (4 GB RAM, 10 GB disk, setup wizard, updating) checked 2026-10-09; LibrePhotos docs: Upgrading (back up the database with pg_dump first) checked 2026-10-09

The steps

1. Back up first, as in Back it up above. An update can migrate LibrePhotos's data on its first start; 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 LibrePhotos start (Ctrl+C stops following the log, not the app):

   docker compose logs -f librephotos-proxy

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

LibrePhotos' Managing Users page gives three ways back in when you cannot log in; the first two work without email.

1. Set a new password with Django's management command in the backend, the page's second way. It asks for the new password twice. Source: LibrePhotos docs: Managing Users (How to change the admin password, when you can't log in) read 2026-10-09; Docker docs: docker compose exec read 2026-10-09

   docker compose exec librephotos-backend python manage.py changepassword <admin username>

2. The page's first way: ADMIN_USERNAME and ADMIN_PASSWORD on the backend reset that account's password every time the container starts. This file leaves them out; add them to the backend's environment only if you want the password kept in the file. Source: LibrePhotos docs: Managing Users (How to change the admin password, when you can't log in) read 2026-10-09
3. The third: a "Forgot your password?" link on the login page, once outgoing email is set up in Admin Area, Site settings, Email and the account has an email address. FRONTEND_BASE_URL is already set here, so the link points at your address. Source: LibrePhotos docs: Managing Users (How to change the admin password, when you can't log in) 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.

• LibrePhotos on GitHub (repository description) checked 2026-10-09 (what it does)
• LibrePhotos docs: Standard Docker Setup (4 GB RAM, 10 GB disk, setup wizard, updating) checked 2026-10-09 (hardware requirements, compose definition and proxy settings, update notes)
• LibrePhotos: deploy/compose/docker-compose.yml (proxy, db, frontend, backend) checked 2026-10-09 (compose definition and proxy settings)
• LibrePhotos: deploy/compose/librephotos.env (tag, folders, database, workers) checked 2026-10-09 (compose definition and proxy settings)
• LibrePhotos docs: Managing Users (How to change the admin password, when you can't log in) checked 2026-10-09 (compose definition and proxy settings)
• LibrePhotos docs: Upgrading (back up the database with pg_dump first) checked 2026-10-09 (compose definition and proxy settings, backup plan, update notes)
• LibrePhotos docs: Single Container Deployment (Behind a reverse proxy: CSRF_TRUSTED_ORIGINS) checked 2026-10-09 (compose definition and proxy settings)
• LibrePhotos docs: Internal files (/logs/secret.key, /protected_media, the models) checked 2026-10-09 (compose definition and proxy settings, backup plan)
• 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)
• PostgreSQL docs: SQL Dump (pg_dump, restoring with psql) 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)
• 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 LibrePhotos to the builder All one hundred apps