PhotoPrism is a modern, open-source personal photo gallery powered by artificial intelligence. It allows you to easily organize, browse, and share your collection of photos and videos. PhotoPrism uses machine learning for automatic image classification, face recognition, and geotagging, greatly simplifying the management of large media archives.

In this article, we will go through the process of installing and configuring PhotoPrism on Ubuntu 24.04 using Docker Compose. You will learn how to prepare the server, launch the application, configure the firewall, perform the initial setup, import media files, and create data backups.

Preparing the Server

Updating the System

Before installing PhotoPrism, update all system packages to the latest versions for stability and security.

sudo apt update
sudo apt upgrade -y
sudo apt autoremove -y

• sudo apt update refreshes the package list.
• sudo apt upgrade -y installs available updates without confirmation.
• sudo apt autoremove -y removes obsolete packages.

Creating a Directory for PhotoPrism

Create a directory for PhotoPrism configuration files and data. The recommended path is /opt/photoprism.

sudo mkdir -p /opt/photoprism

• The -p flag ensures parent directories are created if they do not exist.

Downloading the Docker Compose Configuration

Download the official docker-compose.yml file for PhotoPrism, which defines all required services (PhotoPrism, MariaDB).

sudo wget -O /opt/photoprism/docker-compose.yml https://dl.photoprism.app/docker/compose.yaml

• wget downloads the file from the URL.
• -O /opt/photoprism/docker-compose.yml saves it as docker-compose.yml in /opt/photoprism.

Configuring Local Storage and Docker Compose File

By default, PhotoPrism uses Docker named volumes. For easier management and backups, we’ll use local directories (bind mounts).

First, create the directories for PhotoPrism and MariaDB data:

sudo mkdir -p /opt/photoprism/data/storage \
                /opt/photoprism/data/originals \
                /opt/photoprism/data/database \
                /opt/photoprism/data/settings \
                /opt/photoprism/data/cache \
                /opt/photoprism/data/sidecar

Then edit the docker-compose.yml file:

sudo nano /opt/photoprism/docker-compose.yml

Locate the services → photoprism → volumes section. Replace named volumes with local paths:

Before:

    volumes:
      - photoprism_storage:/photoprism/storage
      - photoprism_originals:/photoprism/originals
      - photoprism_settings:/photoprism/settings
      - photoprism_cache:/photoprism/cache
      - photoprism_sidecar:/photoprism/sidecar

After:

    volumes:
      - /opt/photoprism/data/storage:/photoprism/storage
      - /opt/photoprism/data/originals:/photoprism/originals
      - /opt/photoprism/data/settings:/photoprism/settings
      - /opt/photoprism/data/cache:/photoprism/cache
      - /opt/photoprism/data/sidecar:/photoprism/sidecar

Do the same for services → mariadb → volumes:

Before:

    volumes:
      - photoprism_database:/var/lib/mysql

After:

    volumes:
      - ./data/database:/var/lib/mysql

Finally, scroll to the bottom of the file and delete the volumes: block, since we are not using named volumes anymore.

Save and exit (Ctrl+O, Enter, Ctrl+X).

Setting Environment Variables

Create a .env file in /opt/photoprism to configure PhotoPrism credentials.

sudo nano /opt/photoprism/.env

Add:

PHOTOPRISM_ADMIN_USER=YOUR_ADMIN_USERNAME
PHOTOPRISM_ADMIN_PASSWORD=YOUR_ADMIN_PASSWORD

Save and close the file.

Starting PhotoPrism

Run the containers:

cd /opt/photoprism/
sudo docker compose up -d

• cd /opt/photoprism/ changes to the working directory.
• docker compose up -d launches all services in detached mode.

Checking Status

Verify all containers are running:

sudo docker compose ps

For logs:

sudo docker compose logs -f

Exit with Ctrl+C.

Configuring the Firewall

Open port 2342 (PhotoPrism web UI), and optionally 80 and 443 if using a reverse proxy.

UFW:

sudo ufw status
sudo ufw allow 2342/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Enable UFW if disabled:

sudo ufw enable

iptables:

sudo iptables -A INPUT -p tcp --dport 2342 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT

Accessing the Web Interface

Go to:

http://YOUR_SERVER_IP:2342

Initial Login

Use the credentials from .env:

• Username: YOUR_ADMIN_USERNAME
• Password: YOUR_ADMIN_PASSWORD

Importing Photos

Copy photos into /opt/photoprism/data/originals:

sudo cp -r PATH_TO_YOUR_PHOTOS /opt/photoprism/data/originals

Then, in the web UI, click Import.

Updating PhotoPrism

cd /opt/photoprism/
sudo docker compose down
sudo docker compose pull
sudo docker compose up -d

Backups

Create a backup archive:

sudo tar -czvf photoprism_backup_$(date +%Y%m%d).tar.gz /opt/photoprism/data /opt/photoprism/docker-compose.yml /opt/photoprism/.env

Common Issues

Error / Symptom	Cause	Solution	Diagnostics
Cannot access web UI.	Port 2342 blocked by firewall.	Allow port in UFW: sudo ufw allow 2342/tcp, iptables: sudo iptables -A INPUT -p tcp --dport 2342 -j ACCEPT	sudo ufw status
Containers not starting or restarting.	Insufficient resources or port conflicts.	Check logs: sudo docker compose logs. Ensure port 2342 is free.	sudo docker compose ps
Database access error.	Wrong credentials or corrupted DB.	Verify .env file, reset DB if needed.	sudo docker compose logs mariadb
Photos not imported.	Wrong permissions or unsupported format.	Fix permissions on originals directory.	ls -la /opt/photoprism/data/originals

Useful Links