Getting Started

Quick start guide to use the Roxabi Boilerplate.

Prerequisites

• Node.js >= 24 (for compatibility)
• Bun >= 1.3
• Git
• GitHub CLI (gh)
• Docker (for local PostgreSQL)
• Claude Code (optional but recommended)

1. Create the Project

Clone the boilerplate

# Option A: Direct clone (to contribute to the boilerplate)
git clone https://github.com/MickaelV0/roxabi_boilerplate.git my-project
cd my-project

# Option B: Use as template (for a new project)
gh repo create my-project --template MickaelV0/roxabi_boilerplate --private
gh repo clone my-project
cd my-project

Configure the remote (if direct clone)

# Remove the boilerplate's origin remote
git remote remove origin

# Create your own GitHub repo
gh repo create my-project --private --source=. --push

2. Configure GitHub Project & Labels

Set up the project board, status columns, custom fields (Size, Priority), labels, and board automation workflows.

Full setup instructions: Issue Management > Project Board Setup

Labels are included in the template repo. If creating manually, the issue management doc has the full gh label create commands.

3. Configure GitHub Repository

Rename default branch to main

If your repository uses master as the default branch, rename it to main:

# Rename master to main on GitHub
gh api repos/OWNER/REPO/branches/master/rename -f new_name=main

# Update local repository
git fetch origin
git branch -m master main
git branch -u origin/main main
git remote set-head origin -a

Enable GitHub Discussions

# Enable discussions on the repository
gh repo edit --enable-discussions

Or via Settings > General > Features > check Discussions.

Configure branch protection

In Settings > Branches > Add rule for main:

• Require a pull request before merging
• Require approvals (1)
• Dismiss stale pull request approvals when new commits are pushed
• Require conversation resolution before merging
• Require status checks to pass before merging
  • ci (when CI is configured)
• Do not allow bypassing the above settings

Or via API:

gh api repos/OWNER/REPO/branches/main/protection -X PUT \
  --input - <<'EOF'
{
  "required_status_checks": null,
  "enforce_admins": false,
  "required_pull_request_reviews": {
    "dismiss_stale_reviews": true,
    "require_code_owner_reviews": false,
    "required_approving_review_count": 1
  },
  "restrictions": null,
  "allow_force_pushes": false,
  "allow_deletions": false,
  "required_conversation_resolution": true
}
EOF

4. Configure CI/CD (Optional)

CI/CD workflows are included and work out of the box. For faster builds, configure Turbo Remote Cache:

Turbo Remote Cache (~50% faster CI)

1. Create a free Vercel account
2. Go to Settings > Tokens > Create token
3. In your GitHub repo: Settings > Secrets and variables > Actions
4. Add secret: TURBO_TOKEN (your Vercel token)
5. Add variable: TURBO_TEAM (your Vercel team name)

CI Pipeline

The CI pipeline runs automatically on:

• Pull requests to main or staging
• Pushes to main or staging

Jobs: lint / typecheck / test (parallel) → build → e2e (conditional)

To run E2E tests on a PR, add the e2e label.

CD Pipeline

Deployment runs automatically on pushes to main via Vercel:

• Web (TanStack Start) — auto-deploys to Vercel (SSR, edge caching, Fluid compute)
• API (NestJS) — auto-deploys to Vercel (zero-config NestJS, Fluid compute)

No Docker or SSH needed — Vercel watches the GitHub repo directly.

First-time setup: Create two Vercel projects (web + API) from the same repo. See the Deployment Guide.

Marketplace integrations: For Neon, Resend, and Upstash, install the Vercel Marketplace integrations instead of manually configuring env vars. See the Deployment Guide for step-by-step instructions.

5. Install Dependencies

# Install all monorepo dependencies
bun install

6. Configure Environment

# Copy the example file
cp .env.example .env

# Edit with your values
# DATABASE_URL, DATABASE_APP_URL, API keys, etc.

7. Start the Database

# Start PostgreSQL via Docker Compose
bun db:up

# Verify it's running and healthy
docker compose ps

# Apply migrations
bun db:migrate

# Seed dev data (user, org, RBAC)
bun db:seed

Note: Data persists across restarts. To stop: bun db:down. To wipe and re-seed: bun db:reset && bun db:seed.

Troubleshooting: If port 5432 is already in use, stop your local PostgreSQL first (sudo systemctl stop postgresql or brew services stop postgresql).

8. Run the Project

# Run all apps in dev mode
bun dev

# Or individually
bun --filter @repo/web dev
bun --filter @repo/api dev

9. Verify Installation

• Frontend: http://localhost:3000
• API: http://localhost:4000
• API Docs (Swagger): http://localhost:4000/api/docs
• Email Preview: http://localhost:3001
• Documentation: http://localhost:3000/docs (served by bun docs)

Useful Commands

Next Steps

1. Read the Vision to understand the project
2. Check the Architecture
3. Check the open issues
4. Set up Deployment when ready for production