Configuration

Prerequisites

• Bun >= 1.3
• Node.js >= 24 (for compatibility)
• Docker (for local PostgreSQL)
• Git

Installation

# Clone the repository
git clone <repo-url>
cd roxabi_boilerplate

# Install dependencies
bun install

Environment Variables

Copy the example file and configure:

cp .env.example .env

Required Variables

Branch Databases (Local Development)

Each git worktree gets its own isolated PostgreSQL database named roxabi_<issue_number> within the shared Docker container. This prevents schema conflicts when multiple worktrees run concurrent migrations.

Branch databases are created automatically by /implement during worktree setup, or manually:

cd apps/api

# Create a branch database (migrate + seed + update .env)
bun run db:branch:create

# Create with explicit issue number (non-interactive)
bun run db:branch:create --force 150

# Drop a branch database
bun run db:branch:drop

# List all branch databases and their worktree status
bun run db:branch:list

# Seed a fresh database with dev essentials
bun run db:seed

Seed credentials: dev@roxabi.local / password123 (1 user, 1 organization, RBAC roles seeded).

All scripts run from apps/api/ and use docker exec against the container named by POSTGRES_CONTAINER (default: roxabi-postgres). No local psql installation is required.

Database Scripts (Root-Level)

Root-level wrappers load .env automatically and delegate to apps/api/. No need to cd into apps/api or set DATABASE_URL manually.

Common workflow:

# Fresh start after cloning
bun db:up && bun db:migrate && bun db:seed

# Reset and re-seed during development
bun db:reset && bun db:seed

db:reset and db:seed refuse to run when NODE_ENV=production (enforced at both the bash dispatcher and TypeScript script level).

Optional Variables

Docker Overrides (local dev — multi-project)

Override these when running multiple projects on the same machine to avoid container name and volume conflicts:

Set these in .env before running bun db:up. The branch database scripts (db:branch:*) pick up POSTGRES_CONTAINER and DB_BRANCH_PREFIX automatically.

Docker Overrides (local dev — multi-project)

Override these when running multiple projects on the same machine to avoid container name and volume conflicts:

Set these in .env before running bun db:up. The branch database scripts (db:branch:*) pick up POSTGRES_CONTAINER and DB_BRANCH_PREFIX automatically.

Public Variables (exposed to client)

Claude Code Agent Teams

To enable agent teams, set in your shell:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Agent definitions are in .claude/agents/*.md. See the Agent Teams Guide for details.

Complete Environment Variable Reference

Environment files (.env, .env.local) are resolved from the monorepo root only. Do not place .env files in app directories.

Core

Database

Authentication

Rate Limiting & API Features

Scheduled Tasks

Deployment

Public (Client-Side)

Docker (local dev)

Tooling

Derived Variables

Some environment variables default to the value of another variable when not explicitly set. This allows common deployments to be configured with a single value while still supporting advanced overrides.

Precedence: an explicit value in .env always takes precedence silently — the fallback only applies when the variable is absent or empty.

For typical single-domain deployments, setting APP_URL and APP_NAME is sufficient and the derived variables require no further configuration.

Rate Limit Presets

RATE_LIMIT_PRESET selects a named configuration that sets sensible rate limit defaults as a group. This avoids having to tune five individual variables for common scenarios.

On/off toggle: RATE_LIMIT_ENABLED remains the independent kill switch — it disables rate limiting entirely regardless of which preset is active.

Individual overrides: any of the RATE_LIMIT_* variables set explicitly in .env take precedence over the preset values for that specific parameter. This allows mixing presets with targeted adjustments without having to redeclare every value.

Dev-core Configuration

Agent orchestration settings are stored in .claude/dev-core.yml, which is committed to the repository. This file holds GitHub Projects field IDs and other workflow metadata used by Claude Code agent orchestration — it has no effect on the application at runtime.

The file is auto-populated by the /init skill when you first set up the project. You do not normally need to edit it by hand.

Values are resolved using a 3-tier fallback:

1. YAML — .claude/dev-core.yml (committed, shared across the team)
2. Environment variable — shell or .env override for per-developer customization
3. Live lookup — gh repo view for GITHUB_REPO when neither of the above is present

TypeScript Configuration

Root tsconfig.json provides base settings. Each app/package extends it:

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist"
  }
}

Biome Configuration

Linting and formatting configured in biome.json:

• 2-space indentation
• Single quotes
• No semicolons (ASI)
• 100 character line width

TurboRepo Configuration

Tasks defined in turbo.jsonc:

• dev - Run development servers
• build - Build all packages
• codegen - Generate routes and i18n files
• typecheck - Type checking
• lint - Run linter
• test - Run tests
• clean - Remove build artifacts and caches
• license:check - Scan dependency licenses for compliance

Environment Variables in Turbo

The root turbo.jsonc declares env arrays for variables that affect build output — changing these values invalidates the Turbo cache:

• codegen: API_URL, APP_URL, VITE_*
• build: API_URL, APP_URL, KV_*, REDIS_*, VITE_*
• test: CI, VITEST

Wildcard patterns (e.g. VITE_*) automatically match all env vars with that prefix — no manual update to turbo.jsonc needed when adding new vars with a known prefix. For new prefixes, add a wildcard pattern to the relevant task.

The API app extends the root config via apps/api/turbo.json with passThroughEnv for runtime secrets (database, auth). These are available at runtime but don't affect the build cache, preventing unnecessary rebuilds when only secrets change.

IDE Setup

VS Code

Recommended extensions:

• Biome
• TypeScript
• Turbo Console Log

Settings:

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true
}

Production Environment

Production runs entirely on Vercel with two projects (web + API). Environment variables are configured in each project's dashboard.

Vercel — Web Project

Configure in Vercel dashboard under Settings > Environment Variables:

Vercel — API Project

Configure in Vercel dashboard under Settings > Environment Variables (manual vars) or via Marketplace Integrations (auto-injected vars):

Auto-injected vars are managed by their respective Vercel Marketplace integrations and do not need manual configuration. They appear with an integration badge in the Vercel dashboard. For local development, these vars still need to be set manually in .env.

Note: Vercel auto-sets NODE_ENV=production. NestJS runs as a Vercel Function with Fluid compute.

See the Deployment Guide for full setup instructions.