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

Deployment Guide

Database Setup (Neon)

All environments use Neon PostgreSQL. Setup once before deployment:

1. Create Neon project at https://neon.tech
2. Create branches: main (dev), staging, production
3. Get connection strings for each branch
4. Configure in environment variables (see below)

See Neon Setup Guide for details.

Local Deployment

# Setup Neon database URL
cp deployments/local/env.local.example deployments/local/.env.local
# Edit .env.local and add your Neon DATABASE_URL

# Start services (no PostgreSQL container needed)
cd deployments/local
docker-compose up -d

Staging Deployment

Prerequisites

• Kubernetes cluster access
• kubectl configured
• KUBECONFIG set
• Neon staging branch created
• GitHub Secrets configured:
  • NEON_DATABASE_URL_STAGING
  • KUBECONFIG_STAGING

Setup Secrets

# Create Kubernetes secret
kubectl create secret generic auth-service-secrets \
  --from-literal=database-url='postgresql://user:pass@ep-xxx.region.neon.tech/dbname?sslmode=require&pgbouncer=true' \
  --from-literal=jwt-secret='your-staging-jwt-secret' \
  --from-literal=jwt-refresh-secret='your-staging-refresh-secret' \
  -n staging

Deploy

./scripts/deploy/deploy-staging.sh

Or manually:

kubectl apply -f deployments/staging/kubernetes/

Note: Migrations run automatically in CI/CD before deployment.

Production Deployment

Prerequisites

• Production Kubernetes cluster
• kubectl configured with production context
• Neon production branch created
• GitHub Secrets configured:
  • NEON_DATABASE_URL_PRODUCTION
  • KUBECONFIG_PRODUCTION

Setup Secrets

# Create Kubernetes secret
kubectl create secret generic auth-service-secrets \
  --from-literal=database-url='postgresql://user:pass@ep-xxx.region.neon.tech/dbname?sslmode=require&pgbouncer=true' \
  --from-literal=jwt-secret='your-production-jwt-secret' \
  --from-literal=jwt-refresh-secret='your-production-refresh-secret' \
  -n production

Deploy

./scripts/deploy/deploy-prod.sh

Note: Migrations run automatically in CI/CD before deployment (with approval).

Rollback

kubectl rollout undo deployment/auth-service -n production

Health Checks

• Liveness: GET /health/live
• Readiness: GET /health/ready
• Health: GET /health

Monitoring

• Prometheus: http://prometheus:9090
• Grafana: http://grafana:3000
• Traefik Dashboard: http://traefik:8080