Install Photoprism with Podman

Testez-le maintenant pour 1 euro seulement !

Vous avez de grands projets d’hébergement avec beaucoup de ressources ? Avec le CloudServer (VPS) de hosting.fr, ce n’est pas un problème. Grâce à notre vaste gamme d’outils d’hébergement, vous bénéficiez d’une liberté absolue. Bien entendu, vous pouvez choisir librement le système d’exploitation en appuyant sur un bouton.

Réserver un serveur cloud maintenant

Introduction

PhotoPrism is a web software for managing photos that can be run on a personal server. The developers recommend running the software in a container and provide a docker-compose file. Additionally, an nginx web server is used to manage TLS and redirect requests to the Photoprism container.

Prerequisites

You have a hosting.fr cloud server with a valid DNS record, for example demo.mustermann-domain.de.
Privileged shell access on the system.

Install Packages

apt update
apt install podman podman-compose

Install Photoprism

Create a directory for the container

mkdir /opt/photoprism

Download the Photoprism compose file

cd /opt/photoprism
wget https://dl.photoprism.app/podman/docker-compose.yml

Edit the docker-compose.yml file and adjust the following values:

restart: always
Containers with restart: always will automatically start on Debian boot
127.0.0.1:2342:2342
Bind Photoprism to localhost because nginx should act as a frontend here
PHOTOPRISM_DISABLE_PLACES: true
Disables geolocation requests by developers. Must be set to false if maps are to be displayed.
PHOTOPRISM_ADMIN_PASSWORD
The admin password for web login
MARIADB_PASSWORD or MARIADB_ROOT_PASSWORD
Set the database passwords.

. . .
    image: photoprism/photoprism:latest
    container_name: photoprism
    ## Do not enable automatic restarts until Photoprism has been properly configured and tested!
    ## If the service gets stuck in a restart loop, it indicates a memory, filesystem, network, or database problem:
    ## https://docs.photoprism.app/getting-started/troubleshooting/#fatal-server-errors
    # restart: unless-stopped
    restart: always
. . .
    ports:
      ## Web server port mapping in "Host:Container" format. To use a different port, change the host port
      ## on the left and keep the container port, e.g., "80:2342" (for HTTP) or "443:2342" (for HTTPS):
      - "127.0.0.1:2342:2342"
. . .
PHOTOPRISM_ADMIN_PASSWORD: "<new admin password>"
. . .
PHOTOPRISM_DISABLE_PLACES: "true"
. . .
PHOTOPRISM_DATABASE_PASSWORD: "<photoprism database password>"
. . .
  ## MariaDB database server (recommended)
  ## see https://docs.photoprism.app/getting-started/faq/#should-i-use-sqlite-mariadb-or-mysql
  mariadb:
    ## If MariaDB gets stuck in a restart loop, it indicates a memory or filesystem problem:
    ## https://docs.photoprism.app/getting-started/troubleshooting/#fatal-server-errors
    # restart: unless-stopped
    restart: always
. . .
MARIADB_DATABASE: "photoprism"
MARIADB_USER: "photoprism"
MARIADB_PASSWORD: "<photoprism database password>"
MARIADB_ROOT_PASSWORD: "<database root password>"
. . .

Start the container

podman-compose up -d

The different containers will be downloaded and started. Once completed, you should see two running containers with

podman ps

Test Photoprism

To test Photoprism, a port-forwarding ssh connection must be used:

ssh -L 127.0.0.1:2342:127.0.0.1:2342 root@demo.mustermann-domain.de

You can now access the Photoprism page in the browser at http://127.0.0.1:2342 to check if everything works.

Install Nginx

Install Nginx with Let’s Encrypt certificates install.

After the domain has been configured in Nginx for Let’s Encrypt TLS, you need to extend the configuration for Photoprism. For this, the file /etc/nginx/sites-enabled/demo.mustermann-domain.de must be modified

server {
    server_name demo.mustermann-domain.de;

    include snippets/mozilla-modern.conf;
    . . .

    # allow uploading large files
    client_max_body_size 50000M;

    # Set headers
    proxy_set_header Host              $http_host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # enable websockets: http://nginx.org/en/docs/http/websocket.html
    proxy_http_version 1.1;
    proxy_set_header   Upgrade    $http_upgrade;
    proxy_set_header   Connection "upgrade";
    proxy_redirect     off;

    # set timeout
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;
    send_timeout       600s;

    location / {
        proxy_pass http://127.0.0.1:2342;
    }
}

Then check the Nginx configuration with nginx-t for validity and restart the web server (systemctl restart nginx.service). Finally, check if Photoprism is now accessible via https://demo.mustermann-domain.de.

Create a New User in the Community Edition

In the Community Edition, there are several limitations regarding multi-user operation:

Only users with the administrator role can be created
User management only works via the CLI

You can configure a new user with the following command:

podman-compose exec photoprism photoprism users add --password <password> <username>

Structuring PhotoPrism Storage and Volumes

Before using PhotoPrism in production, it is essential to define a clear and durable storage layout. Unlike Nextcloud memories, PhotoPrism supports several data types, including original photos and videos, generated previews and indexes, and database files. Storing all of these in well-defined directories helps prevent data loss, simplifies maintenance, and improves performance.

A recommended structure includes separate directories for original media, PhotoPrism’s internal storage, and the database. For example, originals can be stored in /srv/photoprism/originals, while /srv/photoprism/storage can hold thumbnails, indexes, and cache files. Database data (MariaDB) should be stored in its own directory, such as /srv/photoprism/database. These directories should be mounted as volumes in the compose configuration.

Ensure that the container has appropriate read and write permissions for all mounted paths. For large photo libraries, placing these directories on a dedicated data disk or SSD is strongly recommended. Proper volume planning at the beginning avoids migration issues later and makes backups and restores significantly easier.

Backups, Upgrades, and Maintenance Best Practices

Running PhotoPrism reliably requires a basic but consistent maintenance strategy. The most essential task is regular backups. At a minimum, you should back up three components: the photo originals, the PhotoPrism storage directory, and the database. Originals can be backed up using file-level backups, while MariaDB should be backed up using scheduled SQL dumps.

Before applying updates, always create a fresh backup. To update PhotoPrism, stop the running containers, pull the latest container images, and restart the services. After the update, verify that PhotoPrism starts correctly, the web interface is accessible, and photos load as expected.

Configuration files, such as the compose file and Nginx configuration, should also be backed up or stored in version control. This allows you to recover from misconfigurations or failed updates quickly. Performing maintenance in a controlled manner reduces downtime and ensures data integrity over time.

Common Troubleshooting Scenarios and Solutions

Even with a correct installation, operational issues can occur. Use the checks below to diagnose problems quickly and consistently.

Containers restarting repeatedly (restart loop)

Check logs first: podman logs (or podman-compose logs if applicable).
Confirm environment variables are set correctly (especially database host/user/password and PhotoPrism admin credentials).
Verify system resources: ensure sufficient disk space, RAM, and CPU—indexing can be resource-intensive.
Ensure the database container is healthy and reachable before PhotoPrism starts.

PhotoPrism not reachable behind Nginx

Confirm PhotoPrism is listening locally on the expected address/port (typically 127.0.0.1:2342)
Verify the Nginx proxy_pass target points to http://127.0.0.1:2342.
Check firewall rules to ensure Nginx can reach the local backend (and that the backend port is not exposed publicly).
Review Nginx error logs to identify proxy, TLS, or upstream connectivity issues.

Photos not showing or uploads failing (permissions and paths)

Validate volume paths: confirm the mounted directories match your intended originals, import, and storage locations.
Confirm directory permissions: PhotoPrism must be able to read originals and write to storage/import as required.
If uploads fail for larger files, ensure Nginx supports them: Set a sufficient client_max_body_size and increase proxy timeouts if uploads or indexing requests take longer than default limits.

Slow performance during indexing

Expect high CPU/disk usage during initial scans; run indexing during low-traffic periods if possible.
Consider faster storage (SSD) for storage and database volumes.
Reduce the server’s concurrent workload while PhotoPrism is building indexes and previews.

Security Hardening and Operational Controls

Beyond TLS encryption, additional security measures should be applied to protect a PhotoPrism installation. SSH access should be restricted using key-based authentication, and root login over SSH should be disabled. Firewall rules should allow only required ports, typically 80 and 443, while keeping the PhotoPrism application port inaccessible from the public network.

Running PhotoPrism behind Nginx adds a vital security layer, but system-level protections are equally important. Keep the operating system and container images up to date with security patches. Avoid storing credentials in plain text outside secured configuration files.

For operational stability, monitor system resources, including disk usage, memory, and CPU load. Photo indexing and face recognition can be resource-intensive, especially for large libraries. Setting reasonable resource limits and monitoring usage helps prevent service disruptions. These practices improve both security and long-term reliability.

Don't hesitate to subscribe to our newsletter

Thank you for subscribing to the hosting.fr newsletter.