How To Setup/Install PhotoPrism 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.
Step 1: Configure on Linux
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 docker-compose.yml. Kernel security modules such as AppArmor and SELinux have been reported to cause issues. Ensure that your server has at least 4 GB of swap configured so that indexing doesn't cause restarts when there are memory usage spikes.
doesn’t cause restarts when there are memory usage spikes.
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.
It is not possible to change the password via MARIADB_PASSWORD after the database has been started for the first time. Choosing a secure password is not essential if you don't expose the database to other apps and hosts. To enable automatic schema updates after upgrading to a new major version, set MARIADB_AUTO_UPGRADE to a non-empty value in your docker-compose.yml.
Volumes
Since the app is running inside a container, you have to explicitly mount the host folders you want to use. PhotoPrism won’t be able to see folders that have not been mounted. That’s an important security feature.
/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:
code" style="box-sizing: inherit; -webkit-tap-highlight-color: transparent; background: transparent; border: 0px; font-family: inherit; font-size: inherit; margin: 0px; padding: 0px; user-select: none; text-decoration: none; border-radius: 0.1rem; color: var(--md-default-fg-color--lightest); cursor: pointer; height: 1.5em; outline: none; outline-offset: 0.1rem; position: absolute; right: 0.5em; top: 0.5em; transition: color 0.25s ease 0s; width: 1.5em; z-index: 1;">volumes:
# "/host/folder:/photoprism/folder" # example
- "~/Pictures:/photoprism/originals"You may mount any folder accessible from the host instead, including network drives. Additional directories can be mounted as subfolders of
/photoprism/originals:
code" style="box-sizing: inherit; -webkit-tap-highlight-color: transparent; background: transparent; border: 0px; font-family: inherit; font-size: inherit; margin: 0px; padding: 0px; user-select: none; text-decoration: none; border-radius: 0.1rem; color: var(--md-default-fg-color--lightest); cursor: pointer; height: 1.5em; outline: none; outline-offset: 0.1rem; position: absolute; right: 0.5em; top: 0.5em; transition: color 0.25s ease 0s; width: 1.5em; z-index: 1;">volumes:
- "/home/username/Pictures:/photoprism/originals"
- "/example/friends:/photoprism/originals/friends"
- "/mnt/photos:/photoprism/originals/media"On Windows, prefix the host path with the drive letter and use / instead of \ as separator:
code" style="box-sizing: inherit; -webkit-tap-highlight-color: transparent; background: transparent; border: 0px; font-family: inherit; font-size: inherit; margin: 0px; padding: 0px; user-select: none; text-decoration: none; border-radius: 0.1rem; color: var(--md-default-fg-color--lightest); cursor: pointer; height: 1.5em; outline: none; outline-offset: 0.1rem; position: absolute; right: 0.5em; top: 0.5em; transition: color 0.25s ease 0s; width: 1.5em; z-index: 1;">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. You can mount a folder with the :ro flag to make Docker block write operations as well.
/PHOTOPRISM/STORAGE¶
Cache, session, thumbnail and sidecar files are created in the storage folder:
- a storage folder mount must always be configured in your
docker-compose.ymlfile so that you do not lose these files after a restart or upgrade - never configure the storage folder to be inside the originals folder unless the name starts with a
.to indicate that it is hidden - we recommend placing the storage folder on a local SSD drive for best performance
- mounting symbolic links or using them inside the storage folder is currently not supported
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 may optionally mount an import folder from which files can be transferred to the originals folder in a structured way that avoids duplicates. Imported files receive a canonical filename and will be organized by year and month.
You can safely skip this. 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 the docker-compose.yml file has been saved.2 Run this command to start the application and database services in the background:
code" style="box-sizing: inherit; -webkit-tap-highlight-color: transparent; background: transparent; border: 0px; font-family: inherit; font-size: inherit; margin: 0px; padding: 0px; user-select: none; text-decoration: none; border-radius: 0.1rem; color: var(--md-default-fg-color--lightest); cursor: pointer; height: 1.5em; outline: none; outline-offset: 0.1rem; position: absolute; right: 0.5em; top: 0.5em; transition: color 0.25s ease 0s; width: 1.5em; z-index: 1;">docker-compose up -dNow 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.
It is not possible to change the password via PHOTOPRISM_ADMIN_PASSWORD after the app has been started for the first time. You may run docker-compose exec photoprism photoprism passwd in a terminal to change an existing password. You can also reset your database for a clean start.
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:
code" style="box-sizing: inherit; -webkit-tap-highlight-color: transparent; background: transparent; border: 0px; font-family: inherit; font-size: inherit; margin: 0px; padding: 0px; user-select: none; text-decoration: none; border-radius: 0.1rem; color: var(--md-default-fg-color--lightest); cursor: pointer; height: 1.5em; outline: none; outline-offset: 0.1rem; position: absolute; right: 0.5em; top: 0.5em; transition: color 0.25s ease 0s; width: 1.5em; z-index: 1;">docker-compose stop
docker-compose up -dStep 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?
Back us on Patreon or GitHub Sponsors. Your continued support helps us provide regular updates and services like world maps. Thank you!
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_WORKERSto a reasonably small value indocker-compose.yml, depending on the CPU performance and number of cores - Make sure your server 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
photoprism help lists all commands and config options available in the current version:
code" style="box-sizing: inherit; -webkit-tap-highlight-color: transparent; background: transparent; border: 0px; font-family: inherit; font-size: inherit; margin: 0px; padding: 0px; user-select: none; text-decoration: none; border-radius: 0.1rem; color: var(--md-default-fg-color--lightest); cursor: pointer; height: 1.5em; outline: none; outline-offset: 0.1rem; position: absolute; right: 0.5em; top: 0.5em; transition: color 0.25s ease 0s; width: 1.5em; z-index: 1;">docker-compose exec photoprism photoprism helpUse the --help flag to see a detailed command description, for example:
code" style="box-sizing: inherit; -webkit-tap-highlight-color: transparent; background: transparent; border: 0px; font-family: inherit; font-size: inherit; margin: 0px; padding: 0px; user-select: none; text-decoration: none; border-radius: 0.1rem; color: var(--md-default-fg-color--lightest); cursor: pointer; height: 1.5em; outline: none; outline-offset: 0.1rem; position: absolute; right: 0.5em; top: 0.5em; transition: color 0.25s ease 0s; width: 1.5em; z-index: 1;">docker-compose exec photoprism photoprism backup --helpWhen using Docker Compose, you can prepend commands like docker-compose exec [service] [command] to run them in a service container. Should this fail with no container found, make sure the service has been started, you have specified an existing service (usually photoprism) and you are in the folder where the docker-compose.yml file is located.
PhotoPrism’s command-line interface is well suited for job automation using a scheduler.
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
View Logs docker-compose logs — tail=100 -f
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 Index Database docker-compose exec photoprism photoprism reset -y
Backup Index Database docker-compose exec photoprism photoprism backup -a -i
Restore Index Database docker-compose exec photoprism photoprism restore -a -i
Change Admin Password docker-compose exec photoprism photoprism passwd
Show User Management Commands docker-compose exec photoprism photoprism users help
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 AVCdocker-compose exec photoprism photoprism convert
Regenerate Thumbnails docker-compose exec photoprism photoprism thumbs -f
Update Index docker-compose exec photoprism photoprism index — cleanup
Import Files docker-compose exec photoprism photoprism import [path]
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 "Full Rescan" and then clicking "Start".
The default Docker Compose config filename is docker-compose.yml. For simplicity, it doesn't need to be specified when running the docker-compose command in the same directory. Config files for other apps or instances should be placed in separate folders.
NOTE: If you like what we do, support our channel, put like and add our channel to your favorites. Follow Our Channel to get more guides.
Sponsor By: Meta Revolution World — Revold Project
