API environment reference

Pinchana/pinchana-api/.env.example is the canonical environment template. This page groups the important settings by responsibility; copy the current example instead of reconstructing a .env from this page.

Core production VPN and machine auth

Variable	Typical/default	Purpose
WIREGUARD_PRIVATE_KEY	required in production Compose	WireGuard/NordLynx private key used by Gluetun
GLUETUN_API_KEY	placeholder default exists	Protects the Gluetun control API; replace it
SERVER_COUNTRIES	Netherlands,United States	Preferred VPN server countries
PINCHANA_API_KEYS	JSON object	Independently revocable machine API keys

The development Compose stack does not require production VPN credentials.

Browser authentication

Variable	Default/example	Purpose
TURNSTILE_SECRET_KEY	required for Web	Private Cloudflare Siteverify secret
TURNSTILE_EXPECTED_HOSTNAME	deployment-specific	Final Pinchana Web hostname
TURNSTILE_EXPECTED_ACTION	turnstile-spin-v1	Expected widget action
TURNSTILE_SESSION_SECRET	required	Signs browser-session tokens; use 32+ random chars
TURNSTILE_SESSION_MAX_AGE	43200	Browser session lifetime in seconds

The public Turnstile site key belongs in Pinchana Web, not in this private API secret group.

Mobile installation sessions

These routes are not used by Pinchana Web, but the gateway exposes optional native-client installation grants.

Important defaults:

MOBILE_AUTH_MODE=guest
MOBILE_AUTH_REQUIRED=false
MOBILE_ACCESS_TOKEN_MAX_AGE=900
MOBILE_REFRESH_TOKEN_MAX_AGE=2592000
MOBILE_CHALLENGE_TTL=120
MOBILE_CHALLENGE_RATE_WINDOW=600
MOBILE_CHALLENGE_RATE_LIMIT=10
MOBILE_TRUST_PROXY_HEADERS=false
MOBILE_GUEST_SCOPES=mobile:scrape,mobile:media,mobile:capabilities

MOBILE_SESSION_SECRET must be independent from every other signer/credential. Leave attestation URL/token empty unless an attestation verifier is actually deployed.

Rolling application images

Normal API images use variables such as:

• SERVER_IMAGE
• TIKTOK_IMAGE
• INSTAGRAM_IMAGE
• SHORTS_IMAGE
• SOUNDCLOUD_IMAGE
• YTMUSIC_IMAGE
• SPOTIFY_IMAGE
• DEEZER_IMAGE
• THREADS_IMAGE
• TWITTER_IMAGE

The example starts with :stable discovery tags. Production should immediately run:

python scripts/update_rolling.py --env-file .env

The updater replaces the mutable discovery values with immutable digests from one coherent release. Do not hand-edit each service to unrelated image versions.

DLP

DLP is disabled by default:

DLP_ENABLED=false

Important variables:

Variable	Current default/example	Purpose
DLP_GATEWAY_TOKEN	replace	Internal gateway → DLP API credential
DLP_OWNER_SECRET	replace	Derives opaque job-owner identities
DLP_REDIS_PASSWORD	replace	Internal Redis auth
DLP_HOST_JOBS_DIR	/srv/pinchana-dlp/jobs	Temporary host job storage
DLP_DOH_URL	Cloudflare DNS-over-HTTPS	DLP resolver path
DLP_WORKER_IMAGE	:stable initially	Worker image; pin via updater
DLP_API_IMAGE	:stable initially	DLP API image
DLP_ORCHESTRATOR_IMAGE	:stable initially	Orchestrator image
DLP_VPN_IMAGE	qmcgaw/gluetun:v3.40.0	Separate DLP VPN image
DLP_JOB_TTL_SECONDS	7200	Job lifetime
DLP_KEY_TTL_SECONDS	300	Allocation worker-key lifetime
DLP_MAX_ACTIVE_JOBS	3	Concurrency limit
DLP_RATE_LIMIT_PER_MINUTE	10	Allocation/submission abuse limit
DLP_EXECUTION_TIMEOUT_SECONDS	2700	Worker execution timeout
DLP_MAX_OUTPUT_BYTES	8589934592	8 GiB final artifact limit

Use scripts/update_rolling.py --dlp and the DLP preflight before enabling the capability.

Instance certificate

PINCHANA_INSTANCE_CERTIFICATE=
PINCHANA_INSTANCE_CERTIFICATE_FILE=

These expose a project-issued public certificate envelope from /web/identity so the official Web client can authorize this API as a custom instance. The signing private key must never be placed on the API host.

If both are set, the inline certificate takes precedence. A file variable must point to the mounted container path.

Compose names and ports

Default host ports:

API 8080
TikTok 8081
Instagram 8082
Shorts 8083
SoundCloud 8084
YouTube Music 8085
Spotify 8086
Deezer 8087
Threads 8088
Twitter/X 8089
Gluetun control 8000

Production services share Gluetun’s network namespace. The host mappings live on Gluetun; public reverse proxies should target only API 8080.

Container names and host ports can be overridden with the corresponding *_CONTAINER_NAME and *_HOST_PORT variables.

Cache and module behavior

Important shared values:

CACHE_MAX_SIZE_GB=10.0
MEDIA_DOWNLOAD_CONCURRENCY=4
YTDLP_CONCURRENCY=1
VPN_ENABLED=true
CONTAINER_MODE=false
MODULES_CONFIG=./config/modules.yaml
MODULE_NETWORK=container:gluetun

Production module endpoints default to http://localhost:<port> because all services share one network namespace. Development uses separate DEV_MODULE_*_ENDPOINT service-DNS values.

TikTok has additional request pacing/retry/transcode/rotation controls in .env.example; use those current documented defaults rather than hard-coding custom sleeps in application code.

YouTube Shorts cookies

SHORTS_COOKIES_DIR=./secrets/yt-cookies
YTDLP_COOKIES_DIR=/run/pinchana-cookies
YTDLP_COOKIE_FILE=
SHORTS_MAX_MB_PER_MINUTE=18.0

Production Compose mounts SHORTS_COOKIES_DIR read-only into /run/pinchana-cookies.

For rootful Docker with the current root-running Shorts image, use a private root-owned directory/file (0700 directory, 0600 cookie file). Rootless Docker should use the Docker host user instead.

YTDLP_COOKIE_FILE is an optional direct-run single-file fallback when no directory is configured.

Spotify

SPOTIFY_CLIENT_ID=
SPOTIFY_CLIENT_SECRET=

These are required for the Spotify module. Keep them server-side.

Protect .env

chmod 600 .env

Never commit .env, cookies, certificates containing private material, WireGuard keys, API keys, Turnstile secrets, DLP secrets, or Spotify credentials.