Skip to main content

Setup Guide

Complete guide to setting up your development environment for Bitrate.

📋 Prerequisites​

Requirements are separated by workflow in the repository README:

  • Docker stack: Git, Docker Engine 24+ with Compose v2, and Task v3. Host Node.js and Python are not required for this path; use task init after cloning.
  • Native development: Node.js >=24 (.nvmrc selects v24), pnpm 12.7.0 exactly (package.json#packageManager), and Git. Docker/Task provide the local API infrastructure.
  • Claude Code assistance: additional runtime and optional integration requirements are in How to AI. They are not application prerequisites.

The instructions below use the native development path unless marked Docker. Check node --version, pnpm --version, docker compose version and task --version first. Use a Bash/WSL shell for the environment-variable prefixes in these examples.

🚀 Initial Setup​

1. Clone the Repository​

git clone https://github.com/Lordpluha/bitrate.git
cd bitrate

2. Install Dependencies​

# Install workspace dependencies without optional Graphify/RTK setup
SKIP_GRAPHIFY_INSTALL=1 SKIP_RTK_INSTALL=1 pnpm install

This will install dependencies for all apps and packages defined in pnpm-workspace.yaml. It also runs lefthook install automatically (pre-commit, commit-msg, pre-push hooks). The two flags skip only the optional AI-tool installers; keep them on subsequent installs if you do not want Graphify or global RTK setup.

3. Environment Variables​

Nothing to do for the Docker stacks — there is no repository-root env file. Every variable in infra/docker-compose.dev.yaml and infra/docker-compose.preprod.yaml carries a default, so they start on a clean checkout. Export a shell variable to override one:

POSTGRES_PORT=5433 task infra:up

To run a single app natively, copy that app's own template — apps/api, apps/web-player and apps/web-artists each ship one — into that app's .env. Deploy and CI values live in GitHub environment secrets and variables, not in any file.

The API validates its own environment at startup via Zod (apps/api/env.schema.ts). Required variables: DATABASE_URL, REDIS_HOST, REDIS_PORT, JWT_SECRET, WEB_HOST. See Environment variables for the full list.

4. Start Infrastructure​

The recommended workflow is a minimal Docker stack (postgres + redis only) with apps running natively:

# Option A: via task (cross-platform)
task infra:up

# Option B: via Docker Compose directly
docker compose -f infra/docker-compose.dev.yaml up -d

# Verify containers are running
docker compose -f infra/docker-compose.dev.yaml ps

5. Run Database Migrations​

task db:migrate:native
task db:seed:native

# Or without task:
pnpm --filter @bitrate/api run db:migration:start
pnpm --filter @bitrate/api run db:seed

6. Start Development Servers​

All Applications at Once​

# From root directory
pnpm dev

This starts every app Turbo knows about. The full set of local addresses, including the ones that only appear once you start that app on its own:

ServiceURL
APIhttp://localhost:3000
Swaggerhttp://localhost:3000/swagger
Web Playerhttp://localhost:3001
Web Artistshttp://localhost:3002
Docs (Docusaurus)http://localhost:3003
Storybook (ui-react)http://localhost:6006
Storybook (player)http://localhost:6007
Storybook (admin UI kit)http://localhost:6008
Mobile (Metro)http://localhost:8081
Desktop (Vite)http://localhost:1420

These are the native ports. The Docker stack maps web-artists to 3004 — see Docker. For the deployed sites see Deployment.

Individual Applications​

# Backend API
pnpm --filter @bitrate/api start:dev

# Web Player
pnpm --filter @bitrate/web-player dev

# Mobile Application
pnpm --filter @bitrate/mobile start

# Desktop Application
pnpm --filter @bitrate/desktop tauri dev

# Documentation
pnpm --filter @bitrate/docs start

🐳 Full Docker Stack (alternative)​

If you prefer running all apps in Docker:

# First run — build images, migrate, seed
task init

# Subsequent runs
task dev:up

# Stop
task dev:down

task is the only interface to the Docker stack — the old pnpm docker:* scripts were removed. Run task with no arguments to list everything.

🔧 Development Workflow​

Working with Packages​

Building Packages​

# Build all packages
pnpm build

# Build specific package
pnpm --filter @bitrate/ui-react build

Regenerating Assets​

After adding SVG icons to packages/ui-react/assets/icons/ — the svgr plugin in vite.config.ts regenerates src/icons/svgr/ as part of the build:

pnpm --filter @bitrate/ui-react build

After API schema changes (API must be running on :3000):

pnpm --filter @bitrate/contracts gen:api

Database Management​

Prisma Studio (GUI)​

pnpm --filter @bitrate/api run db:ui
# Opens at http://localhost:5555

Creating Migrations​

# After modifying a file in apps/api/prisma/schema/
pnpm --filter @bitrate/api run db:migration:start

Resetting Database​

# ⚠️ WARNING: This will delete all data!
pnpm --filter @bitrate/api run db:migration:reset
# or via task (with confirmation prompt):
task db:reset

Running Tests​

# API unit tests
pnpm --filter @bitrate/api test

# API integration tests (needs running DB)
pnpm --filter @bitrate/api test:int

# API E2E tests
pnpm --filter @bitrate/api test:e2e

Linting & Formatting​

# Lint all files (Biome)
pnpm lint

# Format all files (Biome)
pnpm format

# Type checking
pnpm check-types

Committing​

Use the interactive Conventional Commits wizard:

pnpm commit

For packages that changed behaviour, also run:

pnpm changeset

📱 Mobile Development​

iOS (macOS only)​

pnpm --filter @bitrate/mobile ios

Android​

pnpm --filter @bitrate/mobile android

Expo Go​

pnpm --filter @bitrate/mobile start
# Scan QR code with Expo Go app

See Mobile App Guide for detailed instructions.

🖥️ Desktop Development​

System Dependencies​

Linux (Ubuntu/Debian)
sudo apt install -y \
  libwebkit2gtk-4.1-dev \
  build-essential \
  curl \
  wget \
  file \
  libxdo-dev \
  libssl-dev \
  libgtk-3-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev \
  pkg-config

# Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
macOS
# Install Xcode Command Line Tools
xcode-select --install

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
Windows

Running Desktop App​

# Development mode (native Tauri window)
pnpm --filter @bitrate/desktop tauri dev

# UI only in Docker (no Tauri backend)
docker compose --profile desktop up -d desktop
# Open http://localhost:1420

See Desktop App Guide for detailed instructions.

🔍 Debugging​

Backend (API)​

# Debug mode with inspector
pnpm --filter @bitrate/api start:debug

VSCode Debug Configuration:

{
  "type": "node",
  "request": "attach",
  "name": "Attach to NestJS",
  "port": 9229,
  "restart": true,
  "sourceMaps": true
}

🛠️ Useful Commands​

Generate TypeScript Types from Swagger​

# API must be running on :3000
pnpm --filter @bitrate/contracts gen:api

Clean Build Artifacts​

# Cross-platform (uses scripts/clean-dist.mjs)
pnpm clean:dist
# or via task:
task clean:dist

Update Dependencies​

# Check for outdated packages
pnpm outdated -r

# Update all dependencies
pnpm update -r

🐛 Troubleshooting​

Port Already in Use​

# Find process using port 3000
lsof -i :3000

# Or stop all Docker services
docker compose -f infra/docker-compose.preprod.yaml down

Database Connection Issues​

# Check if postgres is running
docker compose -f infra/docker-compose.dev.yaml ps

# Restart
docker compose -f infra/docker-compose.dev.yaml restart postgres

Prisma Client Out of Sync​

pnpm --filter @bitrate/api run db:gen

node_modules Issues​

# Clean install
rm -rf node_modules
rm pnpm-lock.yaml
pnpm install

Turbo Cache Issues​

# Run without cache
pnpm turbo build --force

📚 Next Steps​

Having issues? Check out Troubleshooting or open an issue.