LAB: GitLab CI/CD Docker Deploy to AWS EC2

Source: Dev.to

🎯 Lab Objective

Build a full CI/CD pipeline that:

• Connects GitLab to Mac terminal
• Builds Docker image
• Pushes image to GitLab Registry
• SSH into EC2
• Deploys container
• Handles real‑world production errors

🏗️ Architecture

Mac Terminal
     ↓
GitLab Repo
     ↓
GitLab CI/CD Pipeline
     ↓
Docker Image Build
     ↓
Push to GitLab Container Registry
     ↓
SSH to AWS EC2
     ↓
Docker Pull & Run
     ↓
Application Live on Port 80

🔹 Steps

STEP 1 — GitLab Pages Basic Pipeline

.gitlab-ci.yml

image: busybox

pages:
  stage: deploy
  script:
    - echo "The site will be deployed"
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Trigger pipeline:

git commit --allow-empty -m "Trigger pipeline"
git push origin master

STEP 2 — Add Docker Build Stage

Create Dockerfile (project root):

FROM nginx:alpine
COPY public /usr/share/nginx/html
EXPOSE 80

Update .gitlab-ci.yml:

stages:
  - build
  - push
  - deploy

variables:
  IMAGE_NAME: registry.gitlab.com/$CI_PROJECT_PATH:latest

build_image:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  script:
    - docker build -t $IMAGE_NAME .

STEP 5 — Push to GitLab Container Registry

Add the push job:

push_image:
  stage: push
  image: docker:24
  services:
    - docker:24-dind
  script:
    - echo $CI_REGISTRY_PASSWORD | docker login -u $CI_REGISTRY_USER --password-stdin $CI_REGISTRY
    - docker push $IMAGE_NAME

🔴 Errors & Fixes

ERROR #1 — Image Not Found

Error

An image does not exist locally with the tag

Fix
Ensure the build and push stages use the same $IMAGE_NAME.

STEP 6 — Deploy to AWS EC2

Deploy job:

deploy_ec2:
  stage: deploy
  image: alpine
  before_script:
    - apk add --no-cache openssh
  script:
    - echo "$EC2_KEY" > key.pem
    - chmod 600 key.pem
    - ssh -o StrictHostKeyChecking=no -i key.pem ubuntu@$EC2_HOST "
        docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY &&
        docker pull $IMAGE_NAME &&
        docker stop web || true &&
        docker rm web || true &&
        docker run -d -p 80:80 --name web $IMAGE_NAME
      "

ERROR #2 — SSH Hostname Not Resolved

Cause
CI/CD variables not set.

Fix
Add the following variables in Settings → CI/CD → Variables (not protected, visible):

ERROR #3 — Port 80 Already in Use

Pipeline error

failed to bind host port 80
address already in use

Investigation

ssh -i key.pem ubuntu@$EC2_HOST
sudo lsof -i :80

Result shows nginx listening on port 80.

Fix

sudo systemctl stop nginx
sudo systemctl disable nginx

Re‑run the pipeline → SUCCESS.

🔹 Final Result

The application is accessible at:

http://

🧠 Real DevOps Troubleshooting Lessons

These are typical production‑level debugging steps.

🎓 Interview Explanation Version

If an interviewer asks, “How would you deploy using GitLab CI/CD to EC2?” you can answer:

1. Create a Dockerfile for the application.
2. Configure a multi‑stage .gitlab-ci.yml pipeline (build, push, deploy).
3. Build the Docker image and push it to the GitLab Container Registry.
4. Store the EC2 SSH private key and host IP as CI/CD variables.
5. In the deploy stage, SSH into the EC2 instance, log in to the registry, pull the image, stop/remove any existing container, and run the new container on port 80.
6. Handle common issues (missing variables, port conflicts, existing services) to ensure an idempotent, production‑ready deployment.