Portainer Setup Guide

Portainer can be used to manage Docker containers through a web interface. On many NAS devices, it either comes pre-installed or you can simply install it from the vendor's app store. If you are installing PhotoPrism on a regular home or cloud server, you may instead want to follow our Docker Compose Setup Guide, which only uses standard Docker tools and commands.

Step 1: Create Stack

Navigate to "Stacks", click "Add stack" and paste the contents of our stack.yml config template (opens in a new tab) into the Web editor so that you can change the storage folder locations in the volumes sections as needed:

When using the Web editor, please make sure that related values remain on the same indentation level and that lists start with a dash as shown in our template.

Volumes

You need to explicitly specify the directories you want to use on your NAS device, since PhotoPrism can't see files in folders that have not been shared. This is an important security feature and allows for a flexible configuration without having to change any other variables.

It is important that all folders specified in the "volumes" sections are located on a persistent volume on your device. We recommend changing the relative paths used in our example to absolute paths in order to avoid potential data loss, e.g. if the default application folder managed by Portainer changes or is reset after an update.

The volume mount paths to configure depend on your NAS device and its settings. As on most operating systems, a dot followed by a slash ./ can be used to specify a path relative to the current directory. If you keep the defaults, all files will be located in the internal application folder that Portainer automatically creates when you add a new stack.

Database

Our stack template includes a pre-configured MariaDB database server that stores its data in the Portainer application folder by default:

services:
  mariadb:
    volumes:
      - "./database:/var/lib/mysql"

If your NAS device has a mixed drive configuration with solid-state drives (SSDs) and traditional hard disks, we recommend that you change ./database to an absolute path located on an SSD as this significantly improves performance, for example:

      - "/mnt/ssd/database:/var/lib/mysql"

Database files should never be located on an unreliable device such as a USB flash drive, SD card, or network folder.

/photoprism/originals

The originals folder contains your original photo and video files:

services:
  photoprism:
    volumes:
      - "./originals:/photoprism/originals"

We recommend that you change ./originals to the directory on your NAS where your existing media files are, for example:

      - "/mnt/photos:/photoprism/originals"

Additional directories can be mounted as sub folders of /photoprism/originals (depending on overlay filesystem support):

    volumes:
      - "/mnt/photos:/photoprism/originals"
      - "/mnt/videos:/photoprism/originals/videos"

If you want to start with an empty library, you can mount any directory that has enough free space for your needs.

/photoprism/storage

The storage folder is used to save config, cache, backup, thumbnail, and sidecar files. It must always be specified so that you do not lose these files after a restart or upgrade. If available, we recommend that you put the storage folder on a local SSD drive for best performance. You can otherwise keep the default to store the files in the internal application folder:

services:
  photoprism:
    volumes:
      - "./storage:/photoprism/storage"

Never configure the storage folder to be inside the originals folder unless the name starts with a . to indicate that it is hidden. Should you later want to move your instance to another NAS, the easiest and most time-saving way is to copy the entire storage folder along with your originals and database.

/photoprism/import

You can optionally mount an import folder from which files can be transferred to the originals folder in a structured way that avoids duplicates, for example:

services:
  photoprism:
    volumes:
      - "/mnt/media/usb:/photoprism/import"

Imported files receive a canonical filename and will be organized by year and month. You should never configure the import folder to be inside the originals folder, as this will cause a loop by importing already indexed files.

Even if you don't specify an import folder, adding files via Web Upload and WebDAV remains possible unless read-only mode is enabled or the features have been disabled.

Step 2: Finalize Setup

To complete the setup, download the stack.env file from our server (right click and Save Link As...), click "Load variables from .env file", upload it to Portainer, and then change the values according to your needs:

Always change PHOTOPRISM_ADMIN_PASSWORD so that the app starts with a secure initial password. Never use easy-to-guess passwords or default values like insecure on publicly accessible instances. There is no default in case no password was provided. A minimum length of 8 characters is required.

You cannot change the database password with MARIADB_PASSWORD after MariaDB has been started for the first time. However, choosing a secure password is not essential if you do not share the database with other applications or expose it over a network. To enable automatic schema updates when upgrading to a new major version, please make sure that MARIADB_AUTO_UPGRADE is set to a non-empty value.

When you're done, scroll down and click "Deploy the stack" without changing any of the other options:

After waiting a few moments, you should be able to log in as admin with the password specified in PHOTOPRISM_ADMIN_PASSWORD when you navigate to http://localhost:2342/.

If you have modified the server hostname, port, or protocol in your configuration, the URL to use changes accordingly.

Step 3: Index Your Library

Our First Steps 👣 tutorial guides you through the user interface and settings to ensure your library is indexed according to your individual preferences.

The config options and container image you want to use can be changed at any time by navigating to "Stacks", selecting your existing PhotoPrism stack, clicking "Editor", updating the configuration to your needs, and then clicking "Update the stack" to apply the changes.

PhotoPrism® Plus

Our members can activate additional features by logging in with the admin user created during setup and then following the steps described in our activation guide. Thank you for your support, which has been and continues to be essential to the success of the project!

Compare Memberships › View Membership FAQ ›

We recommend that new users install our free Community Edition before signing up for a membership.

Troubleshooting

If your device runs out of memory, the index is frequently locked, or other system resources are running low:

• Try reducing the number of workers by setting PHOTOPRISM_WORKERS to a reasonably small value, depending on the CPU performance and number of cores
• Make sure your device has at least 4 GB of swap space so that indexing doesn't cause restarts when memory usage spikes; RAW image conversion and video transcoding are especially demanding
• If you are using SQLite, switch to MariaDB, which is better optimized for high concurrency
• As a last measure, you can disable the use of TensorFlow for image classification and facial recognition

Other issues? Our troubleshooting checklists help you quickly diagnose and solve them.

You are welcome to ask for help in our community chat. Sponsors receive direct technical support via email. Before submitting a support request, try to determine the cause of your problem.

Command-Line Interface

Opening a Terminal

Navigate to "Stacks", select the PhotoPrism stack and scroll down to the list of containers:

Now click the button belonging to the photoprism-photoprism-1 container and accept the default settings to open a terminal:

Running photoprism help lists all commands and options available in the current version:

photoprism help

Use the --help flag to see a detailed command description, for example:

photoprism backup --help

The command-line interface is also well suited for job automation using a scheduler.

Examples

Action	Command
Display Config Values	photoprism show config
Show Migration Status	photoprism migrations ls
Repeat Failed Migrations	photoprism migrations run -f
Reset Database	photoprism reset --yes
Backup Database	photoprism backup -a -i
Restore Database	photoprism restore -a -i
Change Password	photoprism passwd [username]
Show User Management Commands	photoprism users help
Reset Users	photoprism users reset --yes
Show Face Recognition Commands	photoprism faces help
Index Faces	photoprism faces index
Reset People & Faces	photoprism faces reset -f
Transcode Videos to AVC	photoprism convert
Regenerate Thumbnails	photoprism thumbs -f
Update Index	photoprism index --cleanup
Move to Originals	photoprism import [path]
Copy to Originals	photoprism cp [path]