---
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](https://console.cloud.google.com/). Guide: [Setting up OAuth 2.0](https://support.google.com/cloud/answer/6158849). Enable [YouTube Data API v3](https://developers.google.com/youtube/v3/getting-started).

## 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](./deploy.md).
- Never commit `.env` or put production secrets in `.env.example`.