How To Install PhotoPrism on Ubuntu 26.04 LTS

If you want a clean, reliable way to self-host your photo library, Install PhotoPrism on Ubuntu 26.04 is a strong place to start. This guide shows you how to build a proper PhotoPrism on Ubuntu 26.04 setup with Docker, strong security defaults, and clear steps that explain both how and why each part matters.

PhotoPrism is a self-hosted photo management app built for browsing, organizing, and searching large collections. Ubuntu 26.04 LTS is a stable base for long-term hosting because Canonical supports it for five years with security updates and critical fixes. That makes it a good fit for a Linux server tutorial that aims to be practical, durable, and easy to maintain.

I wrote this for beginner to intermediate Linux users, developers, and sysadmins who want a setup that feels production-ready, not rushed. You will use Docker, map persistent storage correctly, configure the site URL, and prepare the system for HTTPS if you plan to expose it publicly.

Table of Contents

Prerequisites

Before you start, make sure you have the following:

Ubuntu 26.04 LTS installed on the server.
A user with sudo privileges.
At least 2 CPU cores and 3 GB RAM, though more memory is better for large libraries.
Enough disk space for your photo library, thumbnails, and database files.
A terminal or SSH access.
A domain name if you plan to use HTTPS with a reverse proxy.

Step 1: Update your system

Why this matters

You should always patch the operating system first. That reduces the chance of hitting dependency issues later and gives Docker and PhotoPrism a clean base to run on.

Run the update commands

sudo apt update
sudo apt upgrade -y

apt update refreshes the package list, while apt upgrade -y installs the latest available updates. On a fresh or recently installed Ubuntu 26.04 LTS system, this is one of the simplest ways to avoid avoidable problems.

Check whether a reboot is needed

sudo reboot

A reboot is not always required, but it is a good idea if the kernel, libc, or other core packages were updated. It helps ensure the system starts from a known-good state before you install the container stack.

Step 2: Install Docker

Why Docker is the right choice

PhotoPrism is designed to run well in containers, and Docker gives you a predictable runtime with fewer dependency conflicts. For self-hosted software, that matters because the app, database, and storage layout can stay isolated from the rest of the system.

Install the required packages

sudo apt install -y ca-certificates curl gnupg

These tools help Ubuntu trust external repositories and download Docker securely. That is important because you want the official Docker packages, not random third-party builds.

Add Docker’s GPG key

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

This tells Ubuntu how to verify Docker packages. It protects you from installing tampered packages and keeps the install chain trustworthy.

Add the Docker repository

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

This step adds the official Docker source for your Ubuntu release. That matters because repository-based installs usually give better version alignment than older distro packages.

Install Docker Engine

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

This installs the Docker daemon, command-line tools, and the Compose plugin. For a PhotoPrism on Ubuntu 26.04 setup, Compose is especially useful because you will usually run more than one container.

Verify the installation

docker --version
docker compose version

Expected output should show a Docker version and a Docker Compose plugin version. If both commands work, the container stack is ready.

Optional: allow your user to run Docker without sudo

sudo usermod -aG docker $USER
newgrp docker

This makes Docker easier to use in an admin workflow. It is convenient, but on shared systems you should still think about access control because Docker access is powerful.

Step 3: Create the PhotoPrism directory

Why directory layout matters

A clean directory layout makes backups, upgrades, and troubleshooting easier. It also keeps your app files separate from personal data and reduces confusion later.

Create the project folder

sudo mkdir -p /opt/photoprism
cd /opt/photoprism

Using /opt is a common choice for manually managed server applications. It gives you one clear place to store the Compose file and related data directories.

Create the persistent folders

sudo mkdir -p originals storage database

These folders separate photo originals, PhotoPrism metadata, and database data. That separation matters because each type of data has different backup and performance needs.

Step 4: Download the Compose file

Why use the official Compose format

The safest way to configure PhotoPrism is to start from the official Docker Compose guidance. That reduces version drift and helps you stay close to the documented setup.

Create or edit the Compose file

nano docker-compose.yml

You can also use vim or your preferred editor. The key point is to keep the file readable and controlled by you, not copied from random outdated examples.

A clean starter example

services:
  photoprism:
    image: photoprism/photoprism:latest
    container_name: photoprism
    restart: unless-stopped
    ports:
      - "2342:2342"
    environment:
      PHOTOPRISM_ADMIN_USER: "admin"
      PHOTOPRISM_ADMIN_PASSWORD: "ChangeMe-StrongPassword"
      PHOTOPRISM_SITE_URL: "http://YOUR_SERVER_IP:2342/"
      PHOTOPRISM_ORIGINALS_PATH: "/photoprism/originals"
      PHOTOPRISM_STORAGE_PATH: "/photoprism/storage"
    volumes:
      - ./originals:/photoprism/originals
      - ./storage:/photoprism/storage
    depends_on:
      - mariadb

  mariadb:
    image: mariadb:10.11
    container_name: photoprism-db
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: photoprism
      MARIADB_USER: photoprism
      MARIADB_PASSWORD: ChangeMe-DatabasePassword
      MARIADB_ROOT_PASSWORD: ChangeMe-RootPassword
    volumes:
      - ./database:/var/lib/mysql

This example keeps the structure simple on purpose. It gives you a solid base for a secure PhotoPrism on Ubuntu 26.04 setup without hiding the important parts.

Step 5: Configure PhotoPrism on Ubuntu 26.04

Set the admin password

The admin password controls access to your library, so do not leave it weak. A bad password is the fastest way to turn a private photo server into a security problem.

PHOTOPRISM_ADMIN_PASSWORD: "ChangeMe-StrongPassword"

You should use a long, unique password here. The reason is simple: if someone gets into the admin account, they can browse your library and change settings.

Set the site URL correctly

PHOTOPRISM_SITE_URL: "http://YOUR_SERVER_IP:2342/"

This value must match the way you access the app. If you later place PhotoPrism behind HTTPS and a reverse proxy, change it to your public https:// address.

Configure storage paths

PHOTOPRISM_ORIGINALS_PATH: "/photoprism/originals"
PHOTOPRISM_STORAGE_PATH: "/photoprism/storage"

These settings tell PhotoPrism where to find source images and where to store thumbnails and app data. Keeping them separate helps you back up the original files without mixing them with generated data.

Configure the database

PhotoPrism supports database-backed deployments, and MariaDB is the better choice when you want stronger long-term performance and cleaner management for larger collections. That is why the Compose example includes a separate MariaDB service.

MARIADB_DATABASE: photoprism
MARIADB_USER: photoprism
MARIADB_PASSWORD: ChangeMe-DatabasePassword
MARIADB_ROOT_PASSWORD: ChangeMe-RootPassword

These values define the database name, user, and credentials. They must all be unique and strong because they protect the metadata that PhotoPrism depends on.

Why this configuration works

This setup gives you a predictable stack. PhotoPrism handles the UI and photo indexing, while MariaDB stores application data in a separate container, which makes upgrades and backups easier to manage.

Step 6: Start the stack

Pull the latest images

docker compose pull

This downloads the container images before startup. It is useful because you know exactly what will run, and you can catch image issues before the app starts.

Start PhotoPrism and MariaDB

docker compose up -d

The -d flag runs the stack in the background. That is the normal way to run a server app, because you do not want your shell session tied to the service.

Check container status

docker compose ps

Expected output should show both services as running. If one fails, you will usually see it here first.

Watch the logs

docker compose logs -f

Logs tell you whether the database connected, whether permissions are correct, and whether PhotoPrism finished booting. In real sysadmin work, logs are usually the fastest path to the answer.

Step 7: Open PhotoPrism in your browser

Test local access

http://YOUR_SERVER_IP:2342

That should bring up the web interface if the containers started correctly. For a first login, use the admin account and the password you set in the Compose file.

What to expect after login

You will usually see the main dashboard and library controls. At this point, you can point PhotoPrism at your photo folder and begin indexing.

Why this stage matters

This is the moment where you confirm that the whole stack works as a unit. If the UI opens and you can log in, the server, containers, and database are connected properly.

Step 8: Secure public access

Use HTTPS for remote access

If the server is public, do not leave it on plain HTTP. PhotoPrism documentation recommends placing it behind a secure HTTPS reverse proxy such as Apache or Traefik.

Disable TLS inside PhotoPrism behind a proxy

PHOTOPRISM_DISABLE_TLS="true"

This matters because the reverse proxy should terminate TLS, not the app container itself. That keeps certificate handling in one place and avoids confusion.

Set trusted proxy values

If your proxy is outside Docker’s internal address range, add it to the trusted proxy list so forwarded headers are accepted correctly. This helps PhotoPrism understand the real client IP and protocol.

Why this hardening step is important

Without HTTPS, passwords and session data can travel in clear text over the network. That is unacceptable for a photo server that may contain personal or private content.

Troubleshooting

1. Container will not start

Check the logs first:

docker compose logs -f

If the stack fails immediately, the most common causes are a typo in the Compose file, missing environment variables, or an invalid password. Fix the file, then restart the stack.

2. Port 2342 is already in use

Check what is using the port:

sudo ss -tulpn | grep 2342

If another service already uses that port, change the host mapping in the Compose file or stop the conflicting service. Port conflicts are common on shared servers.

3. PhotoPrism opens, but photos do not appear

This usually means the volume mapping is wrong or the library path does not point to your originals folder. Confirm that the host path and container path match the Compose file exactly.

4. Login fails after startup

Double-check the admin password in the Compose file. If you changed it after the first launch, you may need to recreate the container or update the stored value carefully.

5. HTTPS proxy errors

If you use Apache, Traefik, or another proxy, make sure PhotoPrism runs with internal TLS disabled and the public URL uses https://. A mismatch here often causes redirect loops or broken login sessions.