PhotoPrism® Portal is the cluster coordinator: it authenticates users (locally or against an upstream identity provider), proxies tenant instances under a shared domain at /i/<name>/, provisions per-tenant databases, and acts as the OpenID Provider that signs users in to each instance.

This guide gives a generic overview. For orchestrated deployments, see Kubernetes and OpenShift. For the full list of settings, see Config Options.

System Requirements

Run the Portal on a 64-bit host with at least 2 cores and 4 GB of memory; each tenant instance has its own resource needs on top of that. The Portal and its tenants share one database server — we recommend MariaDB Enterprise or MariaDB 11.4+.

Architecture

A cluster has one Portal node and one or more instance (tenant) nodes:

  • The Portal terminates the shared domain (for example https://portal.example.com/) and proxies each tenant under /i/<name>/.
  • The Portal is the cluster’s OpenID Provider: instances authenticate their users against the Portal using cluster OIDC, with no per-tenant client setup.
  • The Portal provisions a database and user for each tenant and stores cluster membership in its own database.

1. Start the Portal

Set the node role to portal, give it a stable cluster domain, and a join token that new instances use to register:

services:
  portal:
    image: photoprism/portal:latest
    environment:
      PHOTOPRISM_NODE_ROLE: "portal"
      PHOTOPRISM_CLUSTER_DOMAIN: "portal.example.com"
      PHOTOPRISM_ADVERTISE_URL: "https://portal.example.com/"
      PHOTOPRISM_JOIN_TOKEN: "<a-strong-shared-secret>"
      PHOTOPRISM_PORTAL_PROXY: "true"
      PHOTOPRISM_PORTAL_PROXY_URI: "/i/"
      PHOTOPRISM_ADMIN_PASSWORD: "<portal-admin-password>"
      PHOTOPRISM_DATABASE_DRIVER: "mysql"
      PHOTOPRISM_DATABASE_SERVER: "mariadb:3306"
      PHOTOPRISM_DATABASE_NAME: "photoprism_portal"
      PHOTOPRISM_DATABASE_USER: "portal"
      PHOTOPRISM_DATABASE_PASSWORD: "<db-password>"

Cluster authentication is enabled by default, so users can sign in to their instances through the Portal immediately. To add federated single sign-on, configure an upstream identity provider on the Portal (see Config Options).

2. Join an Instance

Each tenant runs a standard PhotoPrism instance configured to join the cluster. Cluster OIDC (single-pass) derives the instance’s OpenID client and issuer from its cluster credentials — leave PHOTOPRISM_OIDC_URI, _CLIENT, and _SECRET empty:

services:
  media:
    image: photoprism/photoprism:latest
    environment:
      PHOTOPRISM_NODE_ROLE: "instance"
      PHOTOPRISM_NODE_NAME: "media"
      PHOTOPRISM_CLUSTER_DOMAIN: "portal.example.com"
      PHOTOPRISM_PORTAL_URL: "http://portal:2342/"
      PHOTOPRISM_JOIN_TOKEN: "<the-same-shared-secret>"
      PHOTOPRISM_CLUSTER_OIDC: "true"
      PHOTOPRISM_OIDC_REDIRECT: "true"

On first start the instance registers with the Portal, receives its database credentials, and becomes reachable at https://portal.example.com/i/media/.

3. Sign In

Open the shared domain (https://portal.example.com/). After signing in, users are sent to their instance, or to the instance chooser when they can reach more than one. Signing out ends the Portal session and, when an upstream provider is configured with RP-initiated logout, the upstream session too.

Learn more chevron_right