PhotoPrism Portal: Config Options

This page documents the configuration options that are specific to running a PhotoPrism® Portal and its cluster instances. The Portal reads the same PHOTOPRISM_* environment variables as a standalone instance, plus a set of cluster options that control node roles, shared-domain routing, database provisioning, and cluster authentication.

For the complete list of general options shared with standalone instances, see the PhotoPrism® Config Options reference. The options below are the ones that matter for a Portal-managed cluster.

Node Role & Cluster Identity

Every node in a cluster has a role and belongs to one cluster domain. The Portal node uses the reserved portal role; tenant instances use instance.

Variable	Applies to	Default	Description
`PHOTOPRISM_NODE_ROLE`	both	`instance`	Set to `portal` on the Portal node; `instance` on tenants. The role determines which cluster features run.
`PHOTOPRISM_NODE_NAME`	instance	derived from hostname	Stable name that identifies a tenant and, in shared-domain mode, its `/i/<name>/` path. Lowercase, 1–63 chars.
`PHOTOPRISM_CLUSTER_DOMAIN`	both	—	Lowercase DNS domain that identifies the cluster and seeds default URLs (for example `portal.example.com`).
`PHOTOPRISM_SITE_URL`	both	derived	Public URL of the node. Portal: `https://portal.example.com/`; tenant: its hostname or `/i/<name>/` path.
`PHOTOPRISM_ADVERTISE_URL`	instance	derived	Internal address at which the Portal can reach the instance (for example `http://media:2342/`).

Public URLs must use HTTPS — secure connections are a strict requirement for single sign-on. Internal Portal↔instance traffic may use plain HTTP over a trusted, cluster-internal network.

Cluster Secrets & Registration

Instances register with the Portal using a shared join token, then receive their own credentials. These options configure that handshake and the trusted-network ranges.

Variable	Applies to	Default	Description
`PHOTOPRISM_JOIN_TOKEN`	both	—	Shared secret used for first-time tenant registration. Must be at least 24 characters long.
`PHOTOPRISM_PORTAL_URL`	instance	derived	Internal Portal URL a tenant calls to register. Defaults to `https://portal.<cluster-domain>`.
`PHOTOPRISM_CLUSTER_CIDR`	both	`10.0.0.0/8`	Network range considered part of the cluster. Set on the Portal; tenants inherit it via the cluster secret.
`PHOTOPRISM_TRUSTED_PROXY`	both	`10.0.0.0/8`	Proxy range trusted for forwarded headers. Set on the Portal; tenants inherit it via the cluster secret.

Registration is idempotent — a new instance receives credentials on first boot, and an existing instance simply confirms its registration on restart. The join token is only used for the first registration of a new node name; later changes require a valid node OAuth token.

Shared-Domain Proxy

When the Portal serves all instances under one hostname, it forwards requests based on the first path segment (/i/<name>/).

Variable	Applies to	Default	Description
`PHOTOPRISM_PORTAL_PROXY`	portal	`false`	Enables shared-domain path routing. Set to `true` to proxy instances under one domain.
`PHOTOPRISM_PORTAL_PROXY_URI`	portal	`/i/`	Path prefix used to route tenant requests. Absolute proxy URIs are also supported.
`PHOTOPRISM_FRONTEND_URI`	portal	`/portal/admin`	Base path of the Portal management UI and the default root-redirect target (for example its login).

Each instance sets its PHOTOPRISM_SITE_URL to the matching path, for example https://portal.example.com/i/media/. Unknown names return a generic not found response, so the cluster does not reveal which instances exist. For routing details, name rules, and instance isolation, see Path-Based Proxy.

Database & Provisioning

The Portal and its tenants share one database server. The Portal can provision a database and user for each tenant automatically, or you can pre-create them.

Variable	Applies to	Default	Description
`PHOTOPRISM_DATABASE_DRIVER`	both	`sqlite`	Use `mysql` for the shared MariaDB/MySQL server (required for a multi-instance cluster).
`PHOTOPRISM_DATABASE_SERVER`	both	—	Database host and port, for example `mariadb:3306`.
`PHOTOPRISM_DATABASE_NAME`	portal	`photoprism`	The Portal’s own database. Must already exist before the Portal starts (default `photoprism_portal` in chart deployments).
`PHOTOPRISM_DATABASE_USER`	portal	—	The Portal’s database user.
`PHOTOPRISM_DATABASE_PASSWORD`	portal	—	The Portal’s database password.
`PHOTOPRISM_DATABASE_PROVISION_DSN`	portal	—	Privileged DSN the Portal uses to create per-tenant databases and users, for example `root:secret@tcp(mariadb:3306)/`. Kept on the Portal only.
`PHOTOPRISM_DATABASE_PROVISION_PREFIX`	portal	`cluster_`	Prefix for provisioned database and user names. Use a per-environment value when sharing one server.

Provisioned databases and users are named automatically from the cluster and node identifiers. The administrative provisioning connection is used only to create and rotate these credentials and is never shared with instances. Tenants leave their PHOTOPRISM_DATABASE_* values blank to receive Portal-provisioned credentials at registration.

For the recommended database baseline and how to run it under an operator, see MariaDB Enterprise.

Cluster Authentication (OIDC)

The Portal is the cluster’s OpenID Provider. Cluster authentication is enabled by default, so a freshly deployed tenant can sign users in through the Portal without any per-tenant client setup. For an overview of the authentication and authorization options and how to choose between them, see Access & Authentication.

Variable	Applies to	Default	Description
`PHOTOPRISM_DISABLE_OIDC`	both	`false`	Keep OIDC enabled on every cluster member; cluster sign-in requires it.
`PHOTOPRISM_CLUSTER_OIDC`	instance	`true`	Single-pass mode: the tenant derives its OIDC client, secret, and issuer from its cluster node credentials.
`PHOTOPRISM_OIDC_REDIRECT`	instance	`true` on tenants, `false` portal	Send users straight to the Portal login (tenant), or keep a local login form with a provider button (Portal).
`PHOTOPRISM_OIDC_URI`	instance	empty	Leave empty on tenants — an explicit value overrides the cluster derivation and breaks Portal-mediated sign-in.
`PHOTOPRISM_OIDC_CLIENT`	instance	empty	Leave empty on tenants (derived from the node credentials).
`PHOTOPRISM_OIDC_SECRET`	instance	empty	Leave empty on tenants (derived from the node credentials).

Out of the box — a Portal plus one or more instances, with no upstream provider — users sign in with local Portal accounts and reach their instances through the cluster flow. Add an upstream identity provider on the Portal when you want federated single sign-on.

Upstream Identity Provider

To add federated single sign-on, configure an upstream OpenID Connect provider on the Portal (not on the tenants). This adds a “Continue with <provider>” button to the Portal login and enables security-group-based admission.

Variable	Applies to	Default	Description
`PHOTOPRISM_OIDC_URI`	portal	empty	Issuer URL of your identity provider (its `/.well-known/openid-configuration`).
`PHOTOPRISM_OIDC_CLIENT`	portal	empty	OAuth client ID registered with your provider for the Portal.
`PHOTOPRISM_OIDC_SECRET`	portal	empty	OAuth client secret for that client.
`PHOTOPRISM_OIDC_PROVIDER`	portal	empty	Display name of the provider shown on the login button.

Because tenants run in single-pass cluster mode, the upstream issuer, client, and secret are configured on the Portal only. See Cluster Authentication & Access Control for how sign-in and access grants work.

Mapping Security Groups to Roles

When users authenticate through an upstream provider, their security-group memberships can be mapped to a login role on each instance.

Variable	Applies to	Default	Description
`PHOTOPRISM_OIDC_GROUP_CLAIM`	instance	`groups`	ID-token claim that carries group memberships.
`PHOTOPRISM_CLUSTER_ALLOW_GROUP_ROLES`	instance	empty	Comma- or space-separated `<group>=<role>` pairs, e.g. `photoprism-admins=admin,photoprism-viewers=viewer`.
`PHOTOPRISM_OIDC_GROUP`	instance	empty	Restrict sign-in to members of at least one listed group (empty allows any).
`PHOTOPRISM_OIDC_ROLE`	instance	`guest`	Account role assigned when no group matches.

Assignable roles are admin, manager, user, contributor, viewer, and guest. The operator role cluster_admin and the anonymous visitor role can never be granted through a group mapping. An explicit per-user instance grant always takes precedence over a group mapping.

Single Sign-Out (RP-Initiated Logout)

By default, signing out ends only the local PhotoPrism session; the upstream provider session stays active, so the next sign-in is silently re-authenticated. Enabling RP-initiated logout ends the provider session too.

Variable	Applies to	Default	Description
`PHOTOPRISM_OIDC_LOGOUT`	both	`false`	When `true`, sign-out redirects through the provider’s `end_session_endpoint` to end the SSO session.

Notes:

Identity-provider prerequisite (required): the provider’s client must list the page PhotoPrism returns to after logout in its Valid Post Logout Redirect URIs. PhotoPrism sends the instance login page as the post_logout_redirect_uri (for example https://portal.example.com/i/<tenant>/library/login). Register each tenant’s login URL, or a shared-domain wildcard (https://portal.example.com/*). If the URI is not registered, the provider rejects the logout with “Invalid redirect uri” and the session is not ended.
The provider must advertise an end_session_endpoint in its discovery document; otherwise PhotoPrism falls back to a local-only sign-out.
In a cluster, the sign-out cascades instance → Portal → upstream provider, so enable PHOTOPRISM_OIDC_LOGOUT on both the tenant instances and the Portal for the chain to reach the upstream provider.

LDAP / Active Directory

As an alternative to (or alongside) an upstream OpenID Connect provider, the Portal can authenticate users against an LDAP or Active Directory server, so users sign in with their existing directory credentials. Configure LDAP on the Portal — it authenticates on behalf of every instance, the same way it does for local and OIDC logins.

Variable	Default	Description
`PHOTOPRISM_LDAP_URI`	empty	Directory URI, for example `ldaps://ad.example.com:636` for LDAP over TLS. Setting it enables LDAP.
`PHOTOPRISM_LDAP_CERT`	empty	TLS certificate file name (`.pem`) for the directory connection.
`PHOTOPRISM_LDAP_INSECURE`	`false`	Skip TLS certificate verification when using LDAPS (not recommended).
`PHOTOPRISM_LDAP_SYNC`	`false`	Re-read name, email, and role from the directory on every login, so changes propagate automatically.
`PHOTOPRISM_LDAP_BIND`	`simple`	Authentication type (`simple`, `md5`).
`PHOTOPRISM_LDAP_BIND_DN`	`userprincipalname`	Username attribute DN, for example `cn` or `userprincipalname`.
`PHOTOPRISM_LDAP_BASE_DN`	empty	Directory base DN, for example `dc=example,dc=com`.
`PHOTOPRISM_LDAP_ROLE`	empty	Default account role when no group matches (`admin`, `manager`, `user`, `contributor`, `viewer`, `guest`).
`PHOTOPRISM_LDAP_ROLE_DN`	empty	Group/attribute DN pattern whose matches become group identifiers for role and instance admission.
`PHOTOPRISM_LDAP_NOLOGIN`	`false`	Disable web login for new LDAP users by default.
`PHOTOPRISM_LDAP_NOLOGIN_DN`	empty	Attribute DN whose members are refused login at the Portal.
`PHOTOPRISM_DISABLE_LDAP`	`false`	Disable LDAP authentication entirely.

Directory groups matched by PHOTOPRISM_LDAP_ROLE_DN feed the same group-to-role admission as upstream OIDC groups (see Mapping Security Groups to Roles), so a user’s directory groups can grant access to the instances mapped to them. LDAP attribute names are not case-sensitive.

For the complete option list, bind examples, and a Docker Compose snippet, see the LDAP and Active Directory guide.

Theme, Backups & Other Options

Variable	Applies to	Default	Description
`PHOTOPRISM_THEME_URL`	portal	empty	URL of a branding theme archive the Portal downloads and distributes to instances. Leave empty to disable.
`PHOTOPRISM_BACKUP_*`	both	`daily`	Database/index backup schedule and options (see the general config reference).
`PHOTOPRISM_VISION_API`	both	`false`	When `true` on the Portal, exposes shared Vision API endpoints so tenants can offload AI models.
`PHOTOPRISM_VISION_KEY`	both	derived	Shared secret for the Vision API. Set the same value on the Portal and on any tenant that uses it.
`PHOTOPRISM_USAGE_INFO`	both	`true`	Shows storage-usage information in the UI.

For how the Portal distributes a branding theme to every instance — the theme directories, login-page and logo customization, and the provisioning flow — see Themes & Branding.

For a Portal-hosted Vision service, set PHOTOPRISM_VISION_API=true and a shared PHOTOPRISM_VISION_KEY on the Portal, then point each tenant at https://portal.example.com/api/v1/vision with the same key. See the AI Services section of the User Guide.

PhotoPrism® Documentation

For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide: