Fabio Luiz

From Docker build to AWS in 5 commands

2 min read

A step-by-step guide to manually deploying Docker images to ECR, following best practices like maintaining both SHA and latest tags.

This guide assumes you’ve configured the AWS CLI with SSO. See The right way to authenticate with AWS for setup.

ECR Authentication

ECR (Elastic Container Registry) is AWS’s private Docker registry. Before you can push images, Docker needs credentials to authenticate with ECR.

This command retrieves a temporary password from AWS and pipes it directly to docker login. The password is valid for 12 hours:

aws ecr get-login-password --region ca-central-1 --profile my-profile | \
  docker login --username AWS --password-stdin 123456789012.dkr.ecr.ca-central-1.amazonaws.com

Building for ARM64

When building for AWS services that run on ARM-based instances (like Graviton), use the --platform linux/arm64 flag. ARM-based Fargate instances are cheaper than x86, and this flag cross-compiles for ARM64 even when building on an Intel Mac.

docker build --platform linux/arm64 -t $ECR_URL:$SHA .

Docker Tags: Why You Need Two

A Docker tag is a human-readable label pointing to an image digest (images are actually identified by their SHA256 content hash). The -t flag assigns a tag during build. We create two tags:

  • SHA tag (f8afe6a7): identifies exactly which code version is running—useful for traceability and rollbacks
  • latest tag: a convention for “most recent stable build”—ECS task definitions reference this to always pull the newest image

The docker tag command creates an alias—it doesn’t copy the image, just adds another name pointing to the same digest. Pushing twice doesn’t upload the image twice.

Complete Workflow

# Define variables once
SHA=$(git rev-parse --short HEAD)
ECR_URL=123456789012.dkr.ecr.ca-central-1.amazonaws.com/my-service
 
# Authenticate (valid for 12 hours)
aws ecr get-login-password --region ca-central-1 --profile my-profile | \
  docker login --username AWS --password-stdin 123456789012.dkr.ecr.ca-central-1.amazonaws.com
 
# Build and tag
docker build --platform linux/arm64 -t $ECR_URL:$SHA .
docker tag $ECR_URL:$SHA $ECR_URL:latest
 
# Push both tags
docker push $ECR_URL:$SHA
docker push $ECR_URL:latest

Verify the Push

Confirm the image was pushed by listing images in the ECR repository:

aws ecr describe-images \
  --repository-name my-service \
  --region ca-central-1 \
  --profile my-profile

You should see both tags pointing to the same image:

{
  "imageTags": ["f8afe6a7", "latest"],
  "imagePushedAt": "2025-12-10T12:34:56-05:00",
  "imageSizeInBytes": 422898486
}

Key Takeaways

  • ECR requires temporary authentication before each push session (valid 12 hours)
  • Build with --platform linux/arm64 for ARM-based AWS instances (cheaper than x86)
  • Push both SHA and latest tags—one for immutability, one for convenience

See also: Docker, AWS, AWS SSO, CD