---
sidebar_position: 2
---

# Getting started

Run Songs2VID locally for development or self-hosting. The OSS edition is payment-free and always has full entitlements (no Stripe, credits, or plans).

Source: [Gitea — Songs2VID/songs2vid](https://git.atakanozban.com/Songs2VID/songs2vid) (`main`).  
Image: [`atakanozban/songs2vid:latest`](https://hub.docker.com/r/atakanozban/songs2vid).

## Fastest path: Docker Compose

1. Copy the template, then edit **only** `.env`:

```bash
cp .env.example .env
```

Set `NEXTAUTH_SECRET`, `GOOGLE_CLIENT_ID`, and `GOOGLE_CLIENT_SECRET`. See [Environment variables](./environment.md).

2. Configure Google OAuth (below), then start the full stack:

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

Or pull the published image:

```bash
docker pull atakanozban/songs2vid:latest
```

Open [http://localhost:3000](http://localhost:3000), sign in with Google, and use the dashboard.

Compose is not required; any Postgres + Redis that match your `.env` works. See [Docker Compose](https://docs.docker.com/compose/).

## Local development (app + worker)

### 1. Environment file

```bash
cp .env.example .env
```

### 2. PostgreSQL and Redis

```bash
docker compose -f docker-compose.dev.yml up -d
```

### 3. Install and migrate

```bash
npm install
npm run db:migrate
```

(`npm run db:push` is an alternative if you prefer schema push without migrations.)

### 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 Docker image includes system FFmpeg; locally, `ffmpeg-static` 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` (see `assets/fonts/README.md` in the repo). Custom `.ttf` / `.otf` uploads work without that step. See [Video editing](./video-editing.md).

### 6. Start app and worker

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

Or run them separately:

```bash
npm run dev
npm run worker
```

This docs site (Docusaurus) is maintained separately and published at [docs.songs2vid.com](https://docs.songs2vid.com).

## Authentication and settings

Users sign in with Google via OAuth 2.0. The app connects their YouTube channel automatically — end users do not need Google Cloud credentials.

After sign-in you go straight to the dashboard. **Settings** includes:

- Account
- YouTube connection
- API key

There is no billing, pricing, or credit UI in the self-hosted OSS build.

## Production

For public HTTPS, OAuth redirect URIs, and worker checklist, see [Production notes](./deploy.md).

## Useful scripts

| Script | Purpose |
|--------|---------|
| `npm run dev:all` | App (3000) + worker together |
| `npm run dev` | Next.js dev server only |
| `npm run worker` | Background job processor only |
| `npm run db:migrate` | Apply Prisma migrations |
| `npm run db:push` | Push Prisma schema to the database |
| `npm run build` | Production build |