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_URLmust 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
.envor put production secrets in.env.example.