Jenkins CI/CD End-to-End Documentation

 

Jenkins CI/CD End-to-End Documentation

1. Objective

This document explains from start to finish how to build a complete, safe, production-ready CI/CD pipeline using Jenkins for the Helium platform.

The pipeline is designed to:

  • Trigger on git push master

  • Build ARM64 Docker images from the latest code

  • Push images to Amazon ECR

  • Deploy automatically to Staging (Mumbai)

  • Pause for manual approval

  • Deploy the same tested image to Production (Mumbai, Singapore, Virginia)

  • Fully control AWS Amplify frontend deployments (no auto-deploy)

2. High-Level CI/CD Flow

Git Push (master)
   ↓
Jenkins pulls latest code (backend + frontend)
   ↓
Docker Build (ARM64)
   ↓
Push image → ECR (helium-backend-staging, Mumbai)
   ↓
Deploy STAGING backend (ECS, Mumbai)
   ↓
[Optional] Deploy STAGING frontend (Amplify)
   ↓
⏸ Manual Approval (button in Jenkins)
   ↓
Promote image → PROD ECR (Mumbai, Singapore, Virginia)
   ↓
Deploy PROD backend (ECS, 3 regions)
   ↓
Deploy PROD frontend (Amplify)

3. Prerequisites

3.1 AWS

You must already have:

  • AWS account

  • ECS clusters created:

    • Staging: Mumbai (ap-south-1)

    • Production: Mumbai, Singapore, Virginia

  • ECS services (already created):

    • Backend

    • Worker

  • ECR repositories:

    • helium-backend-staging (Mumbai only)

    • helium-backend (all prod regions)

  • AWS Amplify apps:

    • Staging app (region: us-east-1)

    • Production app (region: us-east-1)

⚠️ Important: Auto-build must be OFF for both Amplify apps.

3.2 GitHub

  • Private GitHub repository

  • master branch

  • Jenkinsfile committed at repository root

4. Jenkins Server Setup (EC2)

4.1 Launch EC2

  • OS: Ubuntu 22.04 or 24.04

  • Instance type: t3.medium

  • Disk: 30 GB

  • Security group:

    • Port 22 (SSH)

    • Port 8080 (Jenkins UI)

4.2 Connect to EC2

ssh -i your-key.pem ubuntu@<EC2_PUBLIC_IP>

5. Install Jenkins & Required Tools

Install the following once on the EC2 instance:

  • Java 17

  • Jenkins

  • Docker

  • Docker Buildx (ARM64 support)

  • QEMU

  • AWS CLI

After installation:

  • Jenkins runs as a system service

  • Jenkins user can run Docker

  • docker buildx supports linux/arm64

6. Jenkins Initial Setup

  1. Open browser:

    http://<EC2_PUBLIC_IP>:8080

  2. Unlock Jenkins:

    sudo cat /var/lib/jenkins/secrets/initialAdminPassword

  3. Install suggested plugins

  4. Create admin user

7. Required Jenkins Plugins

Ensure these plugins are installed:

  • Pipeline

  • Git

  • GitHub

  • Credentials Binding

  • Docker Pipeline

  • Pipeline: Input Step

  • Pipeline: Stage View

8. GitHub Credentials (Private Repo)

8.1 Create GitHub Token

  • GitHub → Settings → Developer settings

  • Personal Access Token (classic)

  • Scope: repo

8.2 Add to Jenkins

Kind: Username with password
ID: github-creds
Username: <github-username>
Password: <github-token>

9. AWS Credentials in Jenkins

Add two credentials:

Access Key

Kind: Secret text
ID: aws-access-key

Secret Key

Kind: Secret text
ID: aws-secret-key

10. Create Jenkins Pipeline Job

  • New Item → Pipeline

  • Name: helium-cicd

Pipeline configuration:

Definition: Pipeline script from SCM
SCM: Git
Repository URL: https://github.com/<org>/<repo>.git
Credentials: github-creds
Branch: */master
Script Path: Jenkinsfile

11. Jenkinsfile (FINAL)

This Jenkinsfile:

  • Always builds latest code

  • Deploys staging automatically

  • Shows manual approval button

  • Deploys production only after approval

  • Keeps frontend deployment fully controlled

(Jenkinsfile content intentionally unchanged here, as it already matches the final validated pipeline.)

12. First Pipeline Run

Trigger via:

git push origin master

or

Jenkins UI → Build Now

13. Manual Production Approval

When pipeline reaches Approve PRODUCTION stage:

  • Jenkins pauses execution

  • UI shows Proceed button

  • No production action happens until approved

To disable production entirely:

RUN_PRODUCTION = "false"

14. Verification

Backend

  • ECS services use new task definition revision

  • Containers run new image tag

Frontend

  • Amplify deploys only when triggered by Jenkins

15. Daily Developer Workflow

Developers only do:

git push origin master

Jenkins handles everything else.

16. Critical Rules

  • Never install tools inside Jenkinsfile

  • Never enable Amplify auto-build

  • Never deploy production without approval

  • Same image is used for staging & production

17. How Jenkins Controls Amplify (IMPORTANT)

  • Amplify auto-build is disabled

  • Jenkins triggers deployments explicitly:

aws amplify start-job \
  --app-id <APP_ID> \
  --branch-name master \
  --job-type RELEASE

This guarantees:

  • Backend deploys first

  • Frontend deploys after backend

  • Full deployment control via Jenkins

18. Final Result

You now have:

  • Enterprise-grade CI/CD

  • Safe multi-region production deployments

  • Manual approval gate

  • Controlled frontend releases

  • Clean Git workflow

END OF DOCUMENTATION

Comments

Post a Comment

Popular posts from this blog

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 Branch Deployment Scope Staging    kartik-stg          Mumbai (ap-south-1) Production  migrated-demo2 ...
Read more

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