Getting Started

This guide will help you set up the Chompardo monorepo for local development.

Prerequisites

• Node.js >= 18.0
• pnpm 9.0.0 or later
• Docker and Docker Compose (for PostgreSQL, Valkey, and Traefik)
• mkcert for local HTTPS certificates

Installation

1. Clone the repository

git clone https://github.com/chompardo/monorepo.git
cd monorepo

2. Configure wildcard DNS

Run the one-time DNS setup script to resolve *.chompardo.dev to 127.0.0.1:

bash scripts/setup-dns.sh

This installs dnsmasq via Homebrew and creates a macOS resolver for wildcard DNS. No manual /etc/hosts entries needed.

3. Install dependencies

pnpm install

4. Generate TLS certificates

pnpm generate-certs

This trusts the mkcert CA in your system keychain and generates a wildcard cert for *.chompardo.dev. The cert files are gitignored — each developer generates their own.

5. Start infrastructure

docker compose up -d

This starts:

• PostgreSQL on port 5432 (user: dev, password: abc123)
• Valkey on port 6379 (Redis-compatible session store)
• Traefik reverse proxy on port 443 with HTTPS (routes *.chompardo.dev subdomains, hot-reloads per-worktree routes)

6. Configure environment

Copy the example environment files:

cp apps/identity/.env.local.example apps/identity/.env.local
cp apps/app/.env.local.example apps/app/.env.local

7. Run database migrations

cd apps/identity && pnpm run migrate

8. Seed the OAuth client and configure the App

The App authenticates users via the Identity service using OIDC. You need to register an OAuth client:

cd apps/identity && pnpm run seed:oauth-client

Copy BFF_CLIENT_ID into apps/identity/.env.local. Copy OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET into apps/app/.env.local. See the App Getting Started guide for full details.

9. Start development servers

pnpm dev

This runs all applications in development mode:

Service	Direct URL	Subdomain
App	http://localhost:3001	https://main.chompardo.dev
Identity	http://localhost:3000	https://main-identity.chompardo.dev
Docs	http://localhost:6100	https://main-docs.chompardo.dev

Development Commands

Root commands

Command	Description
pnpm dev	Start all apps in development mode
pnpm build	Build all packages and apps
pnpm lint	Lint all workspaces (max 0 warnings)
pnpm format	Format code with oxfmt
pnpm check-types	Run TypeScript type checking
pnpm test	Run unit tests (vitest)
pnpm e2e	Run E2E tests (Playwright)

Filtering to specific workspaces

pnpm dev --filter=identity       # Run only the identity app
pnpm build --filter=@repo/ui     # Build only the UI package
pnpm lint --filter=identity      # Lint only the identity app

Troubleshooting

Database connection issues

Ensure Docker is running and the PostgreSQL container is up:

docker compose ps
docker compose logs postgres

Subdomain not resolving

Verify DNS is working:

dig +short test.chompardo.dev @127.0.0.1

If dnsmasq isn't running, restart it:

sudo brew services restart dnsmasq

Cache issues

Clear Turbo's cache if you experience stale builds:

turbo clean
pnpm install