songs2vid/website/docs/environment.md

sidebar_position

sidebar_position
3

Environment variables

Two files exist on purpose — they are not duplicates you both fill with secrets.

File	Role
.env.example	Safe template committed to git. Shows names and placeholders. No real secrets.
.env	Your real local or production secrets. Gitignored. The app reads only this.

Workflow: copy once (cp .env.example .env), then edit only .env. Leave .env.example as the shared checklist.

The official OSS / Docker image is always self-hosted and payment-free. Do not set Stripe, billing, or credit-related variables for self-host — they are unused.

Required for local development

Variable	Purpose
DATABASE_URL	Postgres connection string (Docker defaults work out of the box)
REDIS_URL	Redis for BullMQ and rate limiting
NEXTAUTH_URL	Public app URL, e.g. http://localhost:3000 or https://songs2vid.example.com
NEXTAUTH_SECRET	Long random string (e.g. openssl rand -base64 32)
GOOGLE_CLIENT_ID	Google OAuth client ID
GOOGLE_CLIENT_SECRET	Google OAuth client secret

Create OAuth credentials in Google Cloud Console. Guide: Setting up OAuth 2.0. Enable YouTube Data API v3.

Optional

Variable	Purpose
TOKEN_ENCRYPTION_KEY	Encrypts YouTube tokens at rest; falls back to NEXTAUTH_SECRET if unset
UPLOAD_DIR	Upload storage path; defaults to ./uploads (Compose uses /app/uploads)
FFMPEG_PATH	Override FFmpeg binary (image defaults to system ffmpeg)
S2VID_PORT	Host port for the optional root docker-compose.yml example (default 3000)
NEXT_PUBLIC_GITEA_URL	Footer / open-source link
NEXT_PUBLIC_GITEA_ISSUES_URL	Bug report link
NEXT_PUBLIC_DOCKER_HUB_URL	Docker image link
NEXT_PUBLIC_DOCS_URL	Docs site URL (production default https://docs.songs2vid.com)
ADMIN_API_KEY	Optional Bearer token for internal admin HTTP routes. Not required for normal self-hosted operation

Notes

• User API keys are generated in Dashboard → Settings → API key (hashed at rest). They are not env vars.
• Full entitlements (layouts, API, playlists, unlimited allowance) are always on in the OSS image — there is no edition flag or paywall to enable.
• In production, NEXTAUTH_URL must match the public HTTPS URL users open in the browser, and the same origin must be listed as an OAuth redirect URI (…/api/auth/callback/google). See Production notes.
• Never commit .env or put production secrets in .env.example.