PhotoStructure for Docker

December 3, 2019

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

Please make sure you’ve read the pros and cons of both approaches before continuing.

Attention, version 0.7 users: these instructions have changed. We’re no longer using docker compose, nor the start-docker.sh script.

Step 1: Install Docker #

Follow these instructions for docker. If you’re on Ubuntu, follow these steps.

Step 2: Setup and run #

This example sets up PhotoStructure to scan both a mounted external harddrive at /mnt/Photos backup and all files in $HOME/Pictures.

# This is where your PhotoStructure Library will be stored.
# It must be readable, writable, and have sufficient free space.
LIBRARY="$HOME/PhotoStructure"

# This is where PhotoStructure will write system settings.
CONFIG="$HOME/.config/PhotoStructure-docker"

# PhotoStructure will write logs into this directory.
LOGS="$CONFIG/logs"

# This 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.
CACHE="/tmp/photostructure-$USER"

docker run \
  -d \
  --name photostructure \
  --publish 1787:1787 \
  -e TZ="$(cat /etc/timezone)" \
  -v "$LIBRARY":/ps/library \
  -v "$CONFIG":/ps/config \
  -v "$LOGS":/ps/logs \
  -v "$CACHE":/ps/tmp \
  # The next three lines are for example only, edit to taste:
  -v "$HOME"/Pictures:/pictures/ \
  -v "/mnt/Photos backup":/photos-backup/ \
  -e PS_SCAN_ALL_DRIVES=1 \
  photostructure/server

Please note:

You may want to put this into a script to make future upgrades easier, or use a tool like Portainer.
If your library is on a remote volume (mounted from a NAS to your docker host, for example), you must add -e PS_FORCE_LOCAL_DB_REPLICA=1 to your docker run command. SQLite’s WAL mode doesn’t work reliably on remote filesystems, and this flag tells PhotoStructure to read and write from a local SQLite database replica to work around this issue.
To add directories you want to import into your PhotoStructure library:
1. Add those paths as volumes, and then
2. Either add -e PS_SCAN_ALL_DRIVES=1 to your docker run command (as was done in this example), or add the container mount points, separated by :, to a PS_SCAN_PATHS environment variable. If your paths include colons, encode the array in JSON: -e PS_SCAN_PATHS='["/path/one","/path/two"]'.
The PS_LOG_LEVEL environment variable defaults to warn. debug is very noisy, info less so, and error emits only on fatal errors.
The PS_HTTP_PORT environment variable defaults to 1787 but can be changed to a different port to suit.

Step 3: Welcome to PhotoStructure! #

Open a browser to http://localhost:1787 to complete installation.

Run PhotoStructure on startup #

After your PhotoStructure container is running, you can set it up to run at startup. This step is optional.

docker stop photostructure

sudo systemctl edit photostructure.service --full --force

And paste:

[Unit]
Description=PhotoStructure
Requires=docker.service
After=docker.service

[Service]
Restart=always
ExecStart=/usr/bin/docker start -a photostructure
# PhotoStructure vacuums and backs up your database on shutdown.
# This 1-minute timeout supports a graceful shutdown of very large
# libraries on slow computers with slow disks.
# It should normally take just a couple seconds.
ExecStop=/usr/bin/docker stop -t 60 photostructure

[Install]
WantedBy=local.target

Finally, enable the service:

sudo systemctl enable photostructure

And start PhotoStructure:

sudo service photostructure start

How to stop PhotoStructure #

If running via a Systemd service:

sudo service photostructure stop

Otherwise:

docker stop -t 60 photostructure

If your library is on a slow disk, or is large, make sure you always stop PhotoStructure with -t 60. This gives it time to vacuum and back up your library database completely. Docker’s timeout of 10 seconds may result in your library database being corrupted.

How to restart PhotoStructure #

If running via a Systemd service:

sudo service photostructure restart

Otherwise:

docker start photostructure

How to upgrade PhotoStructure #

Using Portainer #

First shut down PhotoStructure. Either select “Shutdown” from Portainer, or “Shutdown” from the nav menu within the PhotoStructure. Skipping this step may leave your library in a bad state.
From within portainer, click Containers, and click the name of your PhotoStructure container.
Click the Recreate button, and select Pull latest image:

Upgrading PhotoStructure within Portainer

Using Docker commands #

1. Fetch the latest version #

docker pull photostructure/server

2. Shut down the outdated container #

Always gracefully shut down PhotoStructure on system shutdown or when upgrading: skipping this step may leave your library in a bad state.

If running via a Systemd service:

sudo service photostructure stop

Otherwise:

docker stop -t 60 photostructure

or select “Shutdown” from the nav menu within the PhotoStructure.

3. Create the updated container #

docker create \
  --name photostructure_new \
  --volumes-from photostructure \
  # <insert all the non-volume options you set in step 3, like --expose and -e >
  photostructure/server

# remove the prior container:
docker rm photostructure

# rename the new container:
docker rename photostructure_new photostructure

4. Start the updated container #

If running via a Systemd service:

sudo service photostructure start

Otherwise:

docker start photostructure

Uninstalling PhotoStructure #

docker rm --force photostructure
As you see fit, remove your LIBRARY, CONFIG, LOG, and TMP directories, but 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 delete the $LIBRARY/.photostructure/previews directory.

Photo by Andrew Bain

Server