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
.envfor compose-level vars (or pass them inline:KEY=value docker compose up -d). - In
compose.ymlfor per-service overrides (don't editcompose.ymldirectly — use acompose.override.yml). - In
docker-compose.local.ymlfor dev-only tweaks (mount source, expose ports, etc.).
Next: REST API lists every endpoint.