Skip to content

Configuration

Proton Faces is configured entirely through environment variables. The app and indexer containers share most of them; the bridge has its own (set in compose.yml, mostly Proton SDK env vars).

Compose-level (host-side)

These are read by docker-compose.yml itself, not by the containers:

Variable Default Description
DATA_MOUNT named volume data Host path or :volume that backs DATA_DIR. On a server with a big disk, set DATA_MOUNT=/srv/proton-faces/data. The directory must be writable by UID 1000.
AUTH_SESSION_MOUNT ./credentials/auth-session.json Host path to the Proton session file (issue #32). The file is bind-mounted only into the proton-bridge container at /data/auth-session.json — the indexer and app containers have no path to it. The mount is writable because the SDK refreshes the file on disk. Override if your session lives elsewhere; the directory must be readable (and writable for refresh) by UID 1000.
PORT 8080 Host port the web UI binds to.
BIND_ADDRESS 0.0.0.0 Host address that port is published on. Behind a reverse proxy on the same host set 127.0.0.1: a Docker-published port bypasses host firewalls such as ufw, so the default would also serve plain HTTP beside the proxy.
SYNC_INTERVAL 300 Default seconds between timeline diffs.
SYNC_LIMIT 0 Default sync limit (0 = all photos).
WORKERS 3 Default number of recognition workers.
CLUSTER_INTERVAL 1800 Default seconds between people-clustering runs.
CLUSTER_MAX_FACES 5000 Max unassigned faces per clustering run (0 = no cap).
GPS_INTERVAL 21600 Default seconds between GPS/place enrichment runs.
ALBUM_FULL_RESCAN_SEC 21600 (6 h) How often (seconds) the albums sync runs a full photos-table rescan as a repair pass. Between rescans the sync is incremental (issue #95): only albums whose membership changed are recounted. Lower it to converge out-of-band edits faster at the cost of more scanning.
FACE_SIM_THRESHOLD 0.45 Default cosine similarity threshold for face auto-tagging.
MIN_CLUSTER_SIZE 2 Default minimum faces to form a person cluster.
OTEL_EXPORTER_OTLP_ENDPOINT unset (off) OTLP/HTTP base URL of your collector, such as http://otel-collector:4318. Set it to export metrics from app and indexer. See Observability.
OTEL_SDK_DISABLED false true turns metrics export off even with an endpoint set.
OTEL_METRIC_EXPORT_INTERVAL 60000 Metrics export interval in milliseconds.
LOG_LEVEL INFO Default logging verbosity.
DEMO_ADMIN_PASSWORD proton-faces Password for the auto-created demo admin in demo mode.
RUN_INDEXER 0 Set 1 on the app service to start the in-process indexer (legacy single-process layout).
INDEXER_STATUS_PORT 8091 Internal-only port on the indexer container for its /status endpoint.
BRIDGE_CACHE_STALE_SEC 21600 (6 h) Age (seconds) at which the on-disk Proton SDK cache is flagged "stale" by the admin Server-checks panel. Only fires when full-res downloads are also failing. Lower it to surface stale caches earlier; raise it if your bridge is idle for longer than 6 h.
ORT_INTRA_OP_THREADS 1 Threads per ONNX Runtime session (CLIP). Default 1 prevents the indexer's workers + CLIP sessions from oversubscribing the CPU; raise only on a box with spare cores. OMP_NUM_THREADS=1 is set in compose for the OpenMP-backed kernels (insightface).
CLIP_BATCH_SIZE 4 Max photos embedded per CLIP session.run in the indexer when the pending queue is deep (issue #98). With ORT_INTRA_OP_THREADS=1, batch>1 reuses per-core work and raises indexer throughput during a bulk backlog at the same CPU quota. Set 1 to disable batching.
CLIP_BATCH_QUEUE_DEPTH 8 Pending-queue depth at which indexer workers switch from batch=1 to CLIP_BATCH_SIZE micro-batching. Below it (typical for interactive reclaims) workers embed one photo at a time to keep first-result latency low.
MODEL_IDLE_UNLOAD_SEC 900 Seconds the indexer may sit with no photo to process before it releases its ONNX sessions (CLIP image encoder + InsightFace — several hundred MB of RAM) and trims the heap. They reload on the next new photo, which then takes a few seconds longer. 0 keeps them loaded for the life of the process. Indexer only; the API's models follow WARM_MODELS.
WEBP_METHOD 4 WebP encoder effort for thumbnails/video posters. 6 (Pillow default) is the slowest; 4 is near-identical size at a fraction of the CPU (issue #101).
APP_MEM_LIMIT 6g Memory cap for the app container. Each uvicorn worker loads its own CLIP ONNX session (~838 MB RSS measured) + a per-worker matrix cache; 2 workers fit comfortably under 6 GiB. Lower it on small boxes if you also lower UVICORN_WORKERS.
APP_CPUS 2.0 CPU cap for the app container, so CLIP/search can't starve the other containers on the host.

In-container

Set inside compose.yml for each service. Most match the compose-level defaults above; the in-container values are set explicitly so the single-process dev path (python main.py on the host) works without docker compose.

Variable Default in app/indexer Description
DATA_DIR /data (in-container) Persistent data (thumbnails, SQLite, vectors). Hardcoded to /data in both containers; override only for local single-process dev.
MODELS_DIR /models (in-container) Where the ML models live (baked into the image). Override only for testing.
BRIDGE_URL http://proton-bridge:8090 Bridge container address (internal docker network).
PORT 8080 (in-container) Web UI port inside the app container.
INDEXER_STATUS_URL http://indexer:8091 Where the app container reads the indexer's status from. For local single-process dev with RUN_INDEXER=1, override to http://127.0.0.1:8091.
RUN_INDEXER 0 Set 1 on the app container to start the in-process indexer.
UVICORN_WORKERS 2 Number of uvicorn workers serving the API. Each worker lazily loads its own CLIP ONNX session (~838 MB RSS) + a per-worker matrix cache, so this is the dominant term in the app container's memory footprint. Keep low on memory-constrained hosts; raise on memory-rich ones. Ignored when RUN_INDEXER=1 (single-process mode).
WARM_MODELS 1 Pre-load the CLIP + InsightFace sessions in every uvicorn worker at startup (lifespan hook, issue #97) so the first /api/search and /api/search/face after a deploy/restart don't pay a multi-second model load inside a user request. Models are baked into the image and warmed at build time; this re-applies the per-process load in each worker. Set 0 to defer loading to the first request (tests/CLI use 0). A failed warm-up is logged and non-fatal — the lazy path remains the fallback.
LOG_LEVEL INFO Logging verbosity: DEBUG / INFO / WARNING / ERROR.
DEMO_MODE unset 1 enables demo mode (no real Proton account). Set automatically by the demo compose profile.
DEMO_ADMIN_PASSWORD unset → prompt Override the demo admin password.
DEMO_LOGIN_LOGS 0 Log the demo admin password source at WARN on first boot. The password itself is NEVER logged regardless of this flag. Set 1 to log whether the password came from DEMO_ADMIN_PASSWORD or the default.
DEMO_ALLOW_PUBLIC_THUMBS 0 Binary media endpoints (/thumb, /full, /cover, /crop) are secure by default: they require a bearer token or a short-lived signed URL from /api/sign. Set 1 to make them world-readable (the demo compose profile does this so static <img> tags keep working).
DEMO_DISABLE_ADMIN_AREA 0 404 every /api/admin/* route plus the self-service password (/api/auth/password) and 2FA (/api/auth/2fa/*) routes. The demo compose profile sets this so a shared-credential holder can't reconfigure the demo or change the shared password.

Auth

Variable Default Description
SIGNING_SECRET required (prod) HMAC key for the short-lived signed URLs on binary media endpoints (/thumb, /full, /cover, /crop). Required outside DEMO_MODE — the app refuses to start without it (compose.yml fails the app service with ${SIGNING_SECRET:?…}), so a known default can't be used to forge signed URLs and signed URLs stay valid across all uvicorn workers (default 2, see UVICORN_WORKERS). Generate with openssl rand -hex 32. In DEMO_MODE the app-demo compose service sets a fixed demo-signing-secret (demo content is public by design; the code also allows an ephemeral per-boot fallback there).
INDEXER_TOKEN required (prod) Shared secret the app container sends in the X-Indexer-Token header when proxying to the indexer container's control API on :8091 (/status, /trigger-sync, /sync-config — /healthz is intentionally auth-free for compose healthchecks). Required outside DEMO_MODE — the indexer refuses to start without it (compose.yml fails both indexer and app services with ${INDEXER_TOKEN:?…}), so the control API on the compose internal network cannot be triggered by any container that doesn't already know the secret. The app and indexer services share the same env var in compose.yml so they cannot drift. Generate with openssl rand -hex 32. In DEMO_MODE the indexer-demo/app-demo compose services allow an unset token (each falls back to a per-boot ephemeral value and logs a warning); operators that want stable across-restart auth can still set INDEXER_TOKEN explicitly.
TOTP_ENCRYPTION_KEY (falls back to SIGNING_SECRET) Root key for the AES-GCM encryption of stored TOTP secrets. Set it separately from SIGNING_SECRET so the URL-signing secret can be rotated freely; rotating this value makes every enrolled 2FA secret undecryptable (recover with python main.py --disable-2fa <user>).
AUTH_ACCESS_TTL 28800 (8 hours) Bearer access-token lifetime in seconds. Set 0 for effectively no expiry during a session (not recommended).
AUTH_REFRESH_TTL 2592000 (30 days) Bearer refresh-token lifetime in seconds.
AUTH_2FA_PENDING_TTL 300 (5 minutes) How long a pending 2FA token stays valid (seconds) during the two-step login. After this window the user must re-enter username + password.
AUTH_COOKIE_SECURE 0 FP-1: set the Secure flag on the HttpOnly refresh-token cookie (pf_refresh). Default 0 so local http:// testing and the demo work; set 1 behind TLS (the app compose service does). A Secure cookie is only sent over HTTPS, so leaving it 0 behind TLS is a regression of the XSS-exfiltration fix.
TRUSTED_PROXY_IPS (unset) Comma-separated IPs/CIDRs (or *) whose X-Forwarded-For/X-Forwarded-Proto uvicorn trusts. Unset keeps uvicorn's loopback-only default, so behind a reverse proxy every request carries the proxy's address and the login limiter's per-IP layer throttles everyone behind it together. Set it to the proxy's network (e.g. 172.18.0.0/16) so the real client IP reaches the limiter.
CLIENT_IP_HEADER (unset) Request header holding the real client IP when a CDN or tunnel sits in front of the reverse proxy, e.g. CF-Connecting-IP behind a Cloudflare tunnel (the proxy's X-Forwarded-For is then the tunnel container, so TRUSTED_PROXY_IPS alone still collapses every client onto one address). Used only by the login rate limiter, and only for requests whose peer (after TRUSTED_PROXY_IPS processing) is itself inside TRUSTED_PROXY_IPS — so both must be set, and the trusted range must cover the tunnel's address as the proxy reports it. Any other request, or an invalid/missing header value, keeps the socket peer, so a client that bypasses the proxy chain cannot choose its own limiter key.
AUTH_MAX_CONCURRENT_LOGINS 4 Max bcrypt password checks running at once per uvicorn worker. Excess logins wait up to 10 s and then receive 503 + Retry-After — bounds the CPU a credential-stuffing flood can pin.
MAX_JSON_BODY_BYTES 262144 (256 KB) Ceiling on any non-multipart request body; larger bodies get 413 before parsing. /api/search/face is exempt and bounded by FACE_SEARCH_MAX_UPLOAD_BYTES.
API_THREADPOOL_SIZE 16 Threads the API runs sync routes on (anyio's default is 40). Each thread keeps its own SQLite connection and page cache, so this bounds memory more than throughput.
SQLITE_CACHE_KB 8000 Per-connection SQLite page cache in KB. Connections are thread-local, so the app's cost is API_THREADPOOL_SIZE × SQLITE_CACHE_KB.
INDEXER_SQLITE_CACHE_KB 64000 Value compose passes as SQLITE_CACHE_KB to the indexer, which has only a handful of long-lived threads.
ADMIN_PASSWORD unset → prompt Pre-set the first admin's password so --create-admin runs non-interactively (e.g. from an init container). At least 8 characters or the command rejects it.

Performance tuning

A few knobs are worth knowing for large libraries:

# More parallel recognition workers (capped at #cores - 1)
WORKERS=6

# Less frequent clustering (cheaper if you don't add photos often)
CLUSTER_INTERVAL=3600

# More aggressive face auto-tagging
FACE_SIM_THRESHOLD=0.40

# More frequent sync (faster pick-up of new photos, more API calls)
SYNC_INTERVAL=120

The default WORKERS=3 keeps one core free for the API event loop on a 4-core box. On a 6-core box, WORKERS=5 is a reasonable ceiling.

Bridge-only env vars

The proton-bridge container reads these (set in compose.yml):

Variable Default Description
PORT 8090 Bridge container port (internal only).
BRIDGE_HOST 0.0.0.0 Bridge bind address. Set to 127.0.0.1 when running outside Docker to avoid LAN exposure (issue #43).
BRIDGE_TOKEN (required) Shared secret the app and indexer containers send as Authorization: Bearer to the bridge. docker compose up fails loudly when unset, and the bridge process exits at boot with an empty token unless BRIDGE_HOST is loopback or BRIDGE_AUTH_DISABLED=1. Generate with openssl rand -hex 32.
BRIDGE_AUTH_DISABLED 0 Explicit opt-out of bridge authentication for loopback-only dev setups. Never set it on a bridge reachable from other containers or the LAN.
DATA_DIR /data Where the bridge caches the session + work files.
PROTON_DRIVE_CREDENTIALS_STORE unsafe_file Session storage backend. unsafe_file (default) keeps the plaintext session at /data/auth-session.json (the AUTH_SESSION_MOUNT bind mount). pass selects the SDK's encrypted store: the bridge image ships pass + gnupg, and its entrypoint generates a container-local GPG key (in the bridge-gnupg volume), initializes the store (in the bridge-pass-store volume), and migrates an existing plaintext session on first start. See Session file → Encrypted store. Live only since PR #129 — earlier compose files hardcoded unsafe_file.
PROTON_DRIVE_CACHE_DIR /data Where the SDK caches encrypted blobs.
PROTON_DRIVE_BASE_URL drive-api.proton.me Optional: point at a custom Proton API environment.
PROTON_BRIDGE_RATE_LIMIT 0 (image default; 3 in compose.yml) Sustained outbound requests/second at the operation layer: one token per bridge operation start (timeline sync, node listing, album sync, thumbnail batch, full-res download). Honors Retry-After on 429 responses.
PROTON_BRIDGE_RATE_BURST Math.max(1, ceil(rate × 2)) Burst allowance for the operation-layer bucket (2 in compose.yml).
PROTON_BRIDGE_RATE_LIMIT_HTTP derived: RATE_LIMIT × 10 Requests/second at the SDK's HTTP transport — the patched HTTPClient acquires a token before every upstream HTTPS call (paginated listings, block downloads, thumbnail requests), not just operation starts (issue #44). Unset/empty derives as PROTON_BRIDGE_RATE_LIMIT × 10 (default compose: 3 ops/s → 30 HTTP req/s); explicit 0 disables this layer. Also honors Retry-After on 429/503.
PROTON_BRIDGE_FULL_RES_TIMEOUT_MS 300000 Full-res download queue-slot clamp and the /full MIME-lookup deadline (issue #55). The client can further clamp via the X-Timeout-Ms header.
PROTON_BRIDGE_TIMELINE_TIMEOUT_MS 1800000 Deadline for a full /timeline sync (pagination + node-key decrypt) (issue #55).
PROTON_BRIDGE_NODES_TIMEOUT_MS 300000 Deadline for the /nodes metadata lookup (issue #55).
PROTON_BRIDGE_ALBUMS_TIMEOUT_MS 300000 Deadline for the /albums listing (issue #55).
PROTON_BRIDGE_THUMBNAILS_TIMEOUT_MS 300000 Deadline for a /thumbnails batch download (issue #55).
PROTON_BRIDGE_MAX_VIDEO_TEMP_BYTES 2147483648 (2 GiB) Cap (bytes) on the temp file a video full-res request may materialize to disk (issue #62). 0 disables the cap. When the node's claimed size exceeds it, the bridge refuses with 507 Insufficient Storage before any download starts — the temp file lives on the same volume as the SQLite index, so an uncapped multi-GB video can starve every service. HEAD requests are answered from node metadata and never write a temp file.
BRIDGE_SDK_LOGS 0 (off) Full Proton SDK console logging: per-block download detail and upstream debug statements (issue #70). Default OFF — the SDK's unaudited log statements are noisy and widen the blast radius for accidental secret logging. Set to 1 only when troubleshooting a bridge issue. warn/error logs are always emitted regardless.

Local dev (single-process)

For python main.py on the host:

DATA_DIR=./data \
MODELS_DIR=./data/models \
BRIDGE_URL=http://127.0.0.1:8090 \
LOG_LEVEL=DEBUG \
RUN_INDEXER=1 \
INDEXER_STATUS_URL=http://127.0.0.1:8091 \
ADMIN_PASSWORD=changeme \
python -m main --create-admin admin

Then open http://localhost:8080.

Verifying the config

The ? overlay in the footer shows every relevant env var (under Config). The admin Overview tab shows the running version and the values that affect runtime behavior.

Where to set things

  • In .env for compose-level vars (or pass them inline: KEY=value docker compose up -d).
  • In compose.yml for per-service overrides (don't edit compose.yml directly — use a compose.override.yml).
  • In docker-compose.local.yml for dev-only tweaks (mount source, expose ports, etc.).

Next: REST API lists every endpoint.