---
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](./environment.md). Local setup: [Getting started](./getting-started.md).

### Google OAuth (required)

1. Create a project in [Google Cloud Console](https://console.cloud.google.com/)
2. Enable [YouTube Data API v3](https://developers.google.com/youtube/v3/getting-started)
3. Create OAuth 2.0 Web credentials ([guide](https://developers.google.com/identity/protocols/oauth2/web-server))
4. Add the authorized redirect URI ([URI rules](https://developers.google.com/identity/protocols/oauth2/web-server#uri-validation)):

```text
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](./api/overview.md))

### 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](https://developers.google.com/youtube/v3/guides/quota_and_compliance_audits) |

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}`.

```bash
docker compose up -d --build
```

Compose reference: [Docker Compose docs](https://docs.docker.com/compose/).

### `deploy/songs2vid/` (Caddy sample)

Sample layout under `deploy/songs2vid/`: Compose services plus a [Caddyfile](https://caddyserver.com/docs/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](https://caddyserver.com/docs/)
- [Automatic HTTPS](https://caddyserver.com/docs/automatic-https)
- [`reverse_proxy`](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy)
- [`basicauth`](https://caddyserver.com/docs/caddyfile/directives/basicauth) · [`caddy hash-password`](https://caddyserver.com/docs/command-line#caddy-hash-password)

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