#Debugging

Tips for debugging issues in local development.

#Viewing logs

When running npm run dev, logs from all services appear in your terminal. For structured logging, metrics, and distributed tracing, see Observability.

To view Docker container logs separately:

# All container logs
docker compose logs

# Follow logs in real-time
docker compose logs -f

# Specific service
docker compose logs auth-service

# Last 100 lines
docker compose logs --tail 100

#Hot reload

Services automatically restart when you save changes. The generated docker-compose.yml mounts your source code:

services:
  auth-service:
    volumes:
      - ./apps/auth-service/src:/app/src

If changes aren't picked up:

1. Check the file is inside src/
2. Restart: Ctrl+C then npm run dev

#Database access

#pgAdmin (built-in)

tsdevstack automatically generates pgAdmin with all your databases pre-configured:

http://localhost:5050
Login: admin@localhost.com / admin

All service databases appear in the sidebar. Database credentials are pre-loaded via pgpass, so clicking a database connects automatically - no password prompts.

#Prisma Studio

Each service with a database has a generated .env file with DATABASE_URL. Run Prisma Studio for a service:

cd apps/auth-service && npx prisma studio

Opens at http://localhost:5555 with a visual interface for browsing and editing data. Run from the service directory to use its .env file.

#CLI access

Each service has its own database container. Connect via Docker:

# Connect to auth database
docker compose exec auth-db psql -U $AUTH_DB_USER -d auth-service

# Connect to offers database
docker compose exec offers-db psql -U $OFFERS_DB_USER -d offers-service

Or directly (if you have psql installed):

# User and password are in .secrets.local.json (AUTH_DB_USER / AUTH_DB_PASSWORD)
psql postgresql://<user>:<password>@localhost:5432/auth-service

#Other GUI tools

You can also use DBeaver, TablePlus, or similar tools:

Ports are auto-assigned starting from 5432. Check docker-compose.yml for actual port mappings. Passwords are generated by the framework and stored in .secrets.local.json.

#Common issues

#Port already in use

# Find what's using the port
lsof -i :8000

# Kill it
kill -9 <PID>

#Container won't start

Check logs for the specific service:

docker compose logs auth-service

Common causes: missing env vars, syntax errors, database not ready.

#Kong returns 502

The gateway can't reach the backend. Check the service is running:

docker compose ps

If services are unhealthy, regenerate configs and restart:

npx tsdevstack sync
docker compose down && npm run dev

#TypeScript errors

Check compilation:

npm run build -w auth-service

#Debug checklist

1. Check logs: docker compose logs -f
2. Verify containers: docker compose ps
3. Regenerate configs: npx tsdevstack sync
4. Restart: docker compose down && npm run dev
5. Rebuild: docker compose build --no-cache