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.
2026-07-27 16:26:19 +02:00
parent 5c18d199fd
commit 9404efd86c
206 changed files with 37078 additions and 638 deletions
@@ -0,0 +1,107 @@
+---
+sidebar_position: 2
+---
+
+# Getting started
+
+Run Songs2VID locally for development or self-hosting.
+
+## 1. Environment file
+
+Copy the template, then edit **only** `.env` with your real values:
+
+```bash
+cp .env.example .env
+```
+
+See [Environment variables](./environment.md) for required vs optional keys.
+
+## 2. PostgreSQL and Redis
+
+For local app development (infra only):
+
+```bash
+docker compose -f docker-compose.dev.yml up -d
+```
+
+Or run the full stack (web + worker + DB) with the self-hosted edition — an optional Compose example:
+
+```bash
+docker compose up -d --build
+```
+
+Compose is not required; any Postgres + Redis that match your `.env` works. See [Docker Compose](https://docs.docker.com/compose/) if you use the examples above.
+
+## 3. Install and migrate
+
+```bash
+npm install
+npm run db:push
+```
+
+## 4. Google OAuth
+
+In [Google Cloud Console](https://console.cloud.google.com/) (server-side only — end users never enter credentials):
+
+1. Enable [YouTube Data API v3](https://developers.google.com/youtube/v3/getting-started)
+2. Create OAuth 2.0 Web credentials ([OAuth 2.0 for web server apps](https://developers.google.com/identity/protocols/oauth2/web-server))
+3. Add an authorized redirect URI ([URI validation](https://developers.google.com/identity/protocols/oauth2/web-server#uri-validation)):
+   - Local: `http://localhost:3000/api/auth/callback/google`
+   - Production: `https://YOUR_DOMAIN/api/auth/callback/google`
+4. Set `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` in `.env`
+
+Also set `NEXTAUTH_URL` to the same origin users open in the browser.
+
+## 5. FFmpeg and fonts
+
+The worker needs FFmpeg. The `ffmpeg-static` npm package is used by default. Set `FFMPEG_PATH` only if you want a system binary instead.
+
+For curated watermark fonts (Inter, Montserrat, etc.), ensure files exist under `assets/fonts`:
+
+```bash
+node scripts/fetch-watermark-fonts.mjs
+```
+
+Custom `.ttf` / `.otf` uploads work without this step. See [Video editing](./video-editing.md).
+
+## 6. Start app, worker, and docs
+
+One command for everything:
+
+```bash
+npm run dev:all
+```
+
+| Process | URL / role |
+|---------|------------|
+| Next.js app | [http://localhost:3000](http://localhost:3000) |
+| BullMQ worker | Encodes videos and uploads to YouTube |
+| Docusaurus docs | [http://localhost:3001](http://localhost:3001) |
+
+Or run them separately:
+
+```bash
+npm run dev
+npm run worker
+npm run docs:dev
+```
+
+## Authentication
+
+Users sign in with Google via OAuth 2.0. The app connects their YouTube channel automatically — end users do not need Google Cloud credentials or API keys.
+
+## Production
+
+For public HTTPS, OAuth redirect URIs, and worker checklist, see [Production notes](./deploy.md). Repo Compose/Caddy files there are optional examples only.
+
+## Useful scripts
+
+| Script | Purpose |
+|--------|---------|
+| `npm run dev:all` | App (3000) + worker + docs (3001) together |
+| `npm run dev` | Next.js dev server only |
+| `npm run worker` | Background job processor only |
+| `npm run docs:dev` | Documentation site only (port 3001) |
+| `npm run db:push` | Push Prisma schema to the database |
+| `npm run build` | Production build |
+| `npm run docs:build` | Build the documentation site |