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](#deployment-architecture)
2. [Prerequisites](#prerequisites)
3. [Database Setup (Neon)](#database-setup-neon)
4. [Local Deployment](#local-deployment)
5. [CI/CD Pipeline](#cicd-pipeline)
6. [Staging Deployment](#staging-deployment)
7. [Production Deployment](#production-deployment)
8. [Scaling & Resilience](#scaling--resilience)
9. [Rollback Procedures](#rollback-procedures)

---

## Deployment Architecture

```mermaid
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](https://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.

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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.

```yaml
# 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

```bash
# 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.