gridpilot.gg/README.docker.md

Docker Setup for GridPilot

This document describes the Docker setup for local development and production deployment of GridPilot.

Quick Start

Development

Start all services with hot-reloading:

npm run docker:dev:build

This will:

• Start PostgreSQL database on port 5432
• Start API on port 3000 (with debugger on 9229)
• Start Website on port 3001
• Enable hot-reloading for both apps

Access:

• Website: http://localhost:3001
• API: http://localhost:3000
• Database: localhost:5432

Production

Start all services in production mode:

npm run docker:prod:build

This will:

• Build optimized Docker images
• Start PostgreSQL, Redis, API, Website, and Nginx
• Enable health checks, auto-restart, and resource limits
• Configure caching and performance optimizations

Access:

• Nginx (Website + API): http://localhost:80

Available Commands

Development

• npm run docker:dev - Start dev environment
• npm run docker:dev:build - Rebuild and start
• npm run docker:dev:down - Stop services
• npm run docker:dev:logs - View logs
• npm run docker:dev:clean - Stop and remove volumes

Production

• npm run docker:prod - Start prod environment
• npm run docker:prod:build - Rebuild and start
• npm run docker:prod:down - Stop services
• npm run docker:prod:logs - View logs
• npm run docker:prod:clean - Stop and remove volumes

Environment Variables

Development (.env.development)

Copy and customize as needed. Default values work out of the box.

Production (.env.production)

IMPORTANT: Update these before deploying:

• Database credentials (POSTGRES_PASSWORD, DATABASE_URL)
• API URLs (NEXT_PUBLIC_API_URL, NEXT_PUBLIC_SITE_URL)
• Vercel KV credentials (required for production)

Architecture

Development Setup

• Hot-reloading enabled via volume mounts
• Source code changes reflect immediately
• Database persisted in named volume
• Debug port exposed for API (9229)

Production Setup

• Multi-stage builds for optimized images
• Only production dependencies included
• Nginx reverse proxy for both services
• Health checks for all services
• Auto-restart on failure

Docker Services

API (NestJS)

• Dev: apps/api/Dockerfile.dev
• Prod: apps/api/Dockerfile.prod
• Port: 3000
• Debug: 9229 (dev only)

Website (Next.js)

• Dev: apps/website/Dockerfile.dev
• Prod: apps/website/Dockerfile.prod
• Port: 3001 (dev), 3000 (prod)

Database (PostgreSQL)

• Image: postgres:15-alpine
• Port: 5432 (internal)
• Data: Persisted in Docker volume
• Optimized with performance tuning parameters

Redis (Production only)

• Image: redis:7-alpine
• Port: 6379 (internal)
• Configured with:
  • LRU eviction policy
  • 512MB max memory
  • AOF persistence
  • Password protection

Nginx (Production only)

• Reverse proxy for website + API
• Features:
  • Rate limiting (API: 10r/s, General: 30r/s)
  • Security headers (XSS, CSP, Frame-Options)
  • Gzip compression
  • Static asset caching
  • Connection pooling
  • Request buffering
• Port: 80, 443

Troubleshooting

Services won't start

# Clean everything and rebuild
npm run docker:dev:clean
npm run docker:dev:build

Hot-reloading not working

Check that volume mounts are correct in docker-compose.dev.yml

Database connection issues

Ensure DATABASE_URL in .env matches the database service configuration

Check logs

# All services
npm run docker:dev:logs

# Specific service
docker-compose -f docker-compose.dev.yml logs -f api
docker-compose -f docker-compose.dev.yml logs -f website
docker-compose -f docker-compose.dev.yml logs -f db

Tips

1. First time setup: Use docker:dev:build to ensure images are built
2. Clean slate: Use docker:dev:clean to remove all data and start fresh
3. Production testing: Test prod setup locally before deploying
4. Database access: Use any PostgreSQL client with credentials from .env file
5. Debugging: Attach debugger to port 9229 for API debugging

Production Deployment

Before deploying to production:

1. Update .env.production with real credentials
2. Configure SSL certificates in nginx/ssl/
3. Update Nginx configuration for HTTPS
4. Set proper domain names in environment variables
5. Consider using Docker secrets for sensitive data

File Structure

.
├── docker-compose.dev.yml       # Development orchestration
├── docker-compose.prod.yml      # Production orchestration
├── .env.development             # Dev environment variables
├── .env.production              # Prod environment variables
├── apps/
│   ├── api/
│   │   ├── Dockerfile.dev       # API dev image
│   │   ├── Dockerfile.prod      # API prod image
│   │   └── .dockerignore
│   └── website/
│       ├── Dockerfile.dev       # Website dev image
│       ├── Dockerfile.prod      # Website prod image
│       └── .dockerignore
└── nginx/
    └── nginx.conf               # Nginx configuration