Local Development Setup

Two modes are available. The Docker Stack is recommended for day-to-day development.

Mode	Command	Best for
Docker Stack (recommended)	pnpm run dev:stack:up	Day-to-day development
Infra-Only + Host Apps	pnpm run dev:infra:up + pnpm run dev	Native debugging, macOS without VirtioFS

---

One-Time Setup

1. Prerequisites

macOS: Docker Desktop required. After installing, enable VirtioFS for fast hot reload:

Docker Desktop → Settings → General → "Use Virtualization framework" → Apply & Restart

VirtioFS on macOS

Without VirtioFS, file-watching inside Docker containers is noticeably slow. Hot reload will work but feel laggy. Check this setting before proceeding.

Linux: Docker Engine + Docker Compose plugin. No extra settings required.

Windows: Use WSL2 with Docker Desktop's WSL integration. Clone and run the repository inside the WSL2 filesystem; native Windows development is not supported.

2. Copy environment files

cp apps/server/.env.example    apps/server/.env
cp apps/webapp/.env.example    apps/webapp/.env
cp apps/marketing/.env.example apps/marketing/.env

apps/webapp/.env and apps/marketing/.env are pre-filled — no changes needed.

For apps/server/.env, fill in the following values:

Variable	How to get it
APP_KEY	cd apps/server && node ace generate:key
BETTER_AUTH_SECRET	cd apps/server && node ace generate:key
HEALTH_SECRET	cd apps/server && node ace generate:key
REDIS_PASSWORD	From 1Password vault
RESEND_API_KEY	From 1Password vault
BREVO_API_KEY	From 1Password vault

Docker Stack overrides DB/Redis hosts

DB_HOST and REDIS_HOST are automatically overridden inside the stack. You only need to set the secrets above.

3. Set up HTTPS certificates

cd infra/local_dev
chmod +x setup-https.sh
./setup-https.sh

What the script does:

1. Installs mkcert (if not present)
2. Installs a local CA into your system trust store (may prompt for your password)
3. Generates infra/local_dev/certs/local.cert.pem and certs/local.key.pem, covering jubiloop.localhost and *.jubiloop.localhost
4. Linux only: adds /etc/hosts entries for all five domains (macOS resolves *.localhost automatically — no /etc/hosts changes needed)

Run once in each worktree that runs Docker

The certificate files are gitignored and bind-mounted from the active worktree. A new worktree does not receive them from Git, so run setup-https.sh there or copy the existing certs/ directory before starting its stack. The trusted mkcert CA is machine-wide and normally needs installation only once.

---

Docker Stack (Recommended)

Starting up

# Start in background (recommended)
pnpm run dev:stack:up

# Start in foreground (see all logs in terminal)
pnpm run dev:stack

First run: ~2–3 minutes to download images, install dependencies, and build shared packages. Subsequent starts are near-instant unless pnpm-lock.yaml changed.

What starts automatically

Service	What it does
install	Runs pnpm install --frozen-lockfile if lockfile changed, then builds shared-types and auth-client. Exits when done.
postgres	PostgreSQL 15 on port 5433
redis	Redis 7 on port 6379
server	Runs node ace migration:run --force then pnpm run dev with HMR
webapp	Vite dev server with HMR
marketing	Next.js dev server with Fast Refresh
ui-prototype	Vite dev server for the design prototype (React 18 mock-data sandbox)
packages	tsup --watch for auth-client and shared-types
docs	VitePress dev server
caddy	HTTPS reverse proxy

Migrations run automatically on every stack start (via node ace migration:run --force in the server container's startup command).

Local URLs

App	URL
Web App (React)	https://app.jubiloop.localhost
API (AdonisJS)	https://api.jubiloop.localhost
Marketing (Next.js)	https://jubiloop.localhost
UI Prototype	https://lab.jubiloop.localhost
Docs (VitePress)	https://docs.jubiloop.localhost

Daily commands

pnpm run dev:stack:up      # Start in background
pnpm run dev:stack:down    # Stop all containers
pnpm run dev:stack:logs    # Stream logs
pnpm run dev:stack:restart # Restart existing containers; does not switch worktree bind mounts
pnpm run dev:stack:rebuild-deps # Reinstall dependencies while preserving database data
pnpm run dev:stack:rebuild # Rebuild images and delete all local volumes and data

Switching worktrees

All worktrees use the same Compose project, container names, and named PostgreSQL, Redis, and node_modules volumes. Only one full stack can run at a time, and its data is shared. restart does not update source bind mounts. From the currently active worktree run pnpm run dev:stack:down, then run pnpm run dev:stack:up in the destination worktree so Docker recreates the containers with that worktree's paths. Use dev:stack:rebuild-deps if dependency versions differ. Do not use dev:stack:rebuild unless deleting the shared local data is intended.

Running commands inside the stack

# Run tests
docker exec -it jubiloop_dev_server node ace test
docker exec -it jubiloop_dev_server node ace test --suite unit
docker exec -it jubiloop_dev_server node ace test --suite functional

# Database
docker exec -it jubiloop_dev_server node ace migration:run
docker exec -it jubiloop_dev_server node ace repl

# Access databases directly
docker exec -it jubiloop_dev_postgres psql -U postgres -d jubiloop_dev_db
docker exec -it jubiloop_dev_redis redis-cli

Container names (Docker Stack)

Service	Container name
postgres	jubiloop_dev_postgres
redis	jubiloop_dev_redis
install	jubiloop_dev_install
server	jubiloop_dev_server
webapp	jubiloop_dev_webapp
marketing	jubiloop_dev_marketing
ui-prototype	jubiloop_dev_ui_prototype
packages	jubiloop_dev_packages
docs	jubiloop_dev_docs
caddy	jubiloop_dev_caddy

---

Dev TUI Dashboard

The Dev TUI is an optional interactive terminal dashboard for managing the local dev environment without memorising Docker commands.

./dev-tui.sh        # from repo root
pnpm run dev:tui     # via pnpm

The script auto-builds a Go binary on first launch (no Go required — Docker is used as a fallback builder). The built binary lives at infra/local_dev/bin/dev-tui (gitignored) and is auto-rebuilt whenever source files change.

What the TUI provides

Section	Features
Services	Start/stop full stack or infra-only, restart individual services, tail logs, shell into any container, open URLs in browser
Server & Database	Run migrations, seed or reset local data, open the backend REPL, run setup:dev
Connections	Open psql shell, Redis CLI, copy DB connection URL to clipboard
Code Quality	Lint, lint-fix, format, run tests, build, type-check, security audit
Maintenance	Rebuild containers, install dependencies, clear Turbo cache, wipe volumes, run HTTPS cert setup

Key features:

• Real-time health monitoring: Docker container status + HTTP health checks every 5 seconds
• Docker/Local execution mode toggle (Tab) — runs commands inside containers or directly on host
• Fuzzy command search (/) across all 32 menu items
• Scrollable output viewer for lint, test, and migration results
• Persistent preferences (.tui-state.json, gitignored)

For full keyboard shortcuts, press ? inside the TUI.

---

Alternative: Infra-Only + Host Apps

See Host-Mode Development. Use this when:

• Native debugging with Node.js inspector
• macOS without VirtioFS enabled
• Running Japa tests directly on the host

---

Service Reference

Service	Host port	Docker Stack container	Infra-only container
PostgreSQL	5433	jubiloop_dev_postgres	jubiloop_local_dev_postgres
Redis	6379	jubiloop_dev_redis	jubiloop_local_dev_redis
Caddy	80, 443	jubiloop_dev_caddy	jubiloop_local_dev_caddy_proxy

Container names differ between modes

Docker Stack uses jubiloop_dev_*. Infra-only uses jubiloop_local_dev_*. Use the right name in docker exec commands.

---

Troubleshooting

Use the Troubleshooting guide for logs, port and certificate diagnostics, dependency recovery, and local database reset procedures.

---

Next: Git Worktrees for parallel development across branches