PhotoPrism

Media rootless 2 containers

photoprism docker.io/photoprism/photoprism:latest · 2342:2342

mariadb docker.io/mariadb:11

Kubernetes YAML

apiVersion: v1
kind: Pod
metadata:
  name: photoprism
  labels:
    app: photoprism
spec:
  restartPolicy: Always
  containers:
  - name: photoprism
    image: docker.io/photoprism/photoprism:latest
    imagePullPolicy: Always
    ports:
    - containerPort: 2342
      hostPort: 2342
    env:
    - name: PHOTOPRISM_ADMIN_USER
      value: admin
    - name: PHOTOPRISM_ADMIN_PASSWORD
      value: DjIDYSaP7XvgefOHDGsHlA
    - name: PHOTOPRISM_SITE_URL
      value: http://localhost:2342/
    - name: PHOTOPRISM_DATABASE_DRIVER
      value: mysql
    - name: PHOTOPRISM_DATABASE_SERVER
      value: 127.0.0.1:3306
    - name: PHOTOPRISM_DATABASE_NAME
      value: photoprism
    - name: PHOTOPRISM_DATABASE_USER
      value: photoprism
    - name: PHOTOPRISM_DATABASE_PASSWORD
      value: DjIDYSaP7XvgefOHDGsHlA
    - name: TZ
      value: Europe/Vienna
    volumeMounts:
    - name: vol-0
      mountPath: /photoprism/originals
    - name: vol-1
      mountPath: /photoprism/storage
  - name: mariadb
    image: docker.io/mariadb:11
    env:
    - name: MARIADB_ROOT_PASSWORD
      value: C53SJjZmMdkoVRoQtLGyWA
    - name: MARIADB_USER
      value: photoprism
    - name: MARIADB_PASSWORD
      value: DjIDYSaP7XvgefOHDGsHlA
    - name: MARIADB_DATABASE
      value: photoprism
    volumeMounts:
    - name: vol-2
      mountPath: /var/lib/mysql
    securityContext:
      runAsUser: 999
      runAsGroup: 999
  volumes:
  - name: vol-0
    persistentVolumeClaim:
      claimName: photoprism-originals
  - name: vol-1
    persistentVolumeClaim:
      claimName: photoprism-storage
  - name: vol-2
    persistentVolumeClaim:
      claimName: photoprism-db

Deployment Guide rootless

Operating System:

Prerequisites once as root

0. Install Podman

apt update && apt install -y podman

1. Create user (if not existing)

useradd -m -s /bin/bash 
passwd

2. Enable linger (service runs after reboot without login)

loginctl enable-linger

↪

Switch to deployment user

su -

Use su - with the dash — this creates a proper login shell as . Without the dash, root environment variables carry over and rootless Podman will not work correctly.

As deployment user

Fix environment for rootless systemd (new users only — skip if already set)

Required once so systemctl --user works in non-login sessions.

cat << 'EOF' >> ~/.bashrc

# Fix for systemd user services (rootless Podman/systemctl)
export XDG_RUNTIME_DIR=/run/user/$(id -u)
export DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus
EOF
source ~/.bashrc

Save the YAML file

mkdir -p ~/.config/containers/
nano ~/.config/containers/photoprism.yaml

Test the pod (without autostart)

podman play kube ~/.config/containers/photoprism.yaml

# Check status:
podman pod ps && podman ps

# Stop:
podman play kube --down ~/.config/containers/photoprism.yaml

Create Quadlet .kube file

photoprism.kube

%h is a systemd home-directory specifier — do not replace it with ~/.

Save to ~/.config/containers/systemd/:

mkdir -p ~/.config/containers/systemd/
nano ~/.config/containers/systemd/photoprism.kube

Start systemd service

systemctl --user daemon-reload
systemctl --user start photoprism.service

Status & Logs

systemctl --user status photoprism.service
journalctl --user -u photoprism.service -f
podman pod ps
podman ps

Enable automatic image updates optional

Requires AutoUpdate=registry in the .kube file. Podman then checks for new images and restarts the pod automatically:

systemctl --user enable --now podman.socket
systemctl --user daemon-reload
systemctl --user enable --now podman-auto-update.timer

# Check status:
systemctl --user status podman-auto-update.timer

# Trigger manually:
podman auto-update

Useful Tips

Ports < 1024 (e.g. 80, 443)

Rootless cannot open privileged ports. Solution:

sysctl net.ipv4.ip_unprivileged_port_start=80

Make persistent in /etc/sysctl.d/99-podman.conf.

Containers communicate via localhost

All containers in the pod share the same network namespace. Always use localhost, not container names.

# Correct (e.g. app → db):
localhost:5432

# Wrong (doesn't work in a pod):
db-container:5432

List open ports

Which ports is the running pod listening on?

podman port photoprism-pod

Custom DNS for the pod

Set a custom DNS server (e.g. local Pi-hole):

# In YAML under spec.dnsConfig:
spec:
  dnsConfig:
    nameservers:
      - 192.168.1.x

Set volume ownership

Fix permission errors by adjusting UID/GID in the user namespace:

podman unshare chown 1000:1000 /path/to/volume

SELinux volume labels

On SELinux systems (RHEL, Fedora) set the volume suffix:

/host/path:/container/path:Z   # private
/host/path:/container/path:z   # shared

List all volumes

podman volume ls
podman volume inspect <volume-name>

Volume backup

Back up data from a named volume:

podman run --rm \
  -v <volume-name>:/data:ro \
  -v $(pwd):/backup \
  busybox tar czf /backup/backup.tar.gz /data

Cleanup

Remove unused images, containers and volumes:

podman system prune -f        # containers + images
podman image prune -f         # untagged images only
podman volume prune -f        # unused volumes

Manual update

Pull a new image version and restart the pod:

podman pull <image>:<tag>
podman play kube --replace \
  ~/.config/containers/photoprism.yaml

Check for outdated images

List local images and test auto-update without applying:

podman images
podman auto-update --dry-run

Shell into a running container

podman exec -it photoprism-<container> /bin/sh
# or bash:
podman exec -it photoprism-<container> /bin/bash

Follow live logs

# All containers in the pod:
podman pod logs -f photoprism-pod

# Single container:
podman logs -f photoprism-<container>

Pod info & resource usage

podman pod inspect photoprism-pod
podman stats photoprism-pod

Restart pod without data loss

podman pod restart photoprism-pod

# or via systemd:
systemctl --user restart photoprism.service

Stop & remove pod

podman pod stop photoprism-pod
podman pod rm photoprism-pod

All in one

podman pod stop photoprism-pod && podman pod rm photoprism-pod

Customize this stack

Change ports, volumes, environment variables and more in the generator.

Open in Generator