Skip to main content

Deployment Process

This page contains legacy ECS, Kubernetes, and Terraform examples and is not the current Learnille production procedure. Production server deployment is handled through Dokploy; use the production deployment guide as the operational source of truth.

Overview​

This document outlines the deployment process for the Learnille platform, ensuring consistent, reliable, and secure software delivery across all environments.

Deployment Environments​

Development Environment​

  • Purpose: Daily development and testing
  • Trigger: Push to develop branch
  • Frequency: Multiple times per day
  • Approval: Automatic
  • Rollback: Automatic on failure

Staging Environment​

  • Purpose: Pre-production validation
  • Trigger: Merge to main branch
  • Frequency: Daily
  • Approval: Automatic after tests pass
  • Rollback: Manual or automatic

Production Environment​

  • Purpose: Live user-facing application
  • Trigger: Release tag or manual trigger
  • Frequency: 1-2 times per week
  • Approval: Manual approval required
  • Rollback: Manual with approval

Deployment Workflow​

1. Pre-Deployment Checklist​

Code Quality​

  • All tests passing (unit, integration, e2e)
  • Code coverage > 80%
  • No critical security vulnerabilities
  • Code review completed and approved
  • Linting and formatting checks passed

Documentation​

  • Release notes updated
  • API documentation updated
  • Database migration scripts documented
  • Deployment runbook updated

Infrastructure​

  • Infrastructure as Code changes reviewed
  • Environment variables configured
  • Database migrations tested
  • Monitoring and alerting configured

2. Deployment Preparation​

Branch Management​

# Create release branch
git checkout -b release/v1.2.3 main

# Update version numbers
echo "1.2.3" > VERSION
npm version 1.2.3 --no-git-tag-version

# Commit version changes
git add VERSION package.json
git commit -m "chore: bump version to 1.2.3"

Build Artifacts​

# Build application
npm run build

# Create Docker image
docker build -t learnille/api:1.2.3 .

# Push to registry
docker push learnille/api:1.2.3

Database Migrations​

# Test migrations on staging
npm run migration:run -- --env staging

# Backup production database
pg_dump learnille_prod > backup_$(date +%Y%m%d_%H%M%S).sql

# Validate migration scripts
npm run migration:validate

3. Staging Deployment​

Automated Deployment​

# .github/workflows/staging.yml
name: Deploy to Staging
on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Deploy to ECS
        run: |
          aws ecs update-service \
            --cluster learnille-staging \
            --service learnille-api \
            --force-new-deployment \
            --task-definition learnille-api:1.2.3

Validation Steps​

  1. Health Checks

    # Check application health
    curl -f https://api-staging.learnille.com/health

    # Verify database connection
    curl -f https://api-staging.learnille.com/health/database

  2. Smoke Tests

    # Run critical user journey tests
    npm run test:smoke -- --env staging

  3. Performance Validation

    # Load testing
    k6 run --env staging load-test.js

4. Production Deployment​

Pre-Production Validation​

  • Staging deployment successful
  • All smoke tests passing
  • Performance benchmarks met
  • Security scan clean
  • Manual QA sign-off

Deployment Execution​

# .github/workflows/production.yml
name: Deploy to Production
on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to deploy'
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v3
      - name: Deploy to ECS
        run: |
          aws ecs update-service \
            --cluster learnille-prod \
            --service learnille-api \
            --task-definition learnille-api:${{ github.event.inputs.version }}

Blue-Green Deployment Process​

  1. Deploy to Green Environment

    # Deploy new version to green
    kubectl set image deployment/learnille-api app=learnille/api:1.2.3
    kubectl rollout status deployment/learnille-api

  2. Health Validation

    # Wait for pods to be ready
    kubectl wait --for=condition=ready pod -l app=learnille-api

    # Run health checks
    curl -f https://api-green.learnille.com/health

  3. Traffic Switch

    # Switch traffic to green
    kubectl patch service learnille-api -p '{"spec":{"selector":{"version":"green"}}}'

  4. Monitor and Validate

    # Monitor error rates and latency
    watch -n 30 'curl -s https://api.learnille.com/metrics'

5. Post-Deployment Validation​

Automated Validation​

# Health checks
curl -f https://api.learnille.com/health

# API endpoint validation
curl -f https://api.learnille.com/api/v1/courses?limit=1

# Database connectivity
curl -f https://api.learnille.com/health/database

Manual Validation​

  • User login functionality
  • Course creation and enrollment
  • Payment processing
  • Email notifications
  • Admin dashboard access

Performance Monitoring​

  • Response times within acceptable range
  • Error rates below threshold
  • Resource utilization normal
  • Database query performance

6. Deployment Completion​

Success Criteria​

  • All health checks passing
  • No critical errors in logs
  • Performance metrics within normal range
  • User feedback positive
  • Team notification sent

Documentation Updates​

# Update deployment log
echo "$(date): Successfully deployed v1.2.3 to production" >> deployment-log.txt

# Tag release
git tag -a v1.2.3 -m "Release version 1.2.3"
git push origin v1.2.3

Rollback Procedures​

Automated Rollback​

  • Trigger: Health check failures, error rate spikes
  • Process: Automatic switch back to previous version
  • Time: < 5 minutes

Manual Rollback​

  1. Assessment

    • Identify rollback trigger
    • Assess impact on users
    • Determine rollback scope

  2. Execution

    # Switch back to blue environment
    kubectl patch service learnille-api -p '{"spec":{"selector":{"version":"blue"}}}'

    # Verify rollback
    curl -f https://api.learnille.com/health

  3. Investigation

    • Analyze deployment logs
    • Identify root cause
    • Document lessons learned

Deployment Tools​

Infrastructure as Code​

# infrastructure/main.tf
resource "aws_ecs_service" "learnille_api" {
  name            = "learnille-api"
  cluster         = aws_ecs_cluster.main.id
  task_definition = aws_ecs_task_definition.learnille_api.arn
  desired_count   = 3

  load_balancer {
    target_group_arn = aws_lb_target_group.api.arn
    container_name   = "learnille-api"
    container_port   = 3000
  }
}

Configuration Management​

# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: learnille-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: learnille-api
  template:
    metadata:
      labels:
        app: learnille-api
    spec:
      containers:
      - name: learnille-api
        image: learnille/api:1.2.3
        ports:
        - containerPort: 3000
        env:
        - name: NODE_ENV
          value: "production"
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: learnille-secrets
              key: database-url

Monitoring and Alerting​

Deployment Metrics​

  • Deployment duration
  • Success/failure rate
  • Rollback frequency
  • Time to detect issues

Application Metrics​

  • Response time percentiles
  • Error rate by endpoint
  • Database query performance
  • Resource utilization

Alerting Rules​

# alerting rules
groups:
  - name: deployment
    rules:
      - alert: DeploymentFailed
        expr: deployment_status{status="failed"} > 0
        for: 5m
        labels:
          severity: critical
      - alert: HighErrorRate
        expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.05
        for: 5m
        labels:
          severity: warning

Security Considerations​

Deployment Security​

  • Image Scanning: Vulnerability scanning before deployment
  • Secret Management: Secure handling of credentials
  • Access Control: Least privilege for deployment accounts
  • Audit Logging: Complete audit trail of deployments

Runtime Security​

  • Network Security: VPC isolation and security groups
  • Container Security: Non-root user, minimal base images
  • API Security: Rate limiting and input validation
  • Data Security: Encryption at rest and in transit

Continuous Improvement​

Deployment Metrics Tracking​

  • Mean time between deployments
  • Mean time to recovery
  • Deployment success rate
  • Customer impact of deployments

Process Optimization​

  • Regular deployment retrospective meetings
  • Automation of manual steps
  • Tool and process improvements
  • Team training and knowledge sharing

Emergency Procedures​

Critical Incident Response​

  1. Assessment: Evaluate incident severity and impact
  2. Communication: Notify stakeholders and team
  3. Containment: Isolate affected systems
  4. Recovery: Execute rollback or fix
  5. Analysis: Post-mortem and improvement actions

Contact Information​