​
Prerequisites

Ensure the following are installed on your machine:
ToolVersionPurpose
Node.js20+JavaScript runtime
pnpm9+Package manager
Docker24+Local services (DB, Redis, etc.)
Docker Composev2+Service orchestration
Git2.40+Version control
Bun1.1+WebSocket server runtime
We recommend using fnm or nvm to manage Node.js versions. The repository includes a .node-version file.

​
Step-by-Step Setup

1

Clone the Repository

git clone https://github.com/obeya-cloud/obeya.git
cd obeya-cloud
2

Install Dependencies

pnpm install
This installs all dependencies across the monorepo using pnpm workspaces.
3

Start Infrastructure Services

docker compose -f docker/docker-compose.dev.yml up -d
This starts:
  • PostgreSQL 16 on port 5432
  • Redis 7 on port 6379
  • MinIO (S3-compatible storage) on port 9000 (console: 9001)
  • Meilisearch on port 7700
  • Mailpit (email testing) on port 8025
4

Configure Environment

cp .env.example .env
The default .env.example is pre-configured for local development. Review and adjust if needed:
# Database
DATABASE_URL="postgresql://obeya:obeya@localhost:5432/obeya"

# Auth
AUTH_SECRET="your-dev-secret-change-in-production"
AUTH_URL="http://localhost:3000"

# Redis
REDIS_URL="redis://localhost:6379"

# Storage
S3_ENDPOINT="http://localhost:9000"
S3_ACCESS_KEY="minioadmin"
S3_SECRET_KEY="minioadmin"
S3_BUCKET="obeya-dev"

# Search
MEILI_URL="http://localhost:7700"
MEILI_MASTER_KEY="dev-master-key"

# WebSocket
WS_URL="ws://localhost:3001"
5

Set Up the Database

# Push the schema to the database
pnpm db:push

# Seed with sample data
pnpm db:seed
The seed script creates a sample organization with workspaces, projects, boards, and items.
6

Start the Dev Servers

pnpm dev
This starts all applications in parallel via Turborepo:

​
Seed Data Credentials

After seeding, you can log in with these test accounts:
EmailPasswordRole
admin@example.compassword123Owner
member@example.compassword123Member
guest@example.compassword123Guest
The seed creates an organization at demo.localhost:3000.

​
Common Commands

# Development
pnpm dev                  # Start all apps in dev mode
pnpm dev --filter=web     # Start only the web app
pnpm dev --filter=ws      # Start only the WebSocket server

# Database
pnpm db:push              # Push schema changes to DB
pnpm db:generate          # Generate migration files
pnpm db:migrate           # Run pending migrations
pnpm db:seed              # Seed sample data
pnpm db:studio            # Open Drizzle Studio (DB browser)

# Testing
pnpm test                 # Run unit tests
pnpm test:e2e             # Run end-to-end tests (Playwright)
pnpm test:coverage        # Run tests with coverage report

# Code Quality
pnpm lint                 # Run ESLint
pnpm format               # Run Prettier
pnpm typecheck            # Run TypeScript type checking

# Build
pnpm build                # Production build
pnpm clean                # Clean all build artifacts

​
Troubleshooting

If port 3000 is taken, modify the PORT env variable or stop the conflicting process:
lsof -i :3000
kill -9 <PID>
Ensure Docker is running and the PostgreSQL container is healthy:
docker compose -f docker/docker-compose.dev.yml ps
docker compose -f docker/docker-compose.dev.yml logs postgres
Clear the pnpm store and retry:
pnpm store prune
rm -rf node_modules
pnpm install