Path-Based Proxy

Instead of giving every instance its own hostname and certificate, a PhotoPrism® Portal can serve them all under a single domain and forward each request based on the first path segment. This is the shared-domain layout: one hostname, one certificate, one entry point for the whole cluster.

How Routing Works

With the proxy enabled, the Portal forwards requests under a path prefix (default /i/) to the matching instance:

https://portal.example.com/i/acme/     →  the "acme" instance
https://portal.example.com/i/contoso/  →  the "contoso" instance

The Portal resolves the name after the prefix to a registered instance and proxies the request to that instance’s internal address. Specifically:

• Name resolution. The segment after /i/ is looked up in the cluster registry and forwarded to the instance’s advertise URL. The Portal adds the standard forwarding headers (X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto) so the instance generates correct links.
• Trailing slash. A request to /i/acme (no trailing slash) gets a temporary redirect to /i/acme/ with the query string preserved; deeper paths such as /i/acme/library/ are forwarded as-is, so they are not pushed through extra redirects.
• WebDAV. WebDAV methods (PROPFIND, COPY, MOVE, LOCK, …) are proxied too, so file access through /i/acme/originals/ keeps working. WebDAV clients must include the same base path before /originals/.
• Unknown names. A name that does not resolve — or an inactive instance — returns a generic not found response, so the cluster does not reveal which instances exist.
• Name rules. Instance names are lowercase letters, digits, and hyphens, 1–32 characters ([a-z0-9-]{1,32}); an invalid or ambiguously encoded name returns not found.

Enabling the Proxy

Turn on path routing on the Portal and, optionally, change the path prefix:

services:
  portal:
    image: photoprism/portal:latest
    environment:
      PHOTOPRISM_NODE_ROLE: "portal"
      PHOTOPRISM_CLUSTER_DOMAIN: "portal.example.com"
      PHOTOPRISM_SITE_URL: "https://portal.example.com/"
      PHOTOPRISM_PORTAL_PROXY: "true"
      PHOTOPRISM_PORTAL_PROXY_URI: "/i/"

PHOTOPRISM_PORTAL_PROXY enables the proxy; PHOTOPRISM_PORTAL_PROXY_URI sets the path prefix (default /i/; absolute proxy URIs are also supported). See Config Options.

Configuring Each Instance

Each instance must advertise the public path it is served under, and an internal address the Portal can reach:

services:
  acme:
    image: photoprism/pro:latest
    environment:
      PHOTOPRISM_NODE_ROLE: "instance"
      PHOTOPRISM_NODE_NAME: "acme"
      PHOTOPRISM_SITE_URL: "https://portal.example.com/i/acme/"
      PHOTOPRISM_ADVERTISE_URL: "http://acme:2342/"

• PHOTOPRISM_SITE_URL is the canonical public URL, including the /i/<name>/ path and a trailing slash. Generated links, redirects, and browser storage are derived from it, so it must match the path the Portal serves the instance under.
• PHOTOPRISM_ADVERTISE_URL is the internal address the Portal forwards to (for example a service DNS name). It must be a host-level URL (scheme and host only, no path) and may use plain HTTP on a trusted, cluster-internal network; public URLs must use HTTPS.

Combining with a Web Overlay

Path-based routing combines well with a Web Overlay: you can publish a static landing page at the shared root (https://portal.example.com/) and a tenant-specific start page under each instance path (https://portal.example.com/i/acme/). When you use an overlay on an instance path, keep the instance’s PHOTOPRISM_SITE_URL set to that same path so links and storage stay scoped to the correct tenant.

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:

• Portal Quickstart Guide
• Portal Config Options
• Portal Web Overlay
• PhotoPrism® User Guide
• PhotoPrism® Pro Knowledge Base