Align preview typography with FFmpeg output, add video/song title split, and ship OSS updates.

Separate YouTube video titles from on-video song/artist fields with Pro gating, serve curated fonts and watermark assets for 1:1 preview parity, and include billing/API/docs/deploy stack for self-hosted release. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-27 16:26:19 +02:00
parent 682020ff5a
commit c8015937f9
206 changed files with 37078 additions and 638 deletions
@@ -0,0 +1,82 @@
+---
+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.