Skip to content
Klutch.sh Docs

Deploying a PhotoPrism App

Introduction

PhotoPrism is an open-source, AI-powered photo manager for browsing, organizing, and sharing your media. Deploying PhotoPrism with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for originals, sidecars, and indexes—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample API usage, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your PhotoPrism Dockerfile (GitHub is the only supported git source)
  • Optional: MariaDB/MySQL database if you prefer it over SQLite for metadata (deploy as a Klutch.sh TCP app on port 8000; connect on 3306)
  • Storage sizing for originals, sidecars, and cache

For onboarding, see the Quick Start.

Architecture and ports

PhotoPrism serves HTTP on internal port 2342; choose HTTP traffic and set the internal port to 2342. Persistent storage is required for photos and indexes. For heavier installs, externalize the database; otherwise SQLite can work for small libraries.

Repository layout

photoprism/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub:

Terminal window
docker build -t photoprism-local .
docker run -p 2342:2342 \
  -e PHOTOPRISM_ADMIN_PASSWORD=changeme \
  photoprism-local

Dockerfile for PhotoPrism (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM photoprism/photoprism:latest


ENV PORT=2342


EXPOSE 2342
CMD ["photoprism", "start", "--port", "2342"]

Notes:

  • Pin the image tag (e.g., photoprism/photoprism:latest or specific version) for stability; update intentionally.
  • Use env vars to point to MariaDB/MySQL if you don’t want SQLite.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • PORT=2342
  • PHOTOPRISM_ADMIN_PASSWORD=<strong-password>
  • PHOTOPRISM_SITE_URL=https://example-app.klutch.sh
  • DB (choose one):
    • MariaDB/MySQL: PHOTOPRISM_DATABASE_DRIVER=mysql, PHOTOPRISM_DATABASE_SERVER=<db-host>:3306, PHOTOPRISM_DATABASE_NAME=<db>, PHOTOPRISM_DATABASE_USER=<user>, PHOTOPRISM_DATABASE_PASSWORD=<password>
    • SQLite (default): no DB vars required
  • Optional: PHOTOPRISM_ORIGINALS_LIMIT, PHOTOPRISM_READONLY=false, PHOTOPRISM_HTTP_COMPRESSION=gzip

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_START_CMD=photoprism start --port 2342

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /photoprism/originals — original photos.
  • /photoprism/storage — cache, index, sidecars, and SQLite database (if used).
  • /photoprism/import — optional import folder.

Ensure these paths are writable inside the container.

Deploy PhotoPrism on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 2342.
  4. Add the environment variables above, including database settings if you use MariaDB/MySQL.
  5. Attach persistent volumes for /photoprism/originals, /photoprism/storage, and /photoprism/import sized for your library and cache.
  6. Deploy. Your PhotoPrism instance will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

Sample API usage

List albums (requires authentication; replace token with a valid bearer token):

Terminal window
curl -X GET "https://example-app.klutch.sh/api/v1/albums" \
  -H "Authorization: Bearer <token>"

Trigger index (if API exposed):

Terminal window
curl -X POST "https://example-app.klutch.sh/api/v1/index" \
  -H "Authorization: Bearer <token>"

Health checks and production tips

  • Add an HTTP probe to /api/v1/config or / for readiness.
  • Enforce HTTPS at the edge; forward internally to port 2342.
  • Keep DB credentials and admin password in Klutch.sh secrets; rotate regularly.
  • Monitor storage usage on /photoprism/originals and /photoprism/storage; resize before they fill.
  • Pin image versions and test upgrades in staging; back up DB and volumes before updates.

PhotoPrism on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, port 2342 configured, and your database/storage attached, you can deliver a secure, AI-powered photo library without extra YAML or workflow overhead.