Setup Using Docker Compose¶
With Docker Compose, you use a YAML file to configure all application services so you can easily start them with a single command. Before you proceed, make sure you have Docker installed on your system. It is available for Mac, Linux, and Windows.
Alternatively, Podman Compose is supported as a drop-in replacement for Docker Compose on Red Hat-compatible Linux distributions like RHEL, CentOS, Fedora, AlmaLinux, and Rocky Linux.
Step 1: Configure¶
Download our docker-compose.yml example
(right click and Save Link As... or use wget
) to a folder of your choice,
and change the configuration as needed:
wget https://dl.photoprism.app/docker/docker-compose.yml
Commands on Linux may have to be prefixed with sudo
when not running as root.
Note that this will point the home directory shortcut ~
to /root
in the volumes:
section of your config file. Kernel security modules such as AppArmor and SELinux
have been reported to cause issues.
We recommend that your server has at least 4 GB of swap configured and to avoid setting a hard memory limit, as this can lead to unexpected restarts when the indexer temporarily needs more memory to process large files. Indexing RAW images and high-resolution panoramas may require additional swap space and/or physical memory beyond the recommended minimum.
Download our docker-compose.yml example
(right click and Save Link As... or use wget
) to a folder of your choice,
and change the configuration as needed:
wget https://dl.photoprism.app/podman/docker-compose.yml
Alternatively, you can run these commands to install Podman and download the default configuration to /opt/photoprism
:
mkdir -p /opt/photoprism
cd /opt/photoprism
curl -sSf https://dl.photoprism.app/podman/install.sh | bash
Please keep in mind to replace the docker
and docker compose
commands with podman
and podman-compose
when following the examples in our documentation.
We recommend that your server has at least 4 GB of swap configured and to avoid setting a hard memory limit, as this can lead to unexpected restarts when the indexer temporarily needs more memory to process large files. Indexing RAW images and high-resolution panoramas may require additional swap space and/or physical memory beyond the recommended minimum.
Download our docker-compose.yml example for
the Raspberry Pi and other ARM64-based devices (right click and Save Link As... or use wget
) to a folder of your choice,
and change the configuration as needed:
wget https://dl.photoprism.app/docker/arm64/docker-compose.yml
Mostly the same installation instructions as for regular Linux servers apply.
Commands may have to be prefixed with sudo
when not running as root.
Please verify if your device meets the system requirements and has at least 4 GB of swap configured before you continue. Indexing RAW images and high-resolution panoramas may require additional swap space and/or physical memory beyond the recommended minimum.
Download our docker-compose.yml example for
older ARMv7-based devices (right click and Save Link As... or use wget
) to a folder of your choice,
and change the configuration as needed:
wget https://dl.photoprism.app/docker/armv7/docker-compose.yml
Mostly the same installation instructions as for regular Linux servers apply.
Commands may have to be prefixed with sudo
when not running as root.
Please verify if your device meets the system requirements and has at least 4 GB of swap configured before you continue. Indexing RAW images and high-resolution panoramas may require additional swap space and/or physical memory beyond the recommended minimum.
Download our docker-compose.yml example for Windows (right click and Save Link As...) to a folder of your choice, and change the configuration as needed:
https://dl.photoprism.app/docker/windows/docker-compose.yml
It is important to increase the Docker memory limit to 4 GB or more when using Hyper-V. The default of 2 GB can reduce indexing performance and cause unexpected restarts. Also make sure you configure at least 4 GB of swap space. Docker Desktop uses dynamic memory allocation with WSL 2, meaning you do not need to change any memory-related settings (depending on which version of Windows and Docker you are using).
Indexing RAW images and high-resolution panoramas may require additional swap space and/or physical memory beyond the recommended minimum.
Running the following commands will automatically download all required config files and start the server for you:
curl.exe -o install.bat https://dl.photoprism.app/docker/windows/install.bat
install.bat
Before you run this, make sure you are in the directory where you want to install PhotoPrism and that Docker Desktop is installed and started on your PC.
Download our docker-compose.yml example for macOS (right click and Save Link As...) to a folder of your choice, and change the configuration as needed:
https://dl.photoprism.app/docker/macos/docker-compose.yml
It is important to increase the Docker memory limit to 4 GB or more, as the default of 2 GB can reduce indexing performance and cause unexpected restarts.
Indexing RAW images and high-resolution panoramas may require additional swap space and/or physical memory beyond the recommended minimum.
When editing YAML files, please make sure that related values remain on the same indentation level and that lists start with a dash.
If the value of an environment variable contains a literal $
sign, for example in a password, it must be escaped with $$
(a double dollar sign) so that e.g. "compo$e"
becomes "compo$$e"
.
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 servers.
There is no default in case no password was provided. A minimum length of 8 characters is required.
Database¶
Our example includes a pre-configured MariaDB database server. If you remove it and provide no other database server credentials, SQLite database files will be created in the storage folder. Local SSD storage is best for databases of any kind.
Never store database files on an unreliable device such as a USB flash drive, SD card, or shared network folder. These may also have unexpected file size limitations, which is especially problematic for databases that do not split data into smaller files.
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.
Volumes¶
You must explicitly specify the directories you want to mount from your host, 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 are mounted to persistent volumes. We recommend changing the relative paths used in our examples to absolute paths and to avoid using named or anonymous volumes in order to prevent potential data loss when the container is recreated, e.g. after an update of the Docker image.
/photoprism/originals¶
The originals folder contains your original photo and video files. ~/Pictures
will be mounted by default, where ~
is a shortcut for your home directory:
services:
photoprism:
volumes:
- "~/Pictures:/photoprism/originals"
We recommend that you change ~/Pictures
to the directory 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"
On Windows, prefix the host path with the drive letter and use /
instead of \
as separator:
volumes:
- "D:/Example/Pictures:/photoprism/originals"
If read-only mode is enabled, all features that require write permission to the originals folder
are disabled, e.g. WebDAV, uploading and deleting files. Set PHOTOPRISM_READONLY
to "true"
in docker-compose.yml
for this. In addition, you can mount volumes with the :ro
flag
so that writes are also blocked by Docker.
/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 you put the storage folder on a local SSD drive for best performance. You can otherwise keep the default and store the files in a folder relative to the current directory:
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 host, 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: Start the server¶
Open a terminal and change to the folder in which your config file has been saved.1 Run this command to start the application and database services in the background:
docker compose up -d
Note that our examples use the new docker compose
command by default. If your server does not yet support it, you can still use docker-compose
or alternatively podman-compose
on Red Hat-compatible distributions.
Now open the Web UI by navigating to http://localhost:2342/. You should see a login screen.
Sign in with the user admin
and the initial password configured via PHOTOPRISM_ADMIN_PASSWORD
.
You may change it on the account settings page.
Enabling public mode will disable authentication.
It can be helpful to keep Docker running in the foreground while debugging so that log messages are displayed directly. To do this, omit the -d
parameter when restarting.
Should the server already be running, or you see no errors, you may have started it on a different host and/or port. There could also be an issue with your browser, ad blocker, or firewall settings.
You cannot change the password with PHOTOPRISM_ADMIN_PASSWORD
after the app has been started for the first time. To change the admin password, run the docker compose exec photoprism photoprism passwd [username]
command in a terminal. You can also run docker compose exec photoprism photoprism reset
to delete the existing index database and start from scratch.
The server port and other config options can be changed in docker-compose.yml
at any time.
Remember to restart the services for changes to take effect:
docker compose stop
docker compose up -d
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.
Easy, isn't it?
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 server 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 indocker-compose.yml
, depending on the CPU performance and number of cores - Ensure that your server has at least 4 GB of swap configured and avoid setting a hard memory limit as this can cause unexpected restarts when the indexer temporarily needs more memory to process large files
- 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¶
Introduction¶
photoprism help
lists all commands and config options available in the current version:
docker compose exec photoprism photoprism help
Use the --help
flag to see a detailed command description, for example:
docker compose exec photoprism photoprism backup --help
PhotoPrism's command-line interface is also well suited for job automation using a scheduler.
When using Docker Compose, you can prefix the commands you want to run with docker compose exec [service]
to execute them in the specified service container.
If this fails with no container found, please make sure that the service has been started, you have specified an existing service (usually photoprism
) and you are in the folder where your config file is located.
Opening a Terminal¶
To open a terminal session as the default user:
docker compose exec photoprism bash
Since the above will open the terminal as root by default, we recommend that you pass the -u
flag to explicitly open a non-root session if PhotoPrism is running under a specific user account, for example:
docker compose exec -u 1000 photoprism bash
This avoids potential filesystem permission issues that can occur when a command creates new files or folders, e.g. to store thumbnails.
Changing the User ID¶
Specifying a user with the -u
flag is possible for all commands you run with Docker and Docker Compose. In the following examples, it is omitted for brevity.
Note, however, that commands that you run without an explicit user ID might be executed as root.
The currently supported user ID ranges are 0, 33, 50-99, 500-600, 900-1250, and 2000-2100.
We recommend running the photoprism
service as a non-root user by setting either the user service property or the PHOTOPRISM_UID
environment variable in your config file. Don't forget to update file permissions and/or ownership with the chown
command when you make changes.
Examples¶
Action | Command |
---|---|
Start Services | docker compose up -d |
Stop Services | docker compose stop |
Download Updates | docker compose pull |
Uninstall | docker compose rm -s -v |
Watch Logs | docker compose logs -f --tail=100 |
Display Config Values | docker compose exec photoprism photoprism show config |
Show Migration Status | docker compose exec photoprism photoprism migrations ls |
Repeat Failed Migrations | docker compose exec photoprism photoprism migrations run -f |
Reset Database | docker compose exec photoprism photoprism reset --yes |
Backup Database | docker compose exec photoprism photoprism backup -a -i |
Restore Database | docker compose exec photoprism photoprism restore -a -i |
Change Password | docker compose exec photoprism photoprism passwd [username] |
Show User Management Commands | docker compose exec photoprism photoprism users help |
Reset User Accounts | docker compose exec photoprism photoprism users reset --yes |
Reset Sessions and Access Tokens | docker compose exec photoprism photoprism auth reset --yes |
Show Face Recognition Commands | docker compose exec photoprism photoprism faces help |
Index Faces | docker compose exec photoprism photoprism faces index |
Reset People & Faces | docker compose exec photoprism photoprism faces reset -f |
Transcode Videos to AVC | docker compose exec photoprism photoprism convert |
Regenerate Thumbnails | docker compose exec photoprism photoprism thumbs -f |
Update Index | docker compose exec photoprism photoprism index --cleanup |
Move to Originals | docker compose exec photoprism photoprism import [path] |
Copy to Originals | docker compose exec photoprism photoprism cp [path] |
Note that our examples use the new docker compose
command by default. If your server does not yet support it, you can still use docker-compose
or alternatively podman-compose
on Red Hat-compatible distributions.
Complete Rescan
docker compose exec photoprism photoprism index -f
rescans all originals, including already indexed and unchanged files.
This may be necessary after major upgrades and after migrations of the database schema, especially if search results are missing or incorrect. Note you can also start a rescan from the user interface by navigating to Library > Index, checking "Complete Rescan" and then clicking "Start". Manually entered information such as labels, people, titles or descriptions will not be modified when indexing, even if you perform a "complete rescan".
-
The default name for Docker Compose config files is
compose.yaml
ordocker-compose.yml
. For simplicity, it does not need to be specified if you run commands in the same directory. Config files for other apps and instances should be placed in separate folders. ↩