local-dev-workflowSafety 95Repository ShareFavorite skill

When to Use

• Adding a new microservice to api/
• Updating or creating Makefiles
• Changing port assignments
• Modifying docker-compose services
• Setting up a developer's local environment

Port Convention

Every service gets a unique local port. In Docker, all services use :8080 internally.

Rule: next service = next sequential port. Never reuse ports.

Environment Modes

Root Makefile Commands

make run            # Start ALL services in background (in-memory)
make stop           # Stop all background services
make logs           # Tail all service logs
make run-{service}  # Start single service
make test           # Run all tests
make test-{service} # Test single service
make build          # Build all binaries
make up             # docker-compose up -d
make down           # docker-compose down -v
make sqlc           # Regenerate sqlc code for all services

Per-Service Makefile Template

When creating a new service, its Makefile MUST follow the template in assets/service.Makefile.

Replace {name}, {assigned port from table}, {pg host port from table}, {service_name}, and {domain} with actual values.

Checklist: Adding a New Service

When adding a new service to the project:

1. Assign next sequential port in the port table above
2. Create api/{service}/Makefile following the template
3. Add run-{service} and test-{service} targets to root Makefile
4. Add pg-{service} container to docker-compose.yml
5. Add service container to docker-compose.yml
6. Add service URL env var to gateway in docker-compose.yml
7. Add proxy route in gateway's main.go
8. Add {SERVICE}_SERVICE_URL to gateway's config.go
9. Update this skill's port table if needed

Docker-Compose: Database per Service Pattern

Each service gets its own PostgreSQL container following the template in assets/docker-compose.service.yml.

Replace {service} and {host port} with actual values from the port table.

Critical: dev passwords are service name (e.g. auth/auth). Production uses secrets management.

File Locations

api/Makefile                      # API orchestrator — runs all services
api/gateway/Makefile              # Gateway service
api/auth/Makefile                 # Auth service
api/{service}/Makefile            # Future services
api/docker-compose.yml            # Docker full stack
api/logs/                         # Local dev log files (gitignored)
api/.pids/                        # Background process PIDs (gitignored)