# Local Setup

Step-by-step guide to running YouTube Studio Flow on a local machine for development.

---

## Prerequisites

- **Node.js 18+** — required by both backend and frontend
- **Docker** — used to run Postgres and Redis locally
- **Git** — for cloning the repository

---

## Step 1 — Start Infrastructure

Start Postgres and Redis using Docker Compose:

```bash
cd infrastructure
docker compose up -d postgres redis
```

> **Important:** Redis must run with `--maxmemory-policy noeviction`. BullMQ silently drops jobs if Redis uses `allkeys-lru` eviction. This policy is already pre-configured in `infrastructure/docker-compose.yml`. Do not change it. See [[04 - Gotchas]] for more detail.

---

## Step 2 — Backend Setup

In a terminal, set up and start the NestJS API:

```bash
cd backend
npm install
cp .env.example .env
# Fill in all required values in .env — see [[02 - Environment Variables]]
npx prisma generate
npx prisma migrate deploy
npm run start:dev
```

The API is now running on **http://localhost:3001**.

---

## Step 3 — Queue Worker

Open a **second terminal** and start the BullMQ queue processor:

```bash
cd backend
npx ts-node src/worker.ts
```

The worker runs from the same codebase as the API but through a separate entry point (`src/worker.ts` → `WorkerModule`). It handles all background jobs: YouTube sync, description rendering, linting, bulk operations, and CSV imports.

---

## Step 4 — Frontend Setup

Open a **third terminal** and start the Next.js frontend:

```bash
cd frontend
npm install
# Create frontend/.env.local with the following content:
# NEXT_PUBLIC_API_URL=http://localhost:3001/api/v1
npm run dev
```

The app is now running on **http://localhost:3000**.

---

## Verify the Setup

1. Navigate to **http://localhost:3000**
2. Click **"Sign in with Google"**
3. Complete the Google OAuth flow
4. You should be redirected to the **Overview** page

If the redirect fails, check that `GOOGLE_CALLBACK_URL` and `FRONTEND_URL` are set correctly in `backend/.env`. See [[02 - Environment Variables]].

---

## Notes

- All three processes must run simultaneously for full functionality:
  - `npm run start:dev` — HTTP API on :3001
  - `npx ts-node src/worker.ts` — BullMQ job processor
  - `npm run dev` — Next.js frontend on :3000
- Database migrations run automatically with `npx prisma migrate deploy`
- After any schema change: stop the backend → `npx prisma generate` → `npx prisma migrate deploy` → restart both the API and worker
- For non-obvious behaviors and known traps, see [[04 - Gotchas]]