Dev Webapp

Dev Webapp

Day-2 local development: Compose up/down, logs, env, common fixes.

Read first: ~/.cursor/skills/webapp-shared/reference.md

Quick reference

Env file: .env (from .env.example). Never commit .env.

Checklist: start dev stack

Dev-webapp start:
- [ ] 1. .env exists with valid Jwt__SigningKey
- [ ] 2. docker compose up --build -d
- [ ] 3. docker compose ps (all healthy)
- [ ] 4. curl health + optional login
- [ ] 5. Open http://localhost:5173

cd <app-root>
cp -n .env.example .env    # if missing
# Ensure Jwt__SigningKey set via ./scripts/generate-jwt-key.sh
docker compose up --build -d
docker compose ps
curl -sf http://localhost:8080/api/health

First boot: API auto-applies EF migrations in Development.

Checklist: stop / reset

# Stop containers (keep volumes)
docker compose down

# Stop + remove volumes (fresh DB)
docker compose down -v

# Rebuild single service after Dockerfile change
docker compose up -d --build api
docker compose up -d --build web

Logs

docker compose logs -f              # all services
docker compose logs -f api          # API only
docker compose logs -f web          # Vite
docker compose logs -f db           # Postgres
docker compose logs api --tail 100  # recent API lines

Look for: migration applied, JWT config error, DB connection refused, CORS errors.

Restart single service

docker compose restart api
docker compose restart web
docker compose restart db

After backend code changes, api with dotnet watch should hot-reload. If stuck, restart api.

Host-side development (optional)

When not using Compose for app processes:

# Backend
cd backend && dotnet watch run --project src/{App}.Api

# Frontend
cd frontend && npm run dev

Ensure .env or user secrets match host connection string (Host=localhost not Host=db).

Run tests locally

cd backend && dotnet test
cd frontend && npm ci && npm test -- --run && npm run build

Testcontainers needs Docker available to test runner.

Common fixes

JWT signing key error

Jwt:SigningKey must be set to a strong secret

./scripts/generate-jwt-key.sh
# Paste into .env → Jwt__SigningKey=...
docker compose up -d --force-recreate api

CORS blocked in browser

• Cors__Origins in .env must include exact browser origin: http://localhost:5173
• No trailing slash mismatch
• Recreate api after env change: docker compose up -d --force-recreate api

DB connection refused

docker compose ps db
docker compose logs db
# Wait for "database system is ready"
docker compose restart api

Check ConnectionStrings__Default uses Host=db inside Compose.

Port already in use

# Find process on 5173 or 8080
ss -tlnp | grep -E '5173|8080'
# Stop conflicting process or adjust ports in docker-compose.override.yml

Migrations out of sync

See add-migration skill:

cd backend
dotnet ef migrations add FixSchema ...
docker compose restart api

Frontend cannot reach API

• Dev: Vite proxy in vite.config.ts should target http://api:8080 in Docker or http://localhost:8080 on host
• Browser calls go to Vite origin; proxy forwards /api/*

Stale node_modules / dist

docker compose exec web npm ci
# or on host:
cd frontend && rm -rf node_modules dist && npm ci

Verify auth flow manually

curl -sf http://localhost:8080/api/health
curl -X POST http://localhost:8080/api/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"dev@test.local","password":"Password1!"}'

Then test login/refresh in browser at http://localhost:5173.

Do not

• Commit .env
• Set ASPNETCORE_ENVIRONMENT=Production for local dev unless testing prod behavior
• Expect prod Caddy in dev compose — Caddy is prod-only

Related skills

• First-time scaffold → create-webapp
• Schema changes → add-migration
• Production → deploy-webapp