How to Push Docker Images into AWS ECR: A Step-by-Step Guide

Introduction to Amazon ECR

As you begin building containerized applications, you quickly realise the need for a secure, reliable environment to store your Docker images. While Docker Hub is a popular choice, developers within the AWS ecosystem typically leverage Amazon Elastic Container Registry (ECR). ECR is a fully managed container registry that simplifies the process of storing, managing, and deploying Docker container images.

By using ECR, you benefit from high availability and seamless integration with core AWS services like Amazon ECS (Elastic Container Service), EKS (Elastic Kubernetes Service), and AWS Lambda. In this guide, we will walk you through the step-by-step process of pushing your first local Docker image to AWS ECR.

Prerequisites

Before starting the technical configuration, ensure you have the following requirements met:

• AWS Account: An active account with permissions to manage ECR.
• AWS CLI: The AWS Command Line Interface installed and configured on your local machine.
• Docker: Docker Desktop or Docker Engine installed and running.
• IAM Permissions: Your AWS user must have the AmazonEC2ContainerRegistryFullAccess policy attached.

Step 1: Create an ECR Repository

First, you need a destination for your image. While you can use the AWS Management Console, the AWS CLI is faster for this workflow.

Execute the following command to create a new repository:

aws ecr create-repository --repository-name my-first-repo --region us-east-1

Replace my-first-repo with your preferred name and us-east-1 with your target region. Upon success, AWS will return a JSON object containing the repositoryUri. Save this URI; you will need it for the following steps.

Step 2: Authenticate Your Docker Client

Docker requires authentication to communicate with AWS. Rather than a static password, AWS uses a temporary token. You can retrieve this token and pipe it directly to Docker with this command:

aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin your-account-id.dkr.ecr.us-east-1.amazonaws.com

Ensure you replace your-account-id with your actual 12-digit AWS Account ID. A “Login Succeeded” message indicates you are ready to proceed.

Step 3: Build Your Docker Image

If you do not have an image ready, let’s build a lightweight example. Create a file named Dockerfile and add these lines:

FROM alpine
CMD ["echo", "Hello from ECR!"]

Now, build the image locally and assign it a tag:

docker build -t my-local-image .

Step 4: Tag Your Image for ECR

To push an image to ECR, the image name must match the AWS repository URI format. You accomplish this by creating an alias (tag) of your local image that identifies the remote AWS repository.

Run this command:

docker tag my-local-image:latest your-account-id.dkr.ecr.us-east-1.amazonaws.com/my-first-repo:latest

This does not modify the image contents; it simply creates a pointer that Docker recognizes as destined for your specific AWS registry.

Step 5: Push the Image to AWS ECR

With authentication complete and the image correctly tagged, use the docker push command to upload it to the cloud:

docker push your-account-id.dkr.ecr.us-east-1.amazonaws.com/my-first-repo:latest

Depending on your upload speed and image size, this may take a moment. Once the progress bars finish, your image is securely stored in AWS ECR.

Verifying the Upload

To confirm the process was successful, navigate to the AWS Management Console. Go to Amazon ECR > Repositories and select your repository. You should see an image listed with the “latest” tag and a recent timestamp.

Common Troubleshooting Tips

• Permissions Errors: Ensure your IAM user has the ecr:PutImage and ecr:InitiateLayerUpload permissions.
• Region Mismatch: Verify that your CLI login region matches the region where you created the repository.
• Docker Daemon: Confirm that the Docker service is running on your local machine.
• Credential Automation: For more efficient workflows, consider using the Amazon ECR Docker Credential Helper to handle authentication automatically.

Conclusion

Pushing Docker images to AWS ECR is a foundational skill for DevOps professionals and Cloud Engineers. It provides a private, scalable environment for your container assets, allowing you to deploy seamlessly to ECS, EKS, or AWS Lambda. Now that your image is hosted on ECR, you are ready to begin orchestrating your cloud-native applications.