Introduction

If you are managing container deployments without complex CI/CD automation pipelines, navigating the AWS Management Console to set up Amazon Elastic Container Registry (ECR) is the most direct way to configure your image repositories. While public registries like Docker Hub allow quick uploads, enterprise cloud environments demand isolated network access controls and encryption at rest. In this hands-on guide, we will walk through provisioning a private ECR repository directly through the AWS Console UI. Beyond simple point-and-click operations, we will cover critical AWS IAM identity controls, KMS encryption settings, automated image scan policies, and how to properly extract authentication commands directly from the Web Interface.

Prerequisites

• An AWS account (free tier is enough)
• An EC2 instance (Amazon Linux 2) or your local machine with Docker support
• AWS CLI configured with your credentials

Step 1: Launch an EC2 instance and SSH

• If you don’t know how to launch EC2 instances and how to access instances using SSH, you can go through this link: how to create EC2 instance

Step 2: Install Docker and Verify

• On Amazon Linux EC2 instances, Docker isn’t installed by default, so we have to install docker and verify

sudo yum update -y
sudo yum install docker -y
sudo service docker start
sudo usermod -a -G docker ec2-user

    

• After running the usermod command, log out and log back in so the group change takes effect; otherwise, you’ll have to prefix every Docker command with sudo.

• Now Verify the installation

docker –version
sudo docker run hello-world
    

• If everything is set up correctly, you’ll see a “Hello from Docker!” message. This confirms Docker can pull images and run containers successfully.

Step 2: Run Your First Real Container

• Installing Docker is one thing; running something useful is another. Let’s spin up an Nginx web server.

docker run -d -p 8080:80 --name my-first-nginx nginx
docker ps
curl http://localhost:8080
    

• You can also use EC2 public IP on your browser like https://ec2_public_ip:8080/

• The -d option starts the container in detached mode (in the background), and -p 8080:80 maps port 80 in the container to port 8080 on your host. Running curl should return the HTML of the default Nginx welcome page.

Step 3: Build Your Own Custom Image

This is the real learning moment: building your own image instead of just using someone else’s.

• Create a project folder and a simple HTML file

mkdir my-app && cd my-app
echo "<h1>Hello from my container, AWS Community Builder!</h1>" > index.html
    

• Now create a Dockerfile

FROM nginx:alpine
COPY index.html /usr/share/nginx/html/index.html
EXPOSE 80
    

• Build and run it

docker build -t my-first-app:v1 .
docker run -d -p 8081:80 --name my-app-container my-first-app:v1
curl http://localhost:8081
    

Now you should see your own custom message instead of the default Nginx page. That’s the basic idea behind containers: the image is a portable, immutable template, and every container you run from it acts the same way, anywhere.

Step 4: Practice Core Docker Command

• Before moving to AWS-specific services, it is worth getting comfortable with the everyday Docker commands you’ll use constantly:

docker ps -a                          # list all containers, running or stopped
docker logs my-app-container           # view container logs
docker exec -it my-app-container sh    # open a shell inside the running container
docker stop my-app-container
docker start my-app-container
docker rm -f my-first-nginx            # remove a container
docker images                          # list all local images
    

Spend a few minutes with each of these; you will be relying on knowing how to inspect logs and get a shell inside a running container constantly when debugging in ECS or EKS later.

Step 5: Access Amazon ECR and Select Visibility Scope

Log into your AWS Management Console using an identity with sufficient IAM permissions (AmazonEC2ContainerRegistryFullAccess).

• In the top search bar, type ECR and select Elastic Container Registry.

• In the left navigation menu under Amazon ECR, click Repositories.

• Choose between Private (accessible only within your AWS account/VPC boundaries) or Public (globally accessible via Gallery). For enterprise microservices, select Private.

Step 6: Push Your Image to Amazon ECR

So far, none of it has gone local. Now, we will push our image to Amazon Elastic Container Registry (ECR), AWS’s managed Docker registry, so it can be pulled later by ECS or EKS.

• Search the AWS console for ECR and open ECR dashboard
• Click on “create” and given name of your images

• Remaining setting leave as it is.
• And click on create

• Click on your repository name and click on “View push command.”
• You will get command for push images from local to AWS ECR
• Copy the command and paste on your terminal

Notes: Before pushing the images, you need to manage the AWS access key and AWS secret access key.

Step 7: configure AWS CLI to push images

If you are using Amazon Linux, you don’t need to install the AWS CLI. If you are using Ubuntu or another Linux environment, then you have to install the AWS CLI. To install the CLI, you can check here: how to install AWS CLI

• Go to your terminal and type aws configure
  • AWS Access Key: xxxx
  • AWS Secret Access Key: xxxxx
  • Default region: xxxxx
  • Default output format: xxxx

• Now, go back to your ECR push command and paste it on your terminal.

Once the push completes, head over to the AWS Console → ECR → your repository, and you should see your image listed with its tag.

AWS Console Architectural Constraints:

• Immutability Lock: Be aware that Tag Immutability cannot be temporarily overridden during a push. If your continuous deployment script attempts to push an updated build to an immutable tag, the daemon will throw a Pushed tag already exists response and abort the deployment.

• KMS Permission Mismatch: If you enable AWS KMS Customer Managed Keys (CMK) via the console during repo creation, ensure that any IAM user/role running local docker push commands also has explicit kms:Decrypt and kms:GenerateDataKey permissions assigned in the KMS key policy, or the push stream will terminate midway.

Production Troubleshooting

Managing container infrastructure via the AWS Web Console presents specific configuration traps. Here is how to resolve the most common issues

Error 1: “Push Commands” Modal Displays Empty or Invalid Region

• The Issue: Clicking View push commands in the console generates CLI snippets containing empty account IDs or incorrect AWS regions (e.g., [https://.dkr.ecr..amazonaws.com] (https:// .dkr.ecr..amazonaws.com))

• The Root Cause: Your IAM identity lacks ecr:GetAuthorizationToken permissions across all resources (*), causing the AWS Console UI scripts to fail when rendering dynamically filled variables.

• The Fix: Attach an inline policy or ensure your IAM role includes the following permission block

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ecr:GetAuthorizationToken",
      "Resource": "*"
    }
  ]
}
    

Error 2: Vulnerability Scan State Returns “SCAN_FAILED”

• The Issue: After pushing an image via CLI and checking the Images list in the AWS ECR Console, the Scan status column displays a red status reading SCAN_FAILED or EXPIRED.

• The Root Cause: Amazon ECR Basic Scanning relies on an upstream vulnerability database. If the pushed base image uses an unsupported operating system (like an obscure Linux distribution or an unindexed base layer), the scan engine cannot parse package manifests.

• The Fix: Switch your AWS Console settings from Basic Scanning to Enhanced Scanning (powered by Amazon Inspector). Navigate to ECR Console Settings -> Private Registry -> Scanning Configuration, and toggle to Enhanced Scanning. This enables deep programming-language-level package inspection (npm, pip, maven) alongside OS packages.

Error 3: “Repository already exists” Validation Error on Creation

• The Issue: Attempting to create a new repository in the Web UI returns a red validation alert: The repository with name ‘x’ already exists in the registry

• The Root Cause: ECR repository names are unique within a specific AWS Region for your Account ID. However, if you deleted a repository recently or created it in a different AWS Region via the CLI, the console view scope might be filtered out.

• The Fix: Check your active AWS Region dropdown in the top right header of the console. Switch across your active regions (e.g., us-east-1, us-west-1) to locate where the existing namespace resides, or delete the old repository using the AWS CLI:

aws ecr delete-repository --repository-name  --region  --force
    

Finally, push your Docker images from local to AWS ECR services. Now you can deploy applications on AWS EC2, EKS, ECS, or AWS Fargate using these images.