blackroad-os-docs/docs/guides/getting-started-local.md

id, title, slug, description, tags, status

id	title	slug	description	tags	status
guides-getting-started-local	Getting Started - Local Development	/guides/getting-started-local	Set up BlackRoad OS for local development	guides getting-started local	stable

Getting Started - Local Development

This guide walks you through setting up BlackRoad OS services for local development.

Prerequisites

Before you begin, ensure you have:

• Node.js 20+ installed (Download)
• npm or pnpm package manager
• Git for cloning repositories
• Docker (optional, for Redis/PostgreSQL)
• PostgreSQL 14+ (local or Docker)
• Redis 6+ (local or Docker)

Quick Start

1. Clone Repositories

Start with the core services:

# Create a workspace directory
mkdir blackroad-os && cd blackroad-os

# Clone core repositories
git clone https://github.com/BlackRoad-OS/blackroad-os-core.git
git clone https://github.com/BlackRoad-OS/blackroad-os-api.git
git clone https://github.com/BlackRoad-OS/blackroad-os-operator.git
git clone https://github.com/BlackRoad-OS/blackroad-os-web.git

2. Set Up Database

Using Docker:

# Start PostgreSQL
docker run -d \
  --name blackroad-postgres \
  -e POSTGRES_PASSWORD=devpassword \
  -e POSTGRES_DB=blackroad_dev \
  -p 5432:5432 \
  postgres:14

# Start Redis
docker run -d \
  --name blackroad-redis \
  -p 6379:6379 \
  redis:latest

Or install locally per your OS instructions.

3. Configure Services

API Service

cd blackroad-os-api
npm install
cp .env.example .env

Edit .env:

DATABASE_URL=postgresql://postgres:devpassword@localhost:5432/blackroad_dev
REDIS_URL=redis://localhost:6379
API_PORT=3000
JWT_SECRET=local-dev-secret-change-me
OPERATOR_URL=http://localhost:3001

Run migrations:

npm run migrate

Operator Service

cd ../blackroad-os-operator
npm install
cp .env.example .env

Edit .env:

DATABASE_URL=postgresql://postgres:devpassword@localhost:5432/blackroad_dev
REDIS_URL=redis://localhost:6379
OPERATOR_PORT=3001
WORKER_CONCURRENCY=2

Web Service

cd ../blackroad-os-web
npm install
cp .env.example .env.local

Edit .env.local:

NEXT_PUBLIC_API_URL=http://localhost:3000
NEXT_PUBLIC_WS_URL=ws://localhost:3000

4. Start Services

Open separate terminal windows for each service:

Terminal 1 - API:

cd blackroad-os-api
npm run dev

Terminal 2 - Operator:

cd blackroad-os-operator
npm run dev

Terminal 3 - Web:

cd blackroad-os-web
npm run dev

5. Verify Setup

• API: http://localhost:3000/health
• Operator: http://localhost:3001/health
• Web: http://localhost:3030 (or configured port)

Development Workflow

Making Changes

1. Create a feature branch
2. Make your changes
3. Run tests: npm test
4. Run linter: npm run lint
5. Build: npm run build
6. Commit and push

Running Tests

# In any service directory
npm test                # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # Coverage report

Database Migrations

When schema changes are needed:

# Create migration
npm run migrate:create my-migration-name

# Run migrations
npm run migrate

# Rollback
npm run migrate:rollback

Troubleshooting

Database Connection Failed

• Verify PostgreSQL is running: docker ps | grep postgres
• Check connection string in .env
• Test connection: psql postgresql://postgres:devpassword@localhost:5432/blackroad_dev

Redis Connection Failed

• Verify Redis is running: docker ps | grep redis
• Test connection: redis-cli ping (should return PONG)

Port Already in Use

Change ports in .env files:

API_PORT=3010
OPERATOR_PORT=3011
# etc.

Module Not Found

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Next Steps

• Extending Agents - Create custom agents
• API Overview - Understand API structure
• Contributing Guide
• Coding Standards (planned)

See Also

• Repositories and Services - Complete repo map
• Local Development - Additional dev info
• Stack Map - Architecture overview