Local Development Startup Guide

Comprehensive guide for starting and troubleshooting the Orient local development environment.

Quick Start

# Start everything
./run.sh dev

# Stop everything
./run.sh dev stop

Containerized Test Environment

For production-like testing with all services running in Docker containers:

# Start test environment
./run.sh test

# View container logs
./run.sh test logs

# Show container status
./run.sh test status

# Stop test environment
./run.sh test stop

What ./run.sh test Does

1. Builds Docker images for all services:

   • bot-slack
   • bot-whatsapp
   • dashboard
   • opencode

2. Starts containers in dependency order:

   • PostgreSQL (database)
   • MinIO (object storage)
   • Dashboard API
   • OpenCode API
   • Bot services (Slack, WhatsApp)
   • Nginx (reverse proxy)

3. Applies database migrations from data/migrations/*.sql

4. Exposes services via Nginx at port 80

Test Environment Access Points

Test Environment vs Dev Mode

Verifying Test Environment

# Check all containers are running
docker ps --filter "name=orienter"

# Check dashboard health
curl http://localhost/dashboard/api/health

# View container logs
./run.sh test logs

# Check specific container
docker logs orienter-dashboard

What ./run.sh dev Does

1. Checks for orphaned processes on required ports
2. Starts Docker infrastructure (PostgreSQL, MinIO, Nginx)
3. Waits for PostgreSQL to be ready
4. Runs database migrations from data/migrations/
5. Seeds agent registry if empty
6. Starts Vite frontend dev server (port 5173)
7. Starts Dashboard API server (port 4098)
8. Starts WhatsApp bot (port 4097)
9. Starts Slack bot

Service Ports

Common Startup Errors and Solutions

1. ECONNREFUSED (Database not running)

Error:

AggregateError [ECONNREFUSED]

Cause: PostgreSQL container is not running.

Solution:

./run.sh dev stop
./run.sh dev

2. Password Authentication Failed

Error:

password authentication failed for user "aibot"

Cause: DATABASE_URL uses different credentials than PostgreSQL was configured with.

Solution:

# Check what credentials PostgreSQL uses
docker exec orienter-postgres-0 env | grep POSTGRES

# Update packages/dashboard/.env to match
DATABASE_URL=postgresql://orient:aibot123@localhost:5432/whatsapp_bot_0

# Restart
./run.sh dev stop && ./run.sh dev

3. Missing Module Export (ESM Resolution)

Error:

SyntaxError: The requested module '@orient/database-services' does not provide an export named 'X'

Cause: Package dist files are stale or missing.

Solution: Rebuild packages in dependency order:

pnpm --filter @orient/core build
pnpm --filter @orient/database build
pnpm --filter @orient/database-services build
pnpm --filter @orient/integrations build

4. Missing Database Table

Error:

relation "user_version_preferences" does not exist

Solution:

1. Check if migration exists in data/migrations/
2. If missing, create migration file
3. Restart: ./run.sh dev stop && ./run.sh dev

5. Container Name Conflict

Error:

Conflict. The container name "/orienter-postgres-0" is already in use

Solution:

./run.sh dev stop
docker rm orienter-postgres-0 2>/dev/null
./run.sh dev

Package Build Order

When ESM errors occur, rebuild in this order:

pnpm --filter @orient/core build
pnpm --filter @orient/database build
pnpm --filter @orient/database-services build
pnpm --filter @orient/integrations build

Database Migrations

Migration Location

data/migrations/*.sql

Creating a New Migration

cat > data/migrations/005_add_my_table.sql << 'EOF'
CREATE TABLE IF NOT EXISTS my_table (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL
);
EOF

Checking Applied Migrations

docker exec orienter-postgres-0 psql -U orient -d whatsapp_bot_0 -c "SELECT * FROM _migrations;"

Verification Checklist

# 1. API Health
curl http://localhost:4098/api/health

# 2. Frontend Loading
curl -s http://localhost:5173 | head -5

# 3. Database Connectivity
docker exec orienter-postgres-0 psql -U orient -d whatsapp_bot_0 -c "SELECT 1;"

# 4. Check Running Processes
ps aux | grep -E "tsx|vite" | grep -v grep

Environment Configuration

packages/dashboard/.env

DATABASE_URL=postgresql://orient:aibot123@localhost:5432/whatsapp_bot_0
DASHBOARD_JWT_SECRET=your-secret-here

Troubleshooting Commands

# View dashboard logs
tail -f logs/instance-0/dashboard-dev.log

# Check Docker containers
docker ps

# Connect to postgres
docker exec -it orienter-postgres-0 psql -U orient -d whatsapp_bot_0

# Check for errors
grep -i error logs/instance-0/*.log | tail -20

Blank Page / Loading Issues via Nginx (Port 80)

Symptoms

• Blank page or stuck on "Loading your workspace..." when accessing http://localhost:80
• No JavaScript console errors visible
• Network requests return 200/304 successfully
• React app intermittently fails to mount (#root element is empty)
• Direct access to http://localhost:5173 works perfectly

Root Causes

1. ES Module Execution Issues Through Proxy When Vite dev server runs behind Nginx proxy, ES modules can intermittently fail to execute:

• Module scripts load (network shows 200/304) but don't run
• No JavaScript errors - silent failure
• Issue is timing/race-condition related with Nginx proxying

2. Browser Extension Interference Extensions like MetaMask use SES (Secure EcmaScript) lockdown which can block:

• Vite's hot module replacement (HMR)
• React prototype modifications
• Look for "SES Removing unpermitted intrinsics" in console

Diagnosis

// In browser console on http://localhost:80/
document.getElementById('root')?.children?.length; // 0 = React not mounted

Solution: Use Direct Vite Access (Strongly Recommended)

For ALL daily development, use http://localhost:5173 directly:

http://localhost:5173/

Benefits:

• 100% reliable React mounting
• Faster hot reload (no Nginx proxy overhead)
• No browser extension conflicts
• Full API access (Vite proxies /api/ requests to port 4098)

Use http://localhost:80 (Nginx) ONLY when testing:

• Production-like routing scenarios
• Auth flows requiring specific hostnames
• Multi-service integration testing
• Always test in incognito mode to avoid extension conflicts

Creating Dashboard Users

When database is recreated, users are lost:

cd packages/dashboard
HASH=$(npx tsx -e "import bcrypt from 'bcryptjs'; bcrypt.hash('password', 10).then(h => console.log(h));")
docker exec orienter-postgres-0 psql -U orient -d whatsapp_bot_0 -c "
INSERT INTO dashboard_users (username, password_hash) VALUES ('username', '$HASH');
"