goodgo-platform/docs/dev-environment.md

Development Environment

Prerequisites

• Docker Engine 24+ & Docker Compose v2
• Node.js 22 LTS
• pnpm 10.27+ — install via corepack enable && corepack prepare pnpm@latest --activate

Quick Start

# 1. Copy environment variables
cp .env.example .env

# 2. Start all infrastructure services
docker compose up -d

# 3. Verify all services are healthy
docker compose ps

# 4. Install dependencies
pnpm install

# 5. Generate Prisma client
pnpm db:generate

# 6. Run database migrations
pnpm db:migrate:dev

# 7. Seed the database (optional)
pnpm db:seed

# 8. Start API and Web in dev mode
pnpm dev

API runs at http://localhost:3001/api/v1, Web at http://localhost:3000.

Swagger UI: http://localhost:3001/api/v1/docs — interactive API documentation.

Infrastructure Services

Service	Port(s)	Description	Dashboard/UI
PostgreSQL + PostGIS	5432	Database with spatial queries	—
Redis	6379	Cache, sessions, queue	—
Typesense	8108	Full-text search engine	http://localhost:8108/health
MinIO	9000 / 9001	S3-compatible object storage	http://localhost:9001 (console)
AI Services	8000	FastAPI — AVM + moderation	http://localhost:8000/health
Prometheus	9090	Metrics collection	http://localhost:9090
Grafana	3002	Dashboards & monitoring	http://localhost:3002

Common Commands

Docker Compose

# Start services
docker compose up -d

# View logs (all or specific service)
docker compose logs -f
docker compose logs -f postgres

# Stop services (data preserved in volumes)
docker compose down

# Stop and remove all data
docker compose down -v

# Restart a single service
docker compose restart redis

# Check service health
docker compose ps

Development

pnpm dev              # Start all apps in watch mode
pnpm build            # Build all packages
pnpm lint             # ESLint across monorepo
pnpm typecheck        # TypeScript type checking
pnpm format           # Prettier formatting
pnpm test             # Run unit/integration tests

Database

pnpm db:generate      # Regenerate Prisma client
pnpm db:migrate:dev   # Create and apply migrations
pnpm db:seed          # Seed database
pnpm db:studio        # Open Prisma Studio (visual editor)
pnpm db:reset         # Reset database (destructive)

E2E Testing

pnpm test:e2e         # Run all E2E tests
pnpm test:e2e:api     # API tests only
pnpm test:e2e:web     # Web UI tests only
pnpm test:e2e:report  # Open HTML test report

Connecting to Services

PostgreSQL

# Via psql
psql postgresql://goodgo:goodgo_secret@localhost:5432/goodgo

# Verify PostGIS
psql postgresql://goodgo:goodgo_secret@localhost:5432/goodgo -c "SELECT PostGIS_Version();"

Redis

redis-cli -p 6379 ping

Typesense

curl http://localhost:8108/health

MinIO

• API: http://localhost:9000
• Console: http://localhost:9001 (login with MINIO_ACCESS_KEY / MINIO_SECRET_KEY from your .env)

AI Services

curl http://localhost:8000/health

Grafana

• URL: http://localhost:3002
• Login: admin / admin (default, configurable via .env)

Troubleshooting

• Port conflict — Change ports in .env (e.g., DB_PORT=5433)
• Permission issues — Run docker compose down -v and restart
• PostGIS not available — Ensure using postgis/postgis:16-3.4 image
• Prisma client out of date — Run pnpm db:generate after pulling schema changes
• AI service not starting — Check docker compose logs ai-services for Python dependency errors
• Typesense unhealthy — Verify TYPESENSE_API_KEY matches in .env and Docker config