pos-system/docs/en/guides/deployment.md

Deployment Guide

Deployment strategies for GoodGo Microservices Platform across Local, Staging, and Production environments using Kubernetes and Neon PostgreSQL

Table of Contents

1. Deployment Architecture
2. Prerequisites
3. Database Setup (Neon)
4. Local Deployment
5. CI/CD Pipeline
6. Staging Deployment
7. Production Deployment
8. Scaling & Resilience
9. Rollback Procedures

---

Deployment Architecture

graph TD
 subgraph "CI/CD Pipeline - GitHub Actions"
 Code[Code Push] --> Test[Run Tests]
 Test --> Build[Build Docker Image]
 Build --> Registry[Push to Registry]
 Registry --> Deploy[Deploy to K8s]
 end

 subgraph "Infrastructure - Kubernetes"
 Ingress[Traefik Ingress] --> Service[K8s Service]
 Service --> Pods[Application Pods]
 Pods --> Secrets[K8s Secrets]
 end

 subgraph "External Services"
 Pods --> Neon[(Neon PostgreSQL)]
 Pods --> Redis[(Redis Cloud)]
 end

 Deploy --> Ingress

 style Code fill:#1e3a5f,color:#e0e7ff
 style Test fill:#065f46,color:#d1fae5
 style Build fill:#1e40af,color:#dbeafe
 style Registry fill:#581c87,color:#f3e8ff
 style Deploy fill:#9a3412,color:#fed7aa
 style Ingress fill:#312e81,color:#e0e7ff
 style Service fill:#1e40af,color:#dbeafe
 style Pods fill:#14532d,color:#d1fae5
 style Secrets fill:#78350f,color:#fef3c7
 style Neon fill:#4c1d95,color:#f3e8ff
 style Redis fill:#854d0e,color:#fef3c7

---

Prerequisites

Before deploying, ensure you have:

• Tools: kubectl, helm, docker installed.
• Access:
• Kubernetes Cluster (EKS/GKE/DigitalOcean).
• Container Registry (GHCR/DockerHub).
• Neon Console Account.
• Configuration:
• KUBECONFIG file set up.
• GitHub Secrets configured for CI/CD.

---

Database Setup (Neon)

We use Neon Serverless PostgreSQL for all environments to leverage branching and auto-scaling.

1. Create Project: Log in to neon.tech and create a project goodgo-platform.
2. Create Branches:

• main -> For Development/Local.
• staging -> For Staging environment.
• production -> For Production environment (Protected).

3. Get Connection Strings:

• Note the connection string for each branch (Pooler mode recommended).

---

Local Deployment

For local development, we use Docker Compose.

# 1. Setup Environment
cp deployments/local/env.local.example deployments/local/.env.local
# Edit .env.local with Neon `main` branch connection string

# 2. Start Infrastructure (Redis, Traefik, etc.)
cd deployments/local
docker-compose up -d

# 3. Start Services (Hot-reload)
pnpm dev

---

CI/CD Pipeline

We use GitHub Actions for automated deployments.

Workflow	Trigger	Description
ci-check.yml	Pull Request	Runs unit tests, linting, and build check.
deploy-staging.yml	Push to develop	Build image -> Deploy to Staging Namespace.
deploy-prod.yml	Release / Tag	Build image -> Deploy to Production Namespace.

Secrets Configuration (GitHub)

Set these secrets in your repository settings:

• NEON_DATABASE_URL_STAGING: Connection string for staging branch.
• NEON_DATABASE_URL_PRODUCTION: Connection string for production branch.
• KUBECONFIG_STAGING: Base64 encoded kubeconfig for staging.
• KUBECONFIG_PRODUCTION: Base64 encoded kubeconfig for production.
• DOCKER_REGISTRY_TOKEN: For pushing images.

---

Staging Deployment

Staging mirrors production but uses cost-effective resources.

Manual Deployment

# 1. Create Secrets
kubectl create secret generic iam-service-secrets \
 --from-literal=database-url='<STAGING_NEON_URL>' \
 --from-literal=jwt-secret='<RANDOM_SECRET>' \
 -n staging

# 2. Apply Manifests
kubectl apply -f deployments/staging/kubernetes/ -n staging

# 3. Verify
kubectl get pods -n staging

via CI/CD

Push code to develop branch. The action will:

1. Run tests.
2. Run prisma migrate deploy against Staging DB.
3. Update Kubernetes deployment image.

---

Production Deployment

Production uses high-availability configurations.

1. Database Preparation

• Ensure Production branch in Neon is protected.
• Configure Point-in-Time Recovery (PITR) window (e.g., 7 days).

2. Manual Deployment Steps

# 1. Create Namespace
kubectl create namespace production

# 2. Create Sealed Secrets (Recommended) or Standard Secrets
kubectl create secret generic iam-service-secrets \
 --from-literal=database-url='<PROD_NEON_URL>' \
 --from-literal=jwt-secret='<SECURE_RANDOM_SECRET>' \
 --from-literal=jwt-refresh-secret='<SECURE_RANDOM_SECRET>' \
 -n production

# 3. Deploy
kubectl apply -f deployments/production/kubernetes/ -n production

3. Verification

# Check Rollout Status
kubectl rollout status deployment/iam-service -n production

# Check Logs
kubectl logs -l app=iam-service -n production

---

Scaling & Resilience

Horizontal Pod Autoscaler (HPA)

We use HPA to automatically scale pods based on CPU/Memory.

# Example HPA Config
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
 name: iam-service-hpa
spec:
 minReplicas: 2
 maxReplicas: 10
 metrics:
 - type: Resource
 resource:
 name: cpu
 target:
 type: Utilization
 averageUtilization: 70

Zero-Downtime Deployment

Kubernetes handles this via Rolling Updates.

• MaxSurge: 25% (Add new pods before removing old ones).
• MaxUnavailable: 0 (Ensure no downtime during update).

---

Rollback Procedures

If a deployment fails or introduces a critical bug:

Kubernetes Rollback

# Undo last deployment
kubectl rollout undo deployment/iam-service -n production

# Undo to specific revision
kubectl rollout undo deployment/iam-service -n production --to-revision=2

Database Rollback

Since Neon supports branching and PITR:

1. Go to Neon Console.
2. Restore the production branch to a timestamp before the bad migration.
3. Warning: This may result in data loss for new transactions. Use with caution.