Staging Deployment & CI/CD Pipeline Documentation

Staging Deployment & CI/CD Pipeline Documentation

1. Overview

This document provides a clear, end-to-end description of the staging deployment setup and the unified CI/CD pipeline implemented for the HeliumAI platform. A single pipeline is used to manage deployments for both staging and production, with strict controls enforced through branch-based execution.

The staging environment is currently deployed and validated in the ap-south-1 (Mumbai) region.

2. Architecture Summary

  • 🌐 Frontend Domain: https://www.heliumai.space

  • 🔌 Backend API Domain: https://api.heliumai.space

  • 🧮 Compute Platform: AWS ECS (Fargate)

  • 📦 Container Registry: Amazon ECR

  • ⚖️ Load Balancer: Application Load Balancer (ALB)

  • 🚀 Traffic Acceleration: AWS Global Accelerator

  • 🔁 CI/CD Platform: GitHub Actions

3. Environments & Branch Mapping

Environment Git BranchDeployment Scope
Staging   kartik-stg         Mumbai (ap-south-1)
Production migrated-demo2      Mumbai, Singapore, Virginia

Branch-based mapping ensures strong isolation between environments and prevents accidental cross-environment deployments.

4. CI/CD Pipeline Overview

A single GitHub Actions pipeline is responsible for:

  • 🏗️ Building Docker images

  • 📤 Pushing images to Amazon ECR

  • 🚢 Deploying services to Amazon ECS

Pipeline execution is strictly gated by Git branch, enabling controlled promotion from staging to production without maintaining multiple workflows.

5. Pipeline Trigger Strategy

Trigger Conditions

  • 🔔 Automatic trigger on git push to environment-specific branches

This approach keeps the pipeline simple while ensuring deployments only occur from explicitly approved branches.

6. Global Pipeline Configuration

Image Tagging Strategy

  • 🏷️ Docker images are tagged using: v${github.run_number}

  • 🔍 Guarantees unique, incremental, and traceable image versions

Image Repository Strategy

  • 📦 Single Amazon ECR repository: helium-backend

  • ♻️ The same image artifact is reused across environments, eliminating unnecessary rebuilds

7. Build Stage – Docker Image Creation

Purpose

  • 🧱 Build ARM64-compatible Docker images

  • 📤 Push images to Amazon ECR

Build Flow

  1. 📥 Checkout application source code

  2. 🛠️ Initialize Docker Buildx

  3. 🔐 Authenticate with AWS

  4. 🏗️ Build ARM64 Docker image

  5. 🏷️ Tag image with pipeline run number

  6. 📦 Push image to ECR

  7. 📤 Export image URI for downstream deployment stages

8. Staging Deployment – End-to-End Flow (Mumbai)

This section documents the complete staging deployment lifecycle, from infrastructure readiness to application validation.

8.1 Preconditions

  • 🌿 Git branch: kartik-stg

  • 🧩 ECS cluster: helium-mumbai-staging-cluster

  • 📦 ECR repository available in ap-south-1

  • ⚖️ ALB and target groups configured for staging services

8.2 Deployment Trigger

  • 🚀 Deployment is automatically initiated on:

    • git push to the kartik-stg branch

8.3 Staging Networking & Access Setup (Pre-Deployment)

  1. 🌍 AWS Global Accelerator configured for staging traffic

  2. 🎯 Accelerator endpoint attached to the staging ALB in ap-south-1

  3. 🌐 Separate staging domain configured: heliumai.space

  4. 🔒 New ACM certificate created for heliumai.space

  5. ✅ Certificate validated using DNS validation

  6. 🧭 CNAME record added in Route 53 pointing the domain to the Global Accelerator DNS name

8.4 Build Phase (CI)

  1. 🔁 GitHub Actions workflow is triggered

  2. 📥 Source code is checked out

  3. 🛠️ Docker Buildx is initialized

  4. 🏗️ ARM64 Docker image is built

  5. 🏷️ Image is tagged using v${github.run_number}

  6. 📦 Image is pushed to Amazon ECR (Mumbai)

  7. 📤 Image URI is exported for deployment

8.5 Deploy Phase (CD)

Execution Condition:

  • 🚨 Runs only when the active branch is kartik-stg

Services Deployed:

  • 🔵 Backend service

  • ⚙️ Worker service

Deployment Steps:

  1. 🔐 Configure AWS credentials for ap-south-1

  2. 📥 Download the current ECS task definition

  3. 🧹 Remove AWS-managed metadata fields

  4. 🖼️ Inject the newly built Docker image

  5. 🧾 Register a new task definition revision

  6. 🔄 Update the ECS service to use the new revision

  7. ⏳ Wait for ECS service stability

8.6 Post-Deployment Validation

  • ✅ Confirm ECS services are stable

  • 📋 Verify new task definition revisions are running

  • 🌐 Validate application access via the staging domain

9. Production Deployment Flow (Multi-Region)

Execution Condition

  • 🚨 Triggered only when code is pushed to the migrated-demo2 branch

Safety Controls

  • 🔐 Strict branch-based gating

  • 🛑 Prevents unintended production deployments

Target Regions & Clusters

RegionECS Cluster
Mumbai    helium-mumbai-cluster
Singapore    helium-singapore-cluster
Virginia    helium-virginia-cluster

Deployment Steps (Per Region)

  1. 🔐 Configure AWS credentials for the target region

  2. 📥 Retrieve existing ECS task definition

  3. 🧹 Remove AWS-managed fields

  4. 🖼️ Inject region-specific Docker image

  5. 🧾 Register a new task definition revision

  6. 🚀 Deploy the updated task definition to ECS

  7. ⏳ Wait for service stability confirmation

10. Security & Secrets Management

  • 🔒 AWS credentials are securely stored in GitHub Secrets

  • 🚫 No credentials or sensitive values are hardcoded

11. Benefits of the Current Setup

  • ✅ Single CI/CD pipeline for all environments

  • 🔐 Strong deployment safety through branch isolation

  • ♻️ Reusable Docker artifacts across environments

  • 🌍 Multi-region production readiness

  • 🧼 Clean, scalable, and maintainable architecture

12. Final Summary

This document captures a well-structured, production-ready CI/CD and staging deployment architecture for HeliumAI. The approach ensures safe staging validation, seamless promotion to production, and consistent deployments using a single, controlled pipeline.

Comments

Post a Comment

Popular posts from this blog

AWS Global Accelerator (GA) & Route 53 Integration Documentation

1. Purpose of This Document This document describes the end-to-end setup of AWS Global Accelerator (GA) integrated with multi-region Application Load Balancers (ALBs) and Amazon Route 53 . It explains the architecture, configuration steps, routing behavior, traffic flow, and best practices from a Cloud Engineer perspective. 2. What is AWS Global Accelerator? AWS Global Accelerator is a global networking service that improves application availability and performance by directing user traffic to the nearest healthy AWS Region using Anycast static IPs . Key Characteristics 🌍 Global service (not region-specific) 📌 Provides two static Anycast IP addresses 🚀 Routes traffic at AWS Edge locations 🌐 Supports multi-region endpoints (ALB, NLB, EC2, Elastic IP) 🔁 Offers near-instant regional failover ℹ️ Important: Global Accelerator is managed from US West (Oregon) . This is only the control plane location and does not mean that application traffic flows through Oregon. 3. Architecture...
Read more

End-To-End-Documentation

End-To-End Documentation  This document provides a consolidated, end-to-end view of the architecture design, infrastructure experiments, and Kubernetes-based deployment for the Helium application. It is structured as a practical engineering reference and runnable runbook. 1. Architecture Review & Design 1.1 Architecture Understanding Reviewed the provided AWS architecture diagram in detail Identified major components, service boundaries, and dependencies Understood data flow between frontend, backend, worker, and data layers Analyzed interactions between AWS-managed services and external integrations 1.2 Architecture Diagram Creation Created an updated AWS architecture diagram Ensured clear separation of: Frontend layer Backend API services Asynchronous worker services Data and caching components Represented VPC boundaries, load balancers, and external service integrations 1.3 AWS Services Studied Amazon VPC and subnet design ECS Fargate for container-based workloads Applicatio...
Read more