Deploying with AWS ECR + GitHub Actions
A complete CI/CD pipeline: Build → Push to ECR → Deploy to EC2

1. What is ECR? ECR (Elastic Container Registry) is AWS's private Docker image registry — think of it as a private Docker Hub that lives inside AWS. Instead of pushing your images to Docker Hub, you push them to ECR.

Why ECR over Docker Hub?
• Lives inside AWS — pulling from EC2 is fast and free (no egress costs)
• Private by default — no public exposure
• Integrates natively with IAM — no separate login credentials
• Automatically scans images for security vulnerabilities on push

1. The Big Picture Here is how all the pieces connect together:

GitHub (your code)
|
| push to main branch
v
GitHub Actions Runner
|
|-- 1. Checkout code
|-- 2. Configure AWS credentials
|-- 3. Login to ECR
|-- 4. Build frontend image
|-- 5. Push frontend to ECR
|-- 6. Build backend image
|-- 7. Push backend to ECR
|-- 8. SSH into EC2
|
|-- pulls frontend from ECR
|-- pulls backend from ECR
|-- pulls mariadb from Docker Hub
|-- pulls adminer from Docker Hub
|-- runs docker compose up

1. ECR Repositories How many repos do you need? You only create ECR repos for YOUR custom images. Public official images (MariaDB, Adminer) come directly from Docker Hub — no ECR needed for them.

Service Image Source ECR Repo Needed?
Frontend Your custom code YES
Backend Your custom code YES
MariaDB Docker Hub (mariadb:11) NO
Adminer Docker Hub (adminer:latest) NO

ECR Repository URL Structure
After creating a repo, AWS gives you a URI like this:

123456789012.dkr.ecr.ap-south-1.amazonaws.com/myapp-frontend

123456789012 = your AWS account ID
dkr.ecr = ECR service
ap-south-1 = your region
amazonaws.com = AWS domain
/myapp-frontend = your repository name

How to Create ECR Repos
AWS Console → ECR → Create Repository → do this twice:

Settings that matter:
• Visibility: Private (always)
• Tag Immutability: Enabled — prevents overwriting existing tags
• Scan on Push: Enabled — auto scans for CVEs on every push
• Everything else: leave as default

Create two repos named:
myapp-frontend
myapp-backend

1. IAM — Users and Roles IAM User vs IAM Role IAM User IAM Role What it is Permanent identity with fixed keys Temporary identity, auto-assumed Has permanent keys? Yes No Who uses it External things (GitHub Actions) AWS services (EC2 → ECR) Credentials Access Key + Secret Key Temporary token (auto-rotated)

IAM User — for GitHub Actions
GitHub Actions runs on a machine outside AWS. It needs real credentials to prove its identity to AWS.

Steps to create:

1. AWS Console → IAM → Users → Create User
2. Name it: github-actions-ecr
3. Attach policy: AmazonEC2ContainerRegistryFullAccess
4. Security Credentials tab → Create Access Key → choose CLI
5. IMPORTANT: Copy both keys immediately — secret shown only once

IAM Role — for EC2
EC2 lives inside AWS. Attach a role to the instance instead of putting keys on the server (keys on server = security risk).

Steps to create:

1. AWS Console → IAM → Roles → Create Role
2. Trusted entity type: AWS Service → EC2
3. Attach policy: AmazonEC2ContainerRegistryReadOnly
4. Name it: ec2-ecr-readonly
5. EC2 → Instances → your instance → Actions → Security → Modify IAM Role → attach it

Verify it worked by SSHing into EC2 and running:
aws sts get-caller-identity
If it returns your account ID and role name, the role is working.

1. GitHub Secrets Go to: GitHub repo → Settings → Secrets and Variables → Actions → New Repository Secret

Secret Name Value
AWS_ACCESS_KEY_ID Your IAM user access key
AWS_SECRET_ACCESS_KEY Your IAM user secret key
AWS_REGION e.g. ap-south-1
EC2_HOST Your EC2 public IP address
EC2_SSH_KEY Full contents of your .pem file (including header/footer)

For EC2_SSH_KEY — open your .pem file, copy everything including the -----BEGIN RSA PRIVATE KEY----- header and -----END RSA PRIVATE KEY----- footer, paste as the secret value.

1. ECR Authentication Explained ECR does not use username/password like Docker Hub. It uses temporary tokens that expire every 12 hours. The command to get and apply the token is:

aws ecr get-login-password --region ap-south-1 \
| docker login \
--username AWS \
--password-stdin \
123456789012.dkr.ecr.ap-south-1.amazonaws.com

• aws ecr get-login-password — asks AWS for a temporary password (valid 12 hours)
• | — pipes that password into the next command
• docker login --username AWS — logs Docker into ECR using the temp password
• --username AWS — ECR always uses the literal string AWS as username, not your IAM username

In GitHub Actions, the aws-actions/amazon-ecr-login@v1 action runs this automatically. You never write it manually in the workflow.

1. The GitHub Actions Workflow steps.login-ecr.outputs.registry Explained This is GitHub Actions syntax for referencing the output of a previous step:

${{ steps.login-ecr.outputs.registry }}

steps = look in previous steps
login-ecr = the id you gave the step (id: login-ecr)
outputs = this step exposes output values
registry = the specific output: your ECR base URL

Resolves to: 123456789012.dkr.ecr.ap-south-1.amazonaws.com

The amazon-ecr-login action automatically figures out your account ID and region from your credentials and exposes it as the registry output. Use it instead of hardcoding your account ID.

Complete Workflow File
Save this as .github/workflows/deploy.yml in your repo:

name: Build, Push to ECR, Deploy to EC2

on:
push:
branches:
- main

jobs:
deploy:
runs-on: ubuntu-latest

steps:
  - name: Checkout Code
    uses: actions/checkout@v3

  - name: Configure AWS Credentials
    uses: aws-actions/configure-aws-credentials@v2
    with:
      aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
      aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
      aws-region: ${{ secrets.AWS_REGION }}

  - name: Login to Amazon ECR
    id: login-ecr
    uses: aws-actions/amazon-ecr-login@v1

  - name: Build and Push Frontend
    env:
      ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
      IMAGE_TAG: ${{ github.sha }}
    run: |
      docker build -t $ECR_REGISTRY/myapp-frontend:$IMAGE_TAG ./frontend
      docker tag $ECR_REGISTRY/myapp-frontend:$IMAGE_TAG $ECR_REGISTRY/myapp-frontend:latest
      docker push $ECR_REGISTRY/myapp-frontend:$IMAGE_TAG
      docker push $ECR_REGISTRY/myapp-frontend:latest

  - name: Build and Push Backend
    env:
      ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
      IMAGE_TAG: ${{ github.sha }}
    run: |
      docker build -t $ECR_REGISTRY/myapp-backend:$IMAGE_TAG ./backend
      docker tag $ECR_REGISTRY/myapp-backend:$IMAGE_TAG $ECR_REGISTRY/myapp-backend:latest
      docker push $ECR_REGISTRY/myapp-backend:$IMAGE_TAG
      docker push $ECR_REGISTRY/myapp-backend:latest

  - name: Deploy to EC2
    uses: appleboy/ssh-action@v0.1.10
    with:
      host: ${{ secrets.EC2_HOST }}
      username: ubuntu
      key: ${{ secrets.EC2_SSH_KEY }}
      envs: AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY,AWS_REGION
      script: |
        aws ecr get-login-password --region $AWS_REGION \
          | docker login \
            --username AWS \
            --password-stdin \
            123456789012.dkr.ecr.ap-south-1.amazonaws.com
        cd /home/ubuntu/myapp
        docker compose pull frontend backend
        docker compose up -d --no-build
        docker image prune -f

1. Docker Compose File This file lives both in your GitHub repo and on your EC2 instance at /home/ubuntu/myapp/docker-compose.yml

services:
frontend:
image: 123456789012.dkr.ecr.ap-south-1.amazonaws.com/myapp-frontend:latest
ports:
- "3000:3000"
depends_on:
- backend
restart: always

backend:
image: 123456789012.dkr.ecr.ap-south-1.amazonaws.com/myapp-backend:latest
ports:
- "8000:8000"
depends_on:
- db
environment:
DB_HOST: db
DB_PORT: 3306
DB_NAME: myapp
DB_USER: myuser
DB_PASS: mypassword
restart: always

db:
image: mariadb:11
environment:
MYSQL_ROOT_PASSWORD: rootpassword
MYSQL_DATABASE: myapp
MYSQL_USER: myuser
MYSQL_PASSWORD: mypassword
volumes:
- db_data:/var/lib/mysql
restart: always

adminer:
image: adminer:latest
ports:
- "8080:8080"
restart: always

volumes:
db_data:

1. Things to Change for Your Project
   File What to Change Change To
   docker-compose.yml ECR URI in image: fields (x2) Your actual ECR repo URIs from AWS console
   deploy.yml ./frontend in docker build Actual path to your frontend folder in repo
   deploy.yml ./backend in docker build Actual path to your backend folder in repo
   deploy.yml ECR URL in docker login script Your actual ECR registry base URL
   deploy.yml username: ubuntu ec2-user if using Amazon Linux, ubuntu if Ubuntu
   deploy.yml /home/ubuntu/myapp Path where docker-compose.yml lives on EC2
   deploy.yml myapp-frontend / myapp-backend Your actual ECR repo names if different

2. EC2 Instance Setup
   SSH into your EC2 and make sure these are installed:

Check Docker

docker --version

Check Docker Compose

docker compose version

Install AWS CLI if missing

sudo apt update
sudo apt install awscli -y

Verify AWS CLI

aws --version

Create app directory

mkdir -p /home/ubuntu/myapp

Copy your docker-compose.yml to EC2 (run this from your local machine):

scp -i your-key.pem docker-compose.yml ubuntu@your-ec2-ip:/home/ubuntu/myapp/

1. Complete Setup Checklist Do these in order before your first deploy:

• Create ECR repo: myapp-frontend
• Create ECR repo: myapp-backend
• Create IAM User (github-actions-ecr) with ECR full access
• Generate access keys for IAM user
• Add AWS_ACCESS_KEY_ID to GitHub Secrets
• Add AWS_SECRET_ACCESS_KEY to GitHub Secrets
• Add AWS_REGION to GitHub Secrets
• Add EC2_HOST to GitHub Secrets
• Add EC2_SSH_KEY to GitHub Secrets
• Create IAM Role (ec2-ecr-readonly) with ECR read-only access
• Attach IAM Role to EC2 instance
• Install AWS CLI on EC2
• Create /home/ubuntu/myapp directory on EC2
• Copy docker-compose.yml to EC2
• Create .github/workflows/deploy.yml in your repo
• Push to main branch and watch GitHub Actions tab