Build a Jenkins CI/CD Pipeline for Spring Boot on AWS

A practical guide using Jenkins, Docker, Amazon ECR, and Amazon ECS

Overview

A CI/CD pipeline automates repeatable steps from source-code change to application deployment. For a Spring Boot service, Jenkins can compile and test the code, build a container image, publish the image to Amazon Elastic Container Registry (Amazon ECR), and deploy the new image to Amazon Elastic Container Service (Amazon ECS).

This guide uses Amazon ECS on AWS Fargate as the deployment target. ECS on EC2 is also possible, but its infrastructure and capacity management differ. Treat the architecture and examples as a reference implementation; validate them in a non-production AWS account before production use.

What the pipeline does

1. A developer pushes a change to the source repository.
2. A webhook or configured SCM polling triggers Jenkins.
3. Jenkins checks out the code and runs Maven tests.
4. Jenkins builds a Docker image and tags it with a unique build identifier.
5. Jenkins authenticates to Amazon ECR using an approved AWS identity and pushes the image.
6. Jenkins updates the ECS task definition to reference the new image.
7. Amazon ECS deploys the new task revision and replaces tasks according to the service's deployment configuration.
8. The pipeline checks deployment status and reports success or failure.

Architecture diagram

The companion file jenkins_spring_boot_aws_cicd_architecture.svg shows the CI/CD flow and runtime architecture.

Components

Component	Responsibility
Git repository (for example, Bitbucket or GitHub)	Source code, Dockerfile, Jenkinsfile, and application configuration templates
Jenkins	Orchestrates checkout, build, tests, image build, push, deployment, and reporting
Maven	Compiles and tests the Spring Boot application
Docker	Packages the application into a container image
Amazon ECR	Stores versioned container images
AWS IAM role or federation	Grants narrowly scoped AWS permissions to the pipeline
Amazon ECS	Runs and manages application tasks
AWS Fargate	Provides serverless compute capacity for ECS tasks
Application Load Balancer (optional)	Routes HTTP/HTTPS traffic to healthy ECS tasks
Amazon CloudWatch	Collects task/application logs and service metrics when configured

Prerequisites

Before implementing the pipeline, prepare:

• A Spring Boot project that builds locally with Maven.
• A Dockerfile that creates a runnable image.
• A Jenkins controller and an appropriately secured build agent with the required Java, Maven, Docker/build tooling, and AWS CLI or SDK capabilities.
• An AWS account and region for ECR and ECS.
• An ECR repository.
• An ECS cluster, task execution role, task role (if the application calls AWS services), and task definition.
• Network connectivity from ECS tasks to required dependencies.
• A secure way for Jenkins to obtain AWS credentials, preferably short-lived role-based credentials or federation where supported.
• A deployment strategy and rollback procedure.

Do not store long-lived AWS access keys, passwords, or repository tokens in source code or in the Jenkinsfile.

Example Dockerfile

Adapt the Java version, build process, and runtime base image to your project's support policy. This example assumes a Maven build produces target/app.jar before the image is built.

FROM eclipse-temurin:21-jre
WORKDIR /app
COPY target/app.jar app.jar
EXPOSE 8080
USER 10001
ENTRYPOINT ["java", "-XX:MaxRAMPercentage=75.0", "-jar", "/app/app.jar"]

Use a maintained, trusted base image, scan images, and consider pinning base images by digest for stricter reproducibility. Ensure the application can run as a non-root user and writes only to intended paths.

Example Jenkinsfile

This declarative pipeline is a template, not a drop-in script. Replace the placeholder repository, region, ECS cluster, service, and task-definition values. Configure AWS authentication in Jenkins through a secure mechanism appropriate to your environment. The agent must have Docker/build tooling and AWS CLI available.

pipeline {
    agent any

    environment {
        AWS_REGION       = 'ap-south-1'
        AWS_ACCOUNT_ID   = '111122223333' // Replace with your account ID
        ECR_REPOSITORY   = 'spring-boot-api'
        ECS_CLUSTER      = 'production-cluster'
        ECS_SERVICE      = 'spring-boot-api-service'
        TASK_FAMILY      = 'spring-boot-api'
        IMAGE_TAG        = "${BUILD_NUMBER}"
    }

    options {
        timestamps()
        disableConcurrentBuilds()
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Build and Test') {
            steps {
                sh 'chmod +x mvnw'
                sh './mvnw -B clean verify'
            }
        }

        stage('Build Image') {
            steps {
                sh '''
                  docker build \
                    --label "org.opencontainers.image.revision=$GIT_COMMIT" \
                    -t "$ECR_REPOSITORY:$IMAGE_TAG" .
                '''
            }
        }

        stage('Authenticate to ECR and Push') {
            steps {
                sh '''
                  set -eu
                  ECR_URI="$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$ECR_REPOSITORY"
                  aws ecr get-login-password --region "$AWS_REGION" \
                    | docker login --username AWS --password-stdin \
                      "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com"
                  docker tag "$ECR_REPOSITORY:$IMAGE_TAG" "$ECR_URI:$IMAGE_TAG"
                  docker push "$ECR_URI:$IMAGE_TAG"
                '''
            }
        }

        stage('Deploy to ECS') {
            steps {
                /*
                 * Recommended production pattern:
                 * 1. Render a new task-definition revision with the immutable image URI.
                 * 2. Register the new task-definition revision.
                 * 3. Update the ECS service to that revision.
                 * 4. Wait for service stability and inspect deployment events.
                 *
                 * The exact command depends on your task-definition template and
                 * deployment policy. Implement these steps using your team's
                 * reviewed deployment script or pipeline library.
                 */
                echo 'Implement reviewed task-definition update and ECS service deployment here.'
            }
        }
    }

    post {
        success {
            echo 'Build and pipeline stages completed. Confirm ECS service health before release sign-off.'
        }
        failure {
            echo 'Pipeline failed. Review stage logs and follow the rollback/runbook process if deployment began.'
        }
        always {
            sh 'docker image prune -f || true'
        }
    }
}

Important note about the deployment stage

The example intentionally leaves the ECS deployment commands as a reviewed implementation step because task definitions often include environment-specific container names, execution roles, networking, secrets, logging, health checks, and resource settings. Avoid using a generic command that silently drops these settings.

A typical implementation uses a version-controlled task-definition template, substitutes the new image URI, registers a new revision with aws ecs register-task-definition, updates the service with aws ecs update-service, and waits for service stability. Validate the rendered task definition before registering it.

AWS permissions: least privilege

The Jenkins identity generally needs permission to authenticate to ECR and push to the specific repository. ECS deployment permissions should be limited to the intended cluster, service, and task-definition family where the APIs support resource-level scoping. Some discovery and pass-role operations may require additional carefully scoped permissions.

The ECS task execution role is distinct from the Jenkins deployment identity. It is commonly used by ECS to pull images from ECR and publish logs; the application task role grants permissions to the running application when it needs to call AWS services.

Do not use administrator permissions as a shortcut. Review the current AWS service authorization reference and test the pipeline using the intended role.

Deployment strategies and rollback

For production, define what happens if the new task revision fails health checks or cannot start.

• Configure ECS deployment circuit-breaker and rollback behavior where appropriate.
• Use ALB health checks when the service is behind a load balancer.
• Keep previous known-good image tags and task-definition revisions available.
• Wait for the ECS service to reach a stable state and inspect deployment events.
• Run smoke tests after deployment.
• Ensure database changes are backward-compatible across old and new application versions.
• Document who can approve production deployment and how to initiate rollback.

A successful image push does not prove that the application deployed successfully. The pipeline should verify ECS service health and application behavior.

Security and reliability checklist

• Jenkins is patched, access-controlled, and uses secured agents.
• Secrets are stored in Jenkins credentials or an approved secret store, not in source control.
• AWS access uses short-lived credentials or role-based federation where feasible.
• IAM permissions follow least privilege and separate build/push from runtime permissions where practical.
• ECR image tags identify a specific build; production deployments do not rely only on mutable latest.
• Images are scanned and base images are maintained.
• ECS task uses an appropriate non-root user and minimal permissions.
• Logs, health checks, alarms, and deployment events are available.
• Rollback is documented and tested.
• Pipeline artifacts and image retention policies are defined.

Troubleshooting

Symptom	Checks
Maven build fails	Java/Maven version, wrapper permissions, dependency access, tests, and build logs
Docker build fails	Dockerfile path, build context, expected JAR location, agent permissions, and disk space
ECR login or push fails	AWS identity, region/account/repository URI, ECR permissions, network access, and image tag
ECS task cannot pull image	Task execution role, ECR repository policy, image URI, network egress, and region/account
Task exits during startup	Container logs, environment variables, secrets access, Java runtime, memory/CPU, and application startup
ECS deployment never stabilizes	Service events, task health, ALB target health, subnet routes, security groups, and container health checks
Application is unhealthy behind ALB	Listener/target group settings, health-check path, application port, response code, and security groups
Rollback does not restore service	Previous task revision/image availability, deployment settings, and database compatibility

Cost and cleanup

Potential costs include Jenkins hosting and agents, ECR storage and data transfer, ECS/Fargate compute, load balancers, logs, and supporting network services such as NAT gateways. Check current regional AWS pricing and your organization's Jenkins hosting costs.

For a learning environment, remove test services, load balancers, and other billable resources after confirming that they are no longer needed. Keep only the resources you intentionally want to retain.

Conclusion

Jenkins, Amazon ECR, and Amazon ECS can form a repeatable delivery path for Spring Boot applications: build and test the code, publish a versioned image, deploy a new task definition, and verify service health. Production quality comes from secure identity, least-privilege permissions, explicit deployment verification, observability, and a tested rollback plan—not simply from automating a Docker push.

AWS console labels, APIs, and pricing can change. Confirm current AWS documentation and validate this template in a non-production environment before use.