Development Setup

Prerequisites

Tool	Version	Purpose
Bun	1.3.8+	Package manager and JS/TS runtime
.NET SDK	10.0	Backend runtime
Docker	Latest	Infrastructure services
Docker Compose	v2+	Service orchestration

Quick Start

Run the automated setup script:

chmod +x scripts/setup-local.sh
./scripts/setup-local.sh

This script is idempotent (safe to run multiple times) and performs:

1. Copies .env.example to .env (if not exists)
2. Installs root dependencies (bun install)
3. Installs Wilo.App dependencies
4. Installs Wilo.Docs dependencies
5. Installs Wilo.Email dependencies
6. Restores .NET packages (dotnet restore Wilo.slnx)
7. Starts Docker infrastructure (docker compose up -d)
8. Waits for services to be healthy

Manual Setup

If you prefer manual setup:

# 1. Clone and enter the repository
git clone <repo-url>
cd wilo

# 2. Create environment file
cp .env.example .env

# 3. Install dependencies
bun install                              # Root (monorepo scripts, lefthook)
bun install --cwd sites/Wilo.App           # Vue frontend
bun install --cwd webs/Wilo.Docs          # VitePress docs
bun install --cwd services/Wilo.Email         # Email renderer

# 4. Restore .NET packages
dotnet restore Wilo.slnx

# 5. Start infrastructure
docker compose up -d

# 6. Wait for services, then start the API
dotnet run --project src/Wilo.Api

Running Services

After infrastructure is running, start the application services:

# Start API (port 5000)
dotnet run --project src/Wilo.Api

# Start frontend dev server (port 5173)
bun run app:dev

# Start documentation site
bun run docs:dev

# Start email renderer dev server (port 3050)
bun run email:dev

Service URLs

Service	URL	Purpose
API	http://localhost:5000	Main API
API Docs (Scalar)	http://localhost:5000/scalar	Interactive API documentation
Health Check	http://localhost:5000/health	Aggregated health status
Frontend	http://localhost:5173	Vue.js SPA
Email Renderer	http://localhost:3050	React Email rendering service
Aspire Dashboard	http://localhost:18888	OpenTelemetry dashboard
Mailpit	http://localhost:8025	Email testing UI
MinIO Console	http://localhost:9001	Object storage UI
Redis Insight	http://localhost:5540	Redis GUI

Available Commands

API (.NET)

bun run api:build            # Build the .NET solution
bun run api:restore          # Restore NuGet packages
bun run api:test             # Run all backend tests
bun run api:test:unit        # Run unit tests only
bun run api:test:arch        # Run architecture tests only
bun run api:test:integration # Run integration tests (requires Docker)
bun run api:format           # Auto-format C# code
bun run api:format:check     # Check C# formatting (CI mode)

Frontend (Vue)

bun run app:dev              # Start dev server with HMR
bun run app:build            # Production build
bun run app:lint             # Lint with auto-fix (oxlint)
bun run app:lint:check       # Lint check only (CI mode)
bun run app:format           # Auto-format (oxfmt)
bun run app:format:check     # Format check only (CI mode)
bun run app:test:unit        # Run Vitest unit tests
bun run app:test:e2e         # Run Playwright E2E tests

Email Renderer

bun run email:dev            # Start Hono dev server (port 3050)
bun run email:build          # Build TypeScript
bun run email:test           # Run Bun tests
bun run email:preview        # React Email preview server
bun run email:typecheck      # TypeScript compiler check
bun run email:lint           # Lint (oxlint)
bun run email:format         # Format (oxfmt)
bun run email:format:check   # Format check (CI mode)

Documentation

bun run docs:dev             # Start VitePress dev server
bun run docs:build           # Build static documentation site
bun run docs:preview         # Preview built site

Quality Checks

bun run check                # Run all quality checks
bun run check:full           # Full quality check (all projects)
bun run check:api            # API quality check only
bun run check:app            # Frontend quality check only
bun run check:email          # Email renderer quality check only
bun run check:docs           # Documentation build check only

Infrastructure Services

All infrastructure runs via Docker Compose:

Service	Port(s)	Image
PostgreSQL	5432	postgres:18.1-alpine
Redis	6379	redis:8.4-alpine
Redis Insight	5540	redis/redisinsight
MinIO	9000, 9001	minio/minio:RELEASE.2025-04-22T22-12-26Z
ClickHouse	8123	clickhouse/clickhouse-server:24.12-alpine
Mailpit	1025, 8025	axllent/mailpit
Email Renderer	3050	Built from services/Wilo.Email/Dockerfile
Aspire Dashboard	18888, 18889	mcr.microsoft.com/dotnet/aspire-dashboard
wilo-api	5000	Built from src/Wilo.Api/Dockerfile (context: repo root)
wilo-frontend	3000	Built from sites/Wilo.App/Dockerfile (context: sites/Wilo.App/)

EF Core Migrations

Each module has its own DbContext and its own migration history. Replace {Module} and {ModuleDbContext} with the target module name.

# Add a migration for a specific module
dotnet ef migrations add <MigrationName> \
  --project src/Wilo.Modules.<Module> \
  --startup-project src/Wilo.Api \
  --context <Module>DbContext \
  --output-dir Persistence/Migrations

# Apply migrations
dotnet ef database update \
  --project src/Wilo.Modules.<Module> \
  --startup-project src/Wilo.Api \
  --context <Module>DbContext

# Example: Identity module
dotnet ef migrations add AddRefreshTokens \
  --project src/Wilo.Modules.Identity \
  --startup-project src/Wilo.Api \
  --context IdentityDbContext \
  --output-dir Persistence/Migrations

Troubleshooting

WSL2 Build Errors (MSB3030/MSB3552)

Cross-filesystem builds on WSL2 may produce transient errors. Fix:

# Clean build artifacts and rebuild
dotnet clean Wilo.slnx
dotnet restore Wilo.slnx
dotnet build Wilo.slnx

Docker Services Not Starting

# Check service status
docker compose ps

# View logs for a specific service
docker compose logs -f postgresdb

# Restart all services
docker compose down && docker compose up -d