Docker Compose Wizard

Docker Compose Wizard

Before you begin, make sure you have:

For background on Docker concepts (bind mounts, networking, Synology, Portainer, etc.), see the Docker reference page.

Configure your compose.yaml

Fill in the form to generate a compose.yaml for PhotoStructure.

* indicates required fields.

Changing this updates the default library directory, PUID, and PGID below.

See tkohhh's recommended UnRAID setup for additional guidance. We changed your PUID to 99 and PGID to 100, but that may not be correct for your system--please double-check and adjust as needed.
SSH into your NAS and run id to find your PUID — Synology assigns UIDs sequentially, so it varies per system. See Synology NAS tips for more details.
TrueNAS SCALE runs apps as 568:568 (the built-in apps user and group). Replace tank with your actual pool name. Create the dataset in TrueNAS first, then set ownership to 568:568.

Where PhotoStructure stores your library database, previews, and (optionally) organized copies of your photos. Must be readable, writable, and have sufficient free space. See /ps/library for details.

Required: Set a cache path below pointing to a fast local disk with 16–32 GB free.

Optional. Directories containing photos and videos you want to import. PhotoStructure always scans your library directory — add any other locations here. Check Read-only to prevent PhotoStructure from writing to that directory.

Videos and photos from your phone: PhotoStructure now sets up the extra import tools during first launch. As of v2026.4.7, the wizard no longer builds a custom image for codec tools. PhotoStructure prompts for consent and installs them from the container's operating system package manager. See media codec support for details.

Docker containers run as root by default, which causes file ownership problems. These IDs tell PhotoStructure which user and group should own your library files. Run id in your terminal to find yours. See PUID/PGID docs.

Run id -u to find yours.

Run id -g to find yours.

Advanced options
  • beta has the latest features and is updated frequently.
  • stable will be the recommended tag soon. For now, use beta.
  • See release history.

The Docker container name. Must be unique on your host.

Controls when Docker restarts the container. See Docker docs.

Controls whether Docker binds the port to all interfaces (LAN-accessible) or 127.0.0.1 (this machine only). PhotoStructure for Docker already listens on all interfaces inside the container, so this is enabled by default to match. PhotoStructure has no built-in authentication, so only expose it on networks you trust. See remote access for details.

HTTP port for the PhotoStructure web UI. Default is 1787.

Auto-detected from your browser. Used for assets without timezone metadata. Full list of timezones

Optional. Cap how much memory or CPU PhotoStructure can use. See Docker docs.

e.g., 4g, 2g, 512m

e.g., 2.0 (number of cores)

Controls how face-tagged names are organized into "Who" tags. See the name parsing guide for details.

Controls how names are parsed into given/family components and displayed in "Who" tags.

See PhotoStructure's environment variables for details

Advanced directory setup

PhotoStructure always imports photos and videos stored here.
When Copy assets to library is enabled, newly found media from other locations is also copied here.
Useful for keeping originals on a large drive while previews stay on a faster SSD.
See the bind mount reference for /ps/originals.

Must be a directory on a local disk (> 32 GB free, SSD recommended).
Defaults to $libraryDir/.photostructure/tmp.
See the bind mount reference for /ps/tmp.

Defaults to $libraryDir/.photostructure/logs
See the bind mount reference for /ps/logs.

Defaults to $libraryDir/.photostructure/.docker-config.
If you have multiple libraries, they can share system settings by bind-mounting the same directory.
See the bind mount reference for /ps/config.

Your compose.yaml

Next steps

  1. Make sure the directories referenced in your compose.yaml exist:

    mkdir -p /mnt/media/PhotoStructure

  2. Save the generated YAML as compose.yaml into your library directory

  3. Start PhotoStructure:

    cd /mnt/media/PhotoStructure
docker compose up --detach

  4. Open http://localhost:1787 to complete setup

Upgrading

docker compose pull
docker compose up --detach

The generated compose.yaml includes pull_policy: always, so docker compose up will check for newer images automatically. The explicit pull is still recommended to separate the download from the restart.

Why no Watchtower? The Watchtower project was archived in December 2025 and is incompatible with Docker 28+. If you were using Watchtower, you can safely remove it and use docker compose pull && docker compose up --detach above instead.

Stopping and restarting

# Stop
docker compose down

# Start
docker compose up --detach

A slow shutdown is normal. It can happen when your library is on a network drive, when the library is large, or when a sync was in progress. PhotoStructure waits up to 2 minutes to stop gracefully. See why does it take so long to shut down?

Adding or removing directories

To import photos from a new directory (or stop scanning one):

  1. Stop PhotoStructure: docker compose down
  2. Revisit this page (your browser remembers your settings), add or remove the directories, and re-download the compose.yaml.
  3. Restart: docker compose up --detach

Uninstalling

docker compose down
docker compose rm

Remove your library, config, tmp, and logs directories as needed. Take care not to delete photos and videos you want to keep!

More information