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:

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:

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:

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:

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

Navigate to http://localhost:3000
Click "Sign in with Google"
Complete the Google OAuth flow
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

2.5 KiB Raw Permalink Blame History