goodgo-platform/docs/deployment.md

Deployment Guide

Overview

GoodGo Platform AI consists of four deployable services:

Service	Technology	Default Port
API	NestJS (Node.js)	3001
Web	Next.js	3000
AI Services	FastAPI (Python)	8000
Infrastructure	Docker Compose	Various

Prerequisites

• Docker Engine 24+ & Docker Compose v2
• Node.js 22 LTS
• pnpm 10.27+
• Python 3.12 (for AI services, if running outside Docker)

Environment Configuration

Copy .env.example to .env and configure all required values:

cp .env.example .env

Required Variables

Variable	Description	Example
DATABASE_URL	PostgreSQL connection string	postgresql://user:pass@host:5432/goodgo
JWT_SECRET	JWT signing key (min 32 chars)	Generate with openssl rand -hex 32
JWT_REFRESH_SECRET	Refresh token signing key	Generate with openssl rand -hex 32
REDIS_URL	Redis connection string	redis://localhost:6379
TYPESENSE_API_KEY	Typesense admin API key	Generate a secure random key

Optional Variables

Variable	Description	Default
API_PORT	API server port	3000
WEB_PORT	Web app port	3001
NODE_ENV	Environment mode	development
CORS_ORIGINS	Allowed CORS origins	—
CLAUDE_API_KEY	Claude API key (for content moderation)	—
NEXT_PUBLIC_MAPBOX_TOKEN	Mapbox token (for maps)	—
VNPAY_*, MOMO_*, ZALOPAY_*	Payment gateway credentials	—

Infrastructure Setup (Docker Compose)

Start all infrastructure services:

docker compose up -d

This starts:

• PostgreSQL 16 + PostGIS 3.4 (port 5432)
• Redis 7 (port 6379)
• Typesense 27 (port 8108)
• MinIO (API: 9000, Console: 9001)
• AI Services (port 8000)
• pg-backup — automated daily PostgreSQL backups at 02:00 UTC with verification at 04:00 UTC
• Loki (port 3100) — log aggregation
• Promtail — log collection agent (ships container logs to Loki)
• Prometheus (port 9090)
• Grafana (port 3002) — dashboards for metrics and logs

Verify all services are healthy:

docker compose ps

All services include health checks. Wait until all show healthy status.

Database Setup

# Generate Prisma client
pnpm db:generate

# Apply migrations
pnpm db:migrate:deploy

# Seed initial data (optional)
pnpm db:seed

Building for Production

API (NestJS)

cd apps/api
pnpm build

Output: apps/api/dist/

Run in production:

NODE_ENV=production PORT=3001 node apps/api/dist/main.js

Web (Next.js)

cd apps/web
pnpm build

Output: apps/web/.next/

Run in production:

NODE_ENV=production pnpm --filter web start

AI Services (FastAPI)

The AI service runs in Docker via docker compose. To build separately:

cd libs/ai-services
docker build -t goodgo-ai-services .
docker run -p 8000:8000 --env-file ../../.env goodgo-ai-services

Production Checklist

Security

• Set strong, unique JWT_SECRET and JWT_REFRESH_SECRET (min 32 characters)
• Set NODE_ENV=production
• Configure CORS_ORIGINS to only allow your domain(s)
• Change default database passwords
• Change default MinIO credentials (MINIO_USER, MINIO_PASSWORD)
• Change default Grafana credentials (GRAFANA_ADMIN_USER, GRAFANA_ADMIN_PASSWORD)
• Use a strong, unique TYPESENSE_API_KEY
• Enable SSL/TLS termination (reverse proxy)
• Set MINIO_USE_SSL=true if MinIO is exposed publicly

Database

• Run pnpm db:migrate:deploy (not db:migrate:dev)
• Enable PostgreSQL connection pooling (PgBouncer recommended)
• Configure automated backups
• Set appropriate max_connections in PostgreSQL config

Monitoring

• Verify Prometheus is scraping /metrics endpoint
• Import Grafana dashboards from monitoring/grafana/dashboards/
• Set up alerting rules for error rates and latency

Performance

• Configure Redis maxmemory and eviction policy
• Set appropriate Typesense --memory-limit
• Enable gzip/brotli compression in reverse proxy
• Configure CDN for static assets (Next.js /_next/static/)

Health Checks

Service	Endpoint	Expected Response
API	GET /health	{"status": "ok"}
API (Swagger)	GET /api/v1/docs	Swagger UI page
API (Metrics)	GET /api/v1/metrics	Prometheus metrics
AI Services	GET /health	{"status": "ok"}
Typesense	GET /health	{"ok": true}
Loki	GET /ready	200 OK
Redis	redis-cli ping	PONG
PostgreSQL	pg_isready -h host -p 5432	Exit code 0

Scaling Considerations

Horizontal Scaling

• API: Stateless — scale with multiple instances behind a load balancer
• Web: Stateless — scale with multiple instances or deploy to Vercel/Cloudflare
• AI Services: CPU-bound — scale based on valuation request volume
• Redis: Use Redis Cluster for high availability
• PostgreSQL: Read replicas for query-heavy workloads

Recommended Architecture (Production)

                    ┌─────────────┐
                    │ Load Balancer│
                    │ (nginx/ALB)  │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
        ┌─────▼──┐  ┌─────▼──┐  ┌─────▼──┐
        │ API #1 │  │ API #2 │  │ API #N │
        └────────┘  └────────┘  └────────┘
              │            │            │
              └────────────┼────────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
        ┌─────▼──┐  ┌─────▼──┐  ┌─────▼─────┐
        │  PG    │  │ Redis  │  │ Typesense  │
        │Primary │  │Cluster │  │  Cluster   │
        │+ Replica│  │        │  │            │
        └────────┘  └────────┘  └────────────┘

Rollback

Application Rollback

Deploy the previous container image or build artifact. The API and Web are stateless — no rollback-specific steps needed.

Database Rollback

Prisma does not support automatic down migrations. If a migration must be reverted:

1. Identify the migration in prisma/migrations/
2. Write a manual SQL rollback script
3. Apply via psql or a migration tool
4. Update _prisma_migrations table

Always test migrations against a staging database before production deployment.