TutorialsLast Updated Oct 28, 20267 min read

Automatically deploy private Docker images to Amazon ECR

Dominic Motuka

DevOps Engineer at Andela

This article is an introduction to using an automated CI/CD pipeline to build and push production-grade Docker images to the Amazon Elastic Container Registry (ECR) for storage.

To follow along, you will need a free CircleCI account and an AWS account.

What is Amazon ECR?

Amazon ECR is a fully-managed, private Docker container registry that makes it easy for developers to store, manage, and deploy Docker container images. Amazon ECR integrates seamlessly with Amazon Elastic Container Service (Amazon ECS) and Amazon Elastic Kubernetes Service (Amazon EKS). Amazon ECR can also be used with other cloud vendors.

Why would you want to use a private Docker registry like Amazon ECR?

  • In many circumstances, it is desirable to segregate the development, test, and production registries.
  • It’s fully managed, which eliminates the need to operate your own container repositories or worry about scaling the underlying infrastructure.
  • It’s secure. A private container registry with scanning capabilities and role-based access control offers more security, governance (IAM), and efficient management. It transfers your container images over HTTPS and automatically encrypts your images at rest.
  • Running registries close to the systems running the containers cuts deployment latency and reduces exposure to network outages.

Developers use registries to store images created during the application development process. Continuous integration pipelines can automate the process of both building container images and pushing these artifacts into Amazon ECR, making development faster and more efficient.

Imagine a pipeline where you push a commit that triggers a build on CircleCI, which then pushes a new image into Amazon ECR. Amazon ECR can then emit an Amazon EventBridge event that triggers a deployment, without any manual steps required.

Registries make it much easier to build a fully automated pipeline like this. Container images stored in the registry can then be used in various phases of development.

In a few steps, we are going to containerize a simple Node.js application, build the image, and push it to Amazon ECR, all in an automated CircleCI workflow. We’ll use CircleCI orbs to keep our pipeline configuration minimal and easy to understand.

Setting up Amazon ECR

From the AWS management console, select IAM. This service lets you manage access to AWS resources.

In the IAM console, go to IAM users and click Create user. I called mine ci-cd-ecr, but any name will work.

The IAM Create user wizard on the Specify user details step, with ci-cd-ecr entered as the user name.

Next, set permissions for the user. Click Attach policies directly and select AmazonEC2ContainerRegistryFullAccess. This policy lets the pipeline create a private repository for the image and push images to it. For production pipelines, consider a custom policy that grants only the Amazon ECR actions the pipeline needs.

The Set permissions step with Attach policies directly selected and only AmazonEC2ContainerRegistryFullAccess checked in the filtered policy list.

Finally, review the details and click Create user.

Because we need the new user to programmatically access AWS resources, we need to create an access key. Click the username of the new user, open the Security credentials tab, and click Create access key. On the Access key best practices & alternatives page, choose Other and click Next. Optionally, add a description tag, then click Create access key.

The Access key best practices and alternatives page for the ci-cd-ecr user, with the Other use case selected.

Once you are done, a banner warns that this is the only time the secret access key can be viewed or downloaded, and the page shows the user’s credentials. This page is only displayed once, so make a note of the Access key and the Secret access key which will be used later on. Alternatively, you can download the provided .csv file, which contains the same credentials.

The Retrieve access keys page showing the new access key ID, a masked secret access key with a Show link, and the Download .csv file button.

Note: Long-lived access keys are the quickest way to get started. For production pipelines, consider using OpenID Connect (OIDC) instead, so CircleCI can assume an IAM role without storing any AWS keys.

Setting up a CircleCI pipeline using the AWS-ECR orb

The code for this demo is available on GitHub. Clone the application using the following command:

git clone https://github.com/CIRCLECI-GWP/circleci-ecr-app-demo

Find the CircleCI config.yml file in the .circleci/ folder. Using orbs, as you’ll see, you can build an image and push it to Amazon ECR using only 16 lines of config! The aws-ecr orb comes prepackaged with commands to:

  • Build an image
  • Log in to Amazon ECR
  • Create an Amazon ECR repo, if one doesn’t exist
  • Push an image to Amazon ECR

Here is the full config for your pipeline:

version: 2.1

orbs:
  aws-cli: circleci/aws-cli@5.4.2
  aws-ecr: circleci/aws-ecr@10.0.0

workflows:
  build_and_push_image:
    jobs:
      - aws-ecr/build_and_push_image:
          context: aws-dev
          auth:
            - aws-cli/setup
          create_repo: true
          dockerfile: Dockerfile
          path: .
          repo: circleci-ecr-app-demo
          tag: "$CIRCLE_SHA1"

This configuration file uses the Amazon Elastic Container Registry orb to build and deploy your Docker image. The auth step uses the aws-cli/setup command from the AWS CLI orb to configure the AWS credentials from the context before the aws-ecr orb logs in to Amazon ECR. The dockerfile: command specifies the path to your Dockerfile. The demo repo uses the following Dockerfile:

# Set the base image to use for subsequent instructions
FROM node:24-alpine

# Add metadata to an image
LABEL app="simple-node-application"
# Directive to set environmental variables key to value pair
ENV NPM_CONFIG_LOGLEVEL=warn

# Set the working directory for any subsequent ADD, COPY, CMD, ENTRYPOINT,
# or RUN instructions that follow it in the Dockerfile
WORKDIR /usr/src/app

# Copy files or folders from source to the dest path in the image's filesystem.
COPY package.json /usr/src/app/
COPY . /usr/src/app/

# Execute any commands on top of the current image as a new layer and commit the results.
RUN npm install --omit=dev

# Define the network ports that this container will listen on at runtime.
EXPOSE 3000

# Configure the container to be run as an executable.
ENTRYPOINT ["npm", "start"]

Adding credentials and environment variables for Amazon ECR

CircleCI contexts allow you to securely store credentials and share them across projects. Since we will need our AWS credentials to deploy our container image, we’ll first need to set up our context.

In the CircleCI dashboard, click Org in the sidebar to open the organization settings. Next, select Contexts. Click Create context and add a unique name for your Context. The Context appears in a list with Security set to All members to indicate that anyone in your organization can access this Context at runtime. As specified in the .circleci/config.yml configuration for this tutorial, the Context name should be aws-dev.

The CircleCI Create Context dialog with aws-dev entered as the context name.

Next, select the aws-dev context.

In the Environment variables section, click Add. Enter the variable name and value you want to associate with this context. Click Add environment variable in the dialog to save. The aws-dev context requires these four environment variables:

  • AWS_ACCESS_KEY_ID is the AWS access key ID for the ci-cd-ecr IAM user created earlier.
  • AWS_SECRET_ACCESS_KEY is the AWS secret access key for the ci-cd-ecr IAM user created earlier.
  • AWS_ACCOUNT_ID is the 12-digit ID of the AWS account that owns the ECR registry.
  • AWS_DEFAULT_REGION is the AWS region where your ECR resources will be located, for example us-east-2.

The aws-dev context page listing AWS_ACCESS_KEY_ID, AWS_ACCOUNT_ID, AWS_DEFAULT_REGION, and AWS_SECRET_ACCESS_KEY with masked values.

Note: You don’t have to set $CIRCLE_SHA1 because it is the default variable available in all CircleCI projects. It’s the SHA1 hash of the last commit of the current build. Using the Git commit hash gives you the ability to trace what’s in the containers. Ideally, it allows you to trace a container back to its Docker image, and then back to the Dockerfile and code contained in the image. In an automated execution environment, this will take you back to the commit that caused the Docker image to be built.

Connecting the application to CircleCI

The next step is to set up a repository on GitHub and link the project to CircleCI. Review Pushing a project to GitHub for instructions.

Log in to CircleCI and click Create project. Enter a project name and click Next. Under Create your first pipeline, connect GitHub if prompted and select the repository (circleci-ecr-app-demo in this case). Keep the default pipeline name and the All pushes trigger, then click Next. CircleCI detects the .circleci/config.yml file that’s already in the repository. Click Next, review the setup, and click Go to project.

The CircleCI Create a project flow on the Pipeline step, with the circleci-ecr-app-demo repository selected and the All pushes trigger.

If the organization still uses the CircleCI GitHub OAuth app, follow the create a project steps for that integration instead.

With the GitHub App flow, the pipeline runs on the next push, so push a commit to the repository to start it. Your first workflow will start running and complete successfully.

A successful aws-ecr/build_and_push_image job in CircleCI with every step green, from Spin up environment to Build Docker Image with buildx.

Now, any time you update your project, your CI pipeline will automatically build a new image and push it to ECR. To review the repository information, go to your AWS management Console.

Conclusion

With both CircleCI and Amazon ECR successfully configured, you can start building images and pushing them to the repository.

With just a few lines of code, you were able to build and push your Docker image to Amazon ECR. CircleCI orbs save time by importing pre-built commands, jobs, and executors into CircleCI configuration files, providing easy integration with cloud services and other tools.