---
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 |