songs2vid/website/docs/deploy.md

sidebar_position

sidebar_position
4

Production notes

Self-hosting in production means running the web app and the worker against shared Postgres, Redis, and upload storage, with a public HTTPS URL for OAuth.

How you package that (bare metal, systemd, Kubernetes, Docker, a PaaS) is up to you. The Compose files in this repo are optional examples, not a required stack.

What you must configure

Requirement	Notes
S2VID_EDITION=selfhosted	Unlimited allowance, API, and Pro layout features. Root Compose injects this when you use that example.
NEXTAUTH_URL	Exact public origin users open (e.g. https://songs2vid.example.com), no trailing slash
NEXTAUTH_SECRET	Strong random secret
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	OAuth Web client from Google Cloud
OAuth redirect URI	https://YOUR_DOMAIN/api/auth/callback/google — must match NEXTAUTH_URL
YouTube Data API v3	Enabled on the same Google Cloud project
Worker process	Same DATABASE_URL, REDIS_URL, and UPLOAD_DIR as the web app
Persistent uploads	Shared volume or disk for both web and worker

Env reference: Environment variables. Local setup: Getting started.

Google OAuth (required)

1. Create a project in Google Cloud Console
2. Enable YouTube Data API v3
3. Create OAuth 2.0 Web credentials (guide)
4. Add the authorized redirect URI (URI rules):

https://YOUR_DOMAIN/api/auth/callback/google

Users sign in with Google; they do not need their own Cloud credentials.

After go-live

1. Open NEXTAUTH_URL and sign in
2. Confirm the YouTube channel connects
3. Generate an API key under Dashboard → Settings → API access if you automate uploads
4. Run a small test job (dashboard or API)

Common issues

Symptom	Check
OAuth redirect mismatch	Redirect URI must match NEXTAUTH_URL + /api/auth/callback/google exactly
Jobs stuck in PENDING	Worker is running and shares Redis + upload storage with web
Encode / upload failures	FFmpeg available where the worker runs; disk space for uploads
YouTube errors	Channel permissions or Google limits — YouTube quota & compliance

Put any reverse proxy you like in front (Caddy, nginx, Traefik, cloud load balancer) and terminate TLS there so NEXTAUTH_URL is HTTPS.

Optional examples in this repo

These are starting points only. Adapt or ignore them.

Root docker-compose.yml

Builds web + worker + Postgres + Redis with S2VID_EDITION=selfhosted. Useful for a quick all-in-one box. App port defaults to ${S2VID_PORT:-3000}.

docker compose up -d --build

Compose reference: Docker Compose docs.

deploy/songs2vid/ (Caddy sample)

Sample layout under deploy/songs2vid/: Compose services plus a Caddyfile that reverse-proxies the app, optionally serves a static docs build, and optionally puts Prisma Studio behind basic auth.

Only relevant if you choose Caddy. Useful links:

• Caddy documentation
• Automatic HTTPS
• reverse_proxy
• basicauth · caddy hash-password

Edit hostnames in the sample Caddyfile to your domains. Do not commit real basic-auth password hashes.