youtube-studio-flow/documentation/YouTube Studio Flow/05 - Development/02 - Environment Variables.md

Environment Variables

Complete reference for all environment variables used by the backend and frontend.

---

Backend (backend/.env)

Copy backend/.env.example to backend/.env and fill in all required values before starting the API or worker. See 01 - Local Setup for the full setup sequence.

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string. Format: postgresql://user:pass@localhost:5432/dbname
REDIS_URL	Yes	Redis connection string. Format: redis://:password@localhost:6379
JWT_SECRET	Yes	Secret for signing access tokens. Use a long random string.
JWT_REFRESH_SECRET	Yes	Secret for signing refresh tokens. Must differ from JWT_SECRET.
GOOGLE_CLIENT_ID	Yes	Google OAuth app client ID
GOOGLE_CLIENT_SECRET	Yes	Google OAuth app client secret
GOOGLE_CALLBACK_URL	Yes	OAuth redirect URL. Local: http://localhost:3001/api/v1/auth/google/callback
TOKEN_ENCRYPTION_KEY	Yes	Exactly 32 characters. AES-256 key for encrypting YouTube OAuth tokens in the DB. If this changes, all channel connections break.
FRONTEND_URL	Yes	Frontend origin for OAuth redirect. Local: http://localhost:3000
PORT	No	API port. Default: 3001
NODE_ENV	No	development or production
CONFLICT_DETECTION_ENABLED	No	Global kill switch for the scheduled remote-conflict sweep. Default: false. Only takes effect on the worker process; the API doesn't read it. Per-team opt-in still required via Team.conflictDetectionEnabled. See 05 - Queue System.
CONFLICT_DETECTION_CRON	No	Cron pattern (BullMQ format) for the sweep. Default: 0 3 * * * (daily at 03:00 UTC). Only read when CONFLICT_DETECTION_ENABLED=true.

Example backend/.env

DATABASE_URL=postgresql://studioflow:yourpassword@localhost:5432/studioflow
REDIS_URL=redis://:yourpassword@localhost:6379
JWT_SECRET=a-very-long-random-string-for-access-tokens
JWT_REFRESH_SECRET=a-different-very-long-random-string-for-refresh-tokens
GOOGLE_CLIENT_ID=123456789-abc.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-yourGoogleSecret
GOOGLE_CALLBACK_URL=http://localhost:3001/api/v1/auth/google/callback
TOKEN_ENCRYPTION_KEY=exactly32characterslongkeyhere!!
FRONTEND_URL=http://localhost:3000
PORT=3001
NODE_ENV=development
CONFLICT_DETECTION_ENABLED=false
CONFLICT_DETECTION_CRON=0 3 * * *

---

Frontend (frontend/.env.local)

Create frontend/.env.local manually (it is not committed to git and has no .example counterpart).

Variable	Required	Description
NEXT_PUBLIC_API_URL	Yes	Backend API base URL. Local: http://localhost:3001/api/v1

Example frontend/.env.local

NEXT_PUBLIC_API_URL=http://localhost:3001/api/v1

---

Security Notes

• Never commit .env or .env.local files to git — both are already listed in .gitignore
• TOKEN_ENCRYPTION_KEY must remain stable for the entire lifetime of the database. Rotating it invalidates all stored YouTube OAuth tokens, requiring every channel to be re-authenticated. See 04 - Gotchas for more detail.
• Use distinct values for JWT_SECRET and JWT_REFRESH_SECRET — reusing the same secret across both token types weakens the separation between access and refresh token validation
• In production, use a secrets manager or CI/CD secret injection rather than plain .env files