PhotoStructure for Docker Compose

These are instructions for advanced users, wanting to run PhotoStructure for Servers via Docker Compose.

Before you begin… #

Please read the first sections of the PhotoStructure for Docker installation instructions.

Make sure you understand:

Example Docker Compose setup #

Copy the following into a docker-compose.yml file in a new directory. Note that the directory name becomes the prefix for the container.

See the docker-compose documentation for more details.

Please change the lines that say CHANGE THIS LINE to values that make sense for your setup.

version: "3.7"
services:
  photostructure:
    # You can run alpha, beta, or stable builds. See
    # <https://forum.photostructure.com/t/274> for details.
    image: photostructure/server:stable
    container_name: photostructure
    
    # See https://docs.docker.com/compose/compose-file/#restart
    restart: always
    
    # PhotoStructure needs some time to close the database cleanly.
    # (It should normally only take seconds, but 2m accounts for
    # a spun-down, remote, old HDD hosting a very large library):
    stop_grace_period: 2m

    volumes:
      # /ps/library is where your PhotoStructure Library will be stored.
      # It must be readable, writable, and have sufficient free space.
      # If it is a remote volume, uncomment the PS_FORCE_LOCAL_DB_REPLICA
      # environment line below.

      - type: bind
        source: /mnt/media/PhotoStructure # < CHANGE THIS LINE
        target: /ps/library

      # /ps/tmp must be fast, local disk with many gigabytes free.
      # PhotoStructure will use this directory for file caching
      # and for storing a temporary database replica when your
      # library is on a remote volume.

      - type: bind
        source: "${HOME}/.cache/photostructure"
        target: /ps/tmp

      # /ps/config stores your "system settings"

      - type: bind
        source: "${HOME}/.config/PhotoStructure-docker"
        target: /ps/config

      # /ps/logs stores PhotoStructure log files.

      - type: bind
        source: "${HOME}/.config/PhotoStructure/logs"
        target: /ps/logs

      # Example additional directories to import into your library.
      # Add as many as you'd like, or remove one or both of these examples.

      # Set the target to /media/... or /mnt/...
      # (the name doesn't matter, as long as it is unique)

      - type: bind
        source: "/mnt/Photos backup" # < CHANGE THIS LINE
        target: /var/photos-backup

      # Here's another example directory to scan:
      # - type: bind
      #   source: /home/jamie/Pictures
      #   target: /var/home-jamie-pictures

    ports:
      - 1787:1787/tcp

    environment:
      # PhotoStructure has _tons_ of settings. See
      # <https://photostructure.com/faq/environment-variables/>

      # This tells PhotoStructure to only log errors, which is the default:
      # - "PS_LOG_LEVEL=error"
      
      # If PhotoStructure is refusing to spin up, uncomment these lines to see what's going on:
      # - "PS_LOG_LEVEL=info"
      # - "PS_LOG_STDOUT=true"
      
      # This is your local timezone. See <https://en.wikipedia.org/wiki/List_of_tz_database_time_zones>
      - "TZ=Etc/GMT" # < CHANGE THIS LINE
      
      # The userid to run PhotoStructure as:
      - "PUID=1000" # < CHANGE THIS LINE or delete this line to run as root. See below for details.
      
      # The groupid to run PhotoStructure as:
      - "PGID=1000" # < CHANGE THIS LINE or delete this line to run as root.

    #
    # The rest of this file enables automatic PhotoStructure upgrades.
    #

    labels:
      # See https://containrrr.dev/watchtower/container-selection/
      - "com.centurylinklabs.watchtower.enable=true"

  watchtower:
    image: containrrr/watchtower
    restart: always
    container_name: watchtower

    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    # Check for updates every couple hours: (3h * 60m * 60s)
    command: --interval 10800
    environment:
      - "WATCHTOWER_LABEL_ENABLE=true"

Running PhotoStructure as a non-root user #

Dockerized applications run as root by default. This results in the files in your library as being owned by root.

Running PhotoStructure as a non-root user is more secure.

As of v1.0, PhotoStructure has adopted linuxserver-style PUID/PGID (rather than Docker’s --user option). Read more about this in the forum.

The user specified by PUID/PGID needs to be able to read and write to /ps/library, /ps/tmp, /ps/config, and /ps/logs (and read from any bind mounts that contain photos and videos).

Set up your bind mounts #

Docker fails if bind mount sources don’t exist. If you used the defaults in the above config, run this:

mkdir -p "${HOME}/.cache/photostructure" \
  "${HOME}/.config/PhotoStructure-docker" \
  "${HOME}/.config/PhotoStructure/logs"

Start PhotoStructure #

cd into the directory with your docker-compose.yml, and then run:

docker-compose up --detach

Then open http://localhost:1787 in a browser to complete the installation. Firefox, Chrome, and Safari are supported.

While you wait for your import to complete, check out these getting-started tips!

Stop PhotoStructure #

cd into the directory with your docker-compose.yml, and then run:

docker-compose down

If you’re wondering why it’s taking a while to shut down, this is why.

Adding and removing volumes to import into your library #

To add or remove volumes to synchronize or import into your PhotoStructure library, just

  1. docker-compose down
  2. Edit your docker-compose.yml and add or remove new bind mounts
  3. docker-compose up

PhotoStructure will detect the new volumes automatically and import them when you restart.

How to upgrade PhotoStructure #

Upgrades are automatic if you use Watchtower (as configured in the example)!

If you disabled Watchtower, cd into the directory with your docker-compose.yml, and then run:

docker-compose down
docker-compose pull
docker-compose up --detach

Uninstalling PhotoStructure #

cd into the directory with your docker-compose.yml, and then run:

docker-compose down
docker-compose rm

As you see fit, remove your library, config, tmp and logs volumes. Take care not to delete photos and videos you want to keep! If you want to keep the originals in your library, but remove PhotoStructure’s preview images and videos, you can safely delete the $LIBRARY/.photostructure/previews directory.

See also #

Photo of Matthew

Hi! I’m Matthew, the author of PhotoStructure. I’m a dad, amateur photographer, and author of open source, adtech, fintech, and edtech software since the turn of the millennium. He/him. I am building a self-hosted, safe, and fast new home for all your photos and videos.
Your memories deserve PhotoStructure. Try it out for free!