Skip to content

DEPLOYMENT_GUIDE.md

Latest commit

 

History

History
710 lines (500 loc) · 12.9 KB

DEPLOYMENT_GUIDE.md

File metadata and controls

710 lines (500 loc) · 12.9 KB

Nimaora - Deployment Guide

Complete Guide to Deploying the Nimaora Platform

From development to production at scale

Table of Contents

Overview

Nimaora CodeBattle supports multiple deployment strategies:

Strategy Use Case Complexity Scale
Docker Compose Development, Small teams Low 1-1,000 users
Kubernetes Production, Enterprise Medium 1,000-100,000+ users
ArvanCloud Iran-based deployment Medium 1,000-50,000 users
AWS Global deployment Medium 1,000-1,000,000+ users

Prerequisites

Common Requirements

  • Git
  • Docker 24.0+
  • Docker Compose v2.20+

For Kubernetes Deployment

  • kubectl configured
  • Kubernetes cluster 1.28+
  • Helm 3.12+
  • Storage class available

For Terraform Deployment

  • Terraform 1.5+
  • Cloud provider credentials

For Ansible Deployment

  • Ansible 2.15+
  • SSH access to target servers

Environment Configuration

Generate Secure Secrets

# Generate APP_KEY
php artisan key:generate --show
# or
openssl rand -base64 32

# Generate database password
openssl rand -base64 24

# Generate Redis password
openssl rand -base64 24

# Generate RabbitMQ password
openssl rand -base64 24

# Generate Reverb secrets
openssl rand -hex 32  # REVERB_APP_KEY
openssl rand -hex 32  # REVERB_APP_SECRET

Environment Variables

Create .env file in project root:

# Application
APP_NAME=Nimaora
APP_ENV=production
APP_DEBUG=false
APP_URL=https://nimaora.dwin.codes
APP_KEY=base64:YOUR_GENERATED_KEY

# Database
DB_CONNECTION=pgsql
DB_HOST=postgres-primary
DB_PORT=5432
DB_DATABASE=nimaora
DB_USERNAME=nimaora
DB_PASSWORD=YOUR_SECURE_PASSWORD

# Redis
REDIS_HOST=redis-master
REDIS_PORT=6379
REDIS_PASSWORD=YOUR_REDIS_PASSWORD

# RabbitMQ
RABBITMQ_HOST=rabbitmq
RABBITMQ_PORT=5672
RABBITMQ_USER=nimaora
RABBITMQ_PASSWORD=YOUR_RABBITMQ_PASSWORD
RABBITMQ_VHOST=/nimaora

# WebSocket (Reverb)
BROADCAST_CONNECTION=reverb
REVERB_APP_ID=nimaora
REVERB_APP_KEY=YOUR_REVERB_APP_KEY
REVERB_APP_SECRET=YOUR_REVERB_APP_SECRET
REVERB_HOST=0.0.0.0
REVERB_PORT=8080

# Frontend URLs
NEXT_PUBLIC_API_URL=https://api.nimaora.dwin.codes
NEXT_PUBLIC_REVERB_HOST=ws.nimaora.dwin.codes
NEXT_PUBLIC_REVERB_PORT=443
NEXT_PUBLIC_REVERB_SCHEME=https

# Monitoring
GRAFANA_ADMIN_PASSWORD=YOUR_GRAFANA_PASSWORD

# SSL
ACME_EMAIL=admin@dwin.codes

Docker Compose Deployment

Development Environment

# Clone repository
git clone https://git.dwin.codes/nimaora/nimaora.git
cd nimaora

# Copy environment file
cp .env.example .env
# Edit .env with your values

# Start all services
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f

# Run migrations
docker compose exec backend php artisan migrate --seed

Production with Docker Compose

# Build optimized images
docker compose build --no-cache

# Start with production settings
docker compose -f docker-compose.yml up -d

# Scale services
docker compose up -d --scale backend=4 --scale websocket=3 --scale horizon=2

# Run migrations
docker compose exec backend php artisan migrate --force

# Optimize Laravel
docker compose exec backend php artisan config:cache
docker compose exec backend php artisan route:cache
docker compose exec backend php artisan view:cache

Service Management

# Restart specific service
docker compose restart backend

# View service logs
docker compose logs -f backend websocket

# Execute command in container
docker compose exec backend php artisan tinker

# Stop all services
docker compose down

# Stop and remove volumes (CAUTION: destroys data)
docker compose down -v

Kubernetes Deployment

Cluster Setup

# Create namespace
kubectl create namespace nimaora

# Apply secrets
kubectl apply -f nimaora-infrastructure/kubernetes/base/secret.yaml -n nimaora

# Apply config maps
kubectl apply -f nimaora-infrastructure/kubernetes/base/configmap.yaml -n nimaora

Deploy Base Infrastructure

cd nimaora-infrastructure/kubernetes

# Apply base configuration
kubectl apply -k base/

# Wait for pods to be ready
kubectl -n nimaora wait --for=condition=ready pod --all --timeout=300s

# Check deployment status
kubectl -n nimaora get pods
kubectl -n nimaora get services
kubectl -n nimaora get ingress

Deploy with Environment Overlays

# Development
kubectl apply -k overlays/development/

# Staging
kubectl apply -k overlays/staging/

# Production
kubectl apply -k overlays/production/

Verify Deployment

# Check all resources
kubectl -n nimaora get all

# Check HPA status
kubectl -n nimaora get hpa

# Check pod logs
kubectl -n nimaora logs -f deployment/backend

# Check events
kubectl -n nimaora get events --sort-by='.lastTimestamp'

Scaling Commands

# Manual scale (if needed)
kubectl -n nimaora scale deployment backend --replicas=10
kubectl -n nimaora scale deployment websocket --replicas=5

# Check HPA status
kubectl -n nimaora get hpa

# View pod distribution
kubectl -n nimaora get pods -o wide

Database Migration in Kubernetes

# Run migrations
kubectl -n nimaora exec -it deployment/backend -- php artisan migrate --force

# Run seeders
kubectl -n nimaora exec -it deployment/backend -- php artisan db:seed

# Clear caches
kubectl -n nimaora exec -it deployment/backend -- php artisan cache:clear

ArvanCloud Deployment

Prerequisites

  1. ArvanCloud account with API key
  2. Domain configured in ArvanCloud DNS
  3. SSH key pair for server access

Terraform Setup

cd nimaora-infrastructure/terraform/arvancloud

# Copy variables file
cp terraform.tfvars.example terraform.tfvars

# Edit terraform.tfvars
vim terraform.tfvars

terraform.tfvars Configuration

arvan_api_key     = "your-api-key"
arvan_region      = "ir-thr-c2"
project_name      = "nimaora"
environment       = "production"
domain_name       = "nimaora.dwin.codes"

# Instance configuration
db_flavor         = "g1-8-16-0"    # 8 vCPU, 16GB RAM
app_flavor        = "g1-4-8-0"     # 4 vCPU, 8GB RAM
app_instance_count = 3

# Storage
db_volume_size    = 100
app_volume_size   = 50

# Scaling
enable_autoscaling = true
min_app_instances  = 3
max_app_instances  = 20
enable_cdn         = true

Deploy Infrastructure

# Initialize Terraform
terraform init

# Preview changes
terraform plan

# Apply changes
terraform apply

# Save outputs
terraform output > outputs.txt

Configure Servers with Ansible

cd nimaora-infrastructure/ansible

# Update inventory with Terraform outputs
vim inventories/production/hosts.ini

# Test connectivity
ansible -i inventories/production/hosts.ini all -m ping

# Run full setup
ansible-playbook -i inventories/production/hosts.ini playbooks/site.yml

# Deploy application only
ansible-playbook -i inventories/production/hosts.ini playbooks/deploy.yml

One-Command Deployment

# From project root
./deploy.sh production full

AWS Deployment

Prerequisites

  1. AWS account with appropriate IAM permissions
  2. AWS CLI configured
  3. Domain in Route53 (optional)

Terraform Setup

cd nimaora-infrastructure/terraform/aws

# Copy variables file
cp terraform.tfvars.example terraform.tfvars

# Edit terraform.tfvars
vim terraform.tfvars

terraform.tfvars Configuration

aws_region     = "eu-west-1"
project_name   = "nimaora"
environment    = "production"

# VPC
vpc_cidr       = "10.0.0.0/16"

# EC2 Instances
instance_type  = "c5.xlarge"
instance_count = 3

# RDS
db_instance_class = "db.r5.large"
db_storage_size   = 100

# ElastiCache
redis_node_type   = "cache.r5.large"
redis_num_nodes   = 3

Deploy Infrastructure

# Initialize
terraform init

# Plan
terraform plan -out=tfplan

# Apply
terraform apply tfplan

# Get outputs
terraform output

Post-Terraform Setup

# Update kubeconfig (if using EKS)
aws eks update-kubeconfig --name nimaora-cluster --region eu-west-1

# Deploy to Kubernetes
kubectl apply -k nimaora-infrastructure/kubernetes/overlays/production/

Database Setup

Initial Migration

# Docker Compose
docker compose exec backend php artisan migrate --seed

# Kubernetes
kubectl -n nimaora exec -it deployment/backend -- php artisan migrate --seed

Seeder Details

The seeder creates:

  • 2 active battles
  • 30 questions (10 easy, 10 medium, 10 hard)
# Run specific seeder
php artisan db:seed --class=BattleSeeder

Backup and Restore

# Backup
docker compose exec postgres-primary pg_dump -U nimaora nimaora > backup.sql

# Restore
docker compose exec -T postgres-primary psql -U nimaora nimaora < backup.sql

SSL/TLS Configuration

Let's Encrypt (Automatic)

Traefik automatically obtains certificates:

# docker-compose.yml
traefik:
  command:
    - "--certificatesresolvers.letsencrypt.acme.email=${ACME_EMAIL}"
    - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
    - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"

Kubernetes with cert-manager

# Install cert-manager
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml

# Create ClusterIssuer
kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: ${ACME_EMAIL}
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - http01:
        ingress:
          class: traefik
EOF

Post-Deployment

Health Checks

# API health
curl https://api.nimaora.dwin.codes/api/health

# Frontend health
curl https://nimaora.dwin.codes

# WebSocket health
curl https://ws.nimaora.dwin.codes

Monitoring Setup

# Access Grafana
kubectl -n nimaora port-forward svc/grafana 3000:3000
# Open http://localhost:3000

# Access Prometheus
kubectl -n nimaora port-forward svc/prometheus 9090:9090

# Access RabbitMQ Management
kubectl -n nimaora port-forward svc/rabbitmq 15672:15672

Performance Optimization

# Laravel optimizations
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan event:cache

# Clear all caches
php artisan optimize:clear

Troubleshooting

Common Issues

Services Not Starting

# Check logs
docker compose logs [service-name]

# Check resource usage
docker stats

# Restart service
docker compose restart [service-name]

Database Connection Issues

# Test connection
docker compose exec backend php artisan db:show

# Check PostgreSQL status
docker compose logs postgres-primary

# Check PgBouncer
docker compose logs pgbouncer

WebSocket Issues

# Check Reverb logs
docker compose logs websocket

# Test WebSocket connection
wscat -c ws://localhost:8080/app/nimaora-app-key

# Check Redis pub/sub
docker compose exec redis-master redis-cli PUBSUB CHANNELS "*"

Queue Issues

# Check Horizon status
docker compose logs horizon

# Check RabbitMQ
docker compose exec rabbitmq rabbitmqctl list_queues

# Purge stuck queue
docker compose exec rabbitmq rabbitmqctl purge_queue nimaora.default

Debug Mode

# Enable debug temporarily
docker compose exec backend php artisan config:clear
# Set APP_DEBUG=true in .env
docker compose restart backend

# View detailed errors
docker compose logs -f backend

Performance Issues

# Check slow queries
docker compose exec backend php artisan pulse:check

# Monitor queue throughput
docker compose exec backend php artisan horizon:status

# Check Redis memory
docker compose exec redis-master redis-cli INFO memory

Rollback Procedures

Docker Compose Rollback

# Stop current deployment
docker compose down

# Checkout previous version
git checkout v1.0.0

# Rebuild and start
docker compose up -d --build

Kubernetes Rollback

# View rollout history
kubectl -n nimaora rollout history deployment/backend

# Rollback to previous version
kubectl -n nimaora rollout undo deployment/backend

# Rollback to specific revision
kubectl -n nimaora rollout undo deployment/backend --to-revision=2

Ansible Rollback

cd nimaora-infrastructure/ansible
ansible-playbook -i inventories/production/hosts.ini playbooks/rollback.yml

Deployment Complete | Monitor Your Metrics | Scale as Needed