Skip to main content

Docker Configuration

This guide covers Docker-based development and deployment for CivStart.

Docker Services​

PostgreSQL Database​

  • Image: postgres:16-alpine
  • Port: 5432
  • Database: civstart (production) / civstart_dev (development)
  • User: civstart
  • Extensions: uuid-ossp, pg_trgm, btree_gin

Redis Cache​

  • Image: redis:7-alpine
  • Port: 6379
  • Persistence: Enabled with AOF

Backend API​

  • Build: Multi-stage Dockerfile
  • Port: 3000
  • Health Check: /health endpoint
  • User: Non-root (nestjs:nodejs)

pgAdmin (Development Only)​

Quick Start​

1. Setup Environment​

pnpm docker:setup

2. Start Development Services​

pnpm docker:dev:up

3. Access Services​

Configuration​

Environment Variables​

Required variables in .env file:

# Database
POSTGRES_PASSWORD=secure_password
DATABASE_URL=postgresql://civstart:secure_password@postgres:5432/civstart

# Authentication
CLERK_SECRET_KEY=your_key
CLERK_PUBLISHABLE_KEY=your_key

# pgAdmin (development)
PGADMIN_EMAIL=admin@civstart.com
PGADMIN_PASSWORD=admin_password

Docker Compose Files​

  • docker-compose.dev.yml - Development configuration (database, Redis, pgAdmin)
  • docker-compose.staging.yml - Staging configuration with full backend
  • docker-compose.production.yml - Production configuration with full backend

Development Workflow​

# Terminal 1: Database services only
pnpm docker:dev:db

# Terminal 2: Backend with hot reload
pnpm dev:backend

# Terminal 3: Frontend with hot reload
pnpm dev:frontend

Full Docker Development​

# All services in containers
pnpm docker:dev:up

# View logs
pnpm docker:dev:logs

Database Management​

Migrations​

# Run migrations in container
pnpm docker:migrate

# Access database shell
pnpm docker:shell:db

pgAdmin Access​

  1. Open http://localhost:5050
  2. Login: admin@civstart.com / admin
  3. Add server:
    • Host: postgres-dev
    • Database: civstart_dev
    • User: civstart
    • Password: [from .env]

Prisma Studio​

# Open Prisma Studio in container
pnpm docker:db:studio

Security​

Production Security​

  • Non-root user in containers
  • Security headers via Helmet.js
  • Health checks for all services
  • Resource limits (configure in compose)

Development Security​

  • Isolated network
  • Environment variable validation
  • Default passwords (change in production!)

Troubleshooting​

Database Connection Failed​

# Check if database is ready
docker-compose logs postgres

# Wait for health check
docker-compose ps

Permission Errors​

# Reset file permissions
sudo chown -R $(whoami) .

Port Conflicts​

# Check what's using the port
lsof -i :5432

# Stop conflicting services
brew services stop postgresql

Useful Commands​

# View container resource usage
docker stats

# Clean up everything
pnpm docker:clean

# Rebuild from scratch
pnpm docker:rebuild

# Access container filesystem
pnpm docker:shell:backend

Production Deployment​

Environment Preparation​

# Create production environment file
cp .env.docker .env.prod

# Update with production values
nano .env.prod

Deployment​

# Deploy with production config
docker-compose --env-file .env.prod up -d

# Monitor deployment
docker-compose logs -f

Health Monitoring​

# Check service health
docker-compose ps

# View resource usage
docker stats civstart-backend civstart-postgres

Maintenance​

Updates​

# Pull latest images
docker-compose pull

# Restart with new images
docker-compose up -d

Backups​

# Database backup
docker-compose exec postgres pg_dump -U civstart civstart > backup.sql

# Restore from backup
docker-compose exec -T postgres psql -U civstart civstart < backup.sql

Log Management​

# View logs with timestamps
docker-compose logs -t -f

# Limit log size
docker-compose logs --tail=100 backend