songs2vid/website/docs/getting-started.md

sidebar_position

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:

cp .env.example .env

See Environment variables for required vs optional keys.

2. PostgreSQL and Redis

For local app development (infra only):

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:

docker compose up -d --build

Compose is not required; any Postgres + Redis that match your .env works. See Docker Compose if you use the examples above.

3. Install and migrate

npm install
npm run db:push

4. Google OAuth

In Google Cloud Console (server-side only — end users never enter credentials):

1. Enable YouTube Data API v3
2. Create OAuth 2.0 Web credentials (OAuth 2.0 for web server apps)
3. Add an authorized redirect URI (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:

node scripts/fetch-watermark-fonts.mjs

Custom .ttf / .otf uploads work without this step. See Video editing.

6. Start app, worker, and docs

One command for everything:

npm run dev:all

Process	URL / role
Next.js app	http://localhost:3000
BullMQ worker	Encodes videos and uploads to YouTube
Docusaurus docs	http://localhost:3001

Or run them separately:

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. 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 docs:build	Static docs build (for Caddy / nginx)
npm run db:push	Push Prisma schema to the database
npm run build	Production build