Environment Variables

Complete reference for all PicPeak environment variables. Set these in the .env file at the project root.

Unless a section says otherwise, a variable works the same on the stable and the beta channel. Sections marked beta channel only describe features that are not in a stable release yet.

Core

TRUST_PROXY

PicPeak keys rate limits, login lockouts and audit addresses on the client IP, and decides from X-Forwarded-Proto whether a request arrived over HTTPS. Both headers are only believed from proxies inside the TRUST_PROXY boundary. The value is anything Express’ trust proxy setting accepts: a number of hops, loopback, linklocal, uniquelocal, a CIDR, a comma list, true, or false/0.

With too low a value every visitor appears under the proxy’s address: one shared rate-limit budget, and five failed logins from anyone lock out logins for everyone for 15 minutes. With too high a value a client can choose its own address through X-Forwarded-For. A hop count is only safe when clients cannot take a shorter path to the app; that is why the Compose stack publishes the backend port on host loopback only. Never use true unless every path to the app crosses a proxy you control.

When TRUST_PROXY is 1 and a request shows another private-range proxy in front of the bundled nginx, the backend logs one warning per process suggesting 2. See Reverse Proxy → Client IP.

Network and transport

Authentication cookies

Admin, gallery, and guest sessions are carried in HTTP cookies. These variables control how those cookies are set.

COOKIE_SECURE values

The value is trimmed and case-insensitive; 1/yes/on mean true and 0/no/off mean false. Any other value is treated as auto, with one warning in the log at startup. The Compose files pass COOKIE_SECURE=${COOKIE_SECURE:-auto}. The installer writes true for installs behind a TLS proxy and false for plain-HTTP installs.

Mixed HTTPS/HTTP deployments (COOKIE_SECURE=auto)

A common self-hosted setup:

• Public: HTTPS via a reverse proxy like Nginx Proxy Manager, Traefik, or Caddy (e.g. https://photos.example.com)
• LAN: Plain HTTP on a private address (e.g. http://192.168.1.50:3000, the frontend port) for admin access without going through the proxy

With COOKIE_SECURE=true, LAN login breaks because browsers refuse to send Secure cookies over HTTP. With COOKIE_SECURE=false, HTTPS login loses the security of the Secure flag. auto, the production default, decides the Secure flag per request — the backend reads req.secure from Express, which reflects the X-Forwarded-Proto header forwarded by your reverse proxy.

The backend port (3001) is published on host loopback only, so LAN access goes through the frontend port. To reach the backend port from another machine, set PICPEAK_BACKEND_BIND_ADDRESS.

Database

Redis

Admin account

Email (SMTP)

A mail server on a private address needs an entry in MAIL_PRIVATE_ENDPOINTS unless it is the SMTP_HOST/SMTP_PORT pair set here.

Application URLs

Ports

Storage

External-folder watching

Available in builds containing PicPeak PR #1345 . These settings control automatic imports for reference-mode events. Each event must also opt in using Watch folder for new files; the global default does not enable watching for every event. See External Media for setup, permissions and deletion behaviour.

All interval values are in milliseconds. The updated bundled Compose files forward the first six options from .env; they do not forward EXTERNAL_MEDIA_WATCH_RECONCILE_INTERVAL_MS. Custom Compose definitions must pass the desired variables through environment or env_file. On AIO, set them on the PicPeak container. Recreate the container after changes; for a native process, restart the backend with the new environment.

The watcher uses the local EXTERNAL_MEDIA_ROOT with both local and S3 storage backends. These settings do not configure the managed-storage file watcher or the S3 prefix walker.

Watch-folder import

The managed-storage file watcher (local storage only).

Docker user mapping

PUID and PGID are no longer read. The backend container starts as root, hands its bind mounts to UID 1001 and drops privileges; to run as another UID, pin user: in a compose override. See Docker → Permissions.

Social link preview fallback

Used for the static HTML title and meta description on the SPA shell — the fallback that catches link-preview fetchers (WhatsApp Business API, Twilio, LinkPreview, etc.) that don’t trigger the per-event Open Graph endpoint. Substituted into index.html at frontend-container start, so changes take effect on the next docker compose up -d frontend — no frontend rebuild needed.

Release channel

In-app updates

Beta channel only (from v3.165.0-beta.0). Off by default. See In-App Updates.

Analytics

Umami and Rybbit are configured under Settings → Analytics, not in the environment. The build-time VITE_UMAMI_URL, VITE_UMAMI_WEBSITE_ID and VITE_UMAMI_SHARE_URL are no longer read. See Analytics.

Public landing page

Upload limits

Limits on what the server admits, set as JSON in the backend environment and applied after a restart. Empty means the defaults; omitted keys keep their default. Sizes are integer bytes, counts positive integers. Unknown keys and zero, negative or fractional values are refused. The defaults are the same on the stable and the beta channel. The full reference is docs/PUBLIC_UPLOAD_LIMITS.md in the code repository.

Public defaults: one request carries at most 95 MiB (never less than one file of the configured maximum size). Lifetime allowances, which deleting a file does not give back:

Admin defaults: at most the smaller of 50 GiB and 25% of free space staged at once, 50,000 staged files, 16 concurrent requests per admin account, 64 per deployment, 10 minutes per request or chunk. Both profiles keep 512 MiB and 1,024 inodes free (inodes only where the filesystem counts them); headroomPercent additionally keeps a share of the volume free and is off by default.

PUBLIC_UPLOAD_LIMITS_JSON={"requestBytes":209715200,"gallery":{"bytes":107374182400}}
ADMIN_UPLOAD_LIMITS_JSON={"stagedBytes":214748364800,"accountRequests":32}

Larger request bodies also need matching limits in your reverse proxy.

Image and media processing

Image parsing and transforms run in a small pool of worker processes outside the backend; ffmpeg, ffprobe and exiftool run under a process guard where the host supports it (Linux with the native build, which the Docker images include). The backend logs one line at startup saying which protections are active. All overrides must be positive integers. Defaults accept what earlier versions accepted. The full reference is docs/MEDIA_PROCESSING.md.

Refreshing old renditions

Beta channel only (from v3.174.2-beta.0). Thumbnails, previews and heroes are written without the photo’s EXIF (GPS position, camera, copyright). After the upgrade a background pass rebuilds the renditions written before that, one photo at a time, starting with link-preview covers.

Storage backend

See Storage Backends for the migration playbook and provider-specific examples.

Video copies

The worker behind Browser-playable copies of videos (Video Support → Browser playback). All optional; the setting itself is switched on in the admin, not here. Builds containing PicPeak PR #1761 ; beta channel only.

Webhooks

See Webhooks for event catalog, payload shapes, and verification examples.

Incoming mail

Capacity and retention for mail captured from the accounting mailbox and additional mailboxes. The limits apply before a new message is downloaded and never delete mail on the IMAP server. A message refused for capacity or rate stays unread on the server and is fetched by a later poll; the backend logs one warning per mailbox, limit and hour naming the variable. Values must be positive integers; invalid values fall back to the defaults. The full reference is docs/incoming-mail-retention.md.

Automatic scene tags

Beta channel only. Uses the same picpeak-ml sidecar, FACE_ML_URL and FACE_ML_TOKEN as face recognition, but has its own feature flag (autoTagging) and per-gallery switch, both off by default.

Contract signing evidence

Beta channel only. See Contracts.

Losing or changing the evidence key

Each stored value names the key it was written under. PicPeak reads it with the current key, any key in PICPEAK_EVIDENCE_KEYS_OLD, and any file named evidence.key.<keyId> next to the key file in storage/business-docs/keys/. New evidence is always written under the current key.

• Losing the key that evidence was written under, with no copy anywhere, makes those signer names, email addresses and IP addresses unreadable. The signatures, the signed PDFs and the signing event log stay valid.
• Recovery means making the lost key readable again: put its value in PICPEAK_EVIDENCE_KEYS_OLD, or restore its file as evidence.key (if it is the current key) or evidence.key.<keyId> (if it is an old one).
• System Health shows the key in use, how many stored values are still under an older key that can be read, and how many are under a key PicPeak no longer has.

Rotating the key

1. Set PICPEAK_EVIDENCE_KEY to the new key. Keep the old one readable: put it in PICPEAK_EVIDENCE_KEYS_OLD, or — if the old key was the generated key file — leave the file where it is.

2. Restart the backend.

3. Run the rotation script:

   docker compose exec backend node scripts/rotate-evidence-key.js --dry-run   # counts per key, changes nothing
   docker compose exec backend node scripts/rotate-evidence-key.js

   On its first run it keeps a replaced generated key file as evidence.key.<keyId>, then re-encrypts every value that is under another key, in batches. It is safe to stop and run again at any time: a run re-encrypts only values still under another key, so a second run after a complete one changes nothing. A signature recorded while it runs is never overwritten; it is skipped and picked up by the next run. It prints how many values it moved and how many are still under another key.

4. Keep the old key until the script reports 0 values still under another key, then remove it from PICPEAK_EVIDENCE_KEYS_OLD (or delete the evidence.key.<keyId> file).

Rotation changes only the encrypted values. The content hash, the PDFs, the signing certificate and the signing log’s hashes stay exactly as they were.

Back up PICPEAK_EVIDENCE_KEY (and any old keys still needed) with your other secrets, or the key files with the database. They sit under business-docs, which is part of the backup export.

Malware scanner for customer documents

Beta channel only. See Customer Documents → Malware scanning. Unset, no scanner is used and customer uploads wait for an admin’s review. The bundled compose files have an opt-in ClamAV service: docker compose --profile clamav up -d, then set CLAMAV_HOST=clamav.

Backup and restore

See Backup and Restore.

BACKUP_MANIFEST_REQUIRE_KEYED is gone: every manifest now needs a key, and a manifest without a valid signature fails closed. .picpeak imports need Linux, the native build (included in the Docker images) and STORAGE_PATH on a local filesystem; where the host does not qualify, only the import is switched off and one startup log line says why.