Docker Image Automation with GitLab: A Complete CI/CD Pipeline

Automating Docker Image Build, Push, and Deployment with GitLab CI/CD

In this article, we'll explore how to create a CI/CD pipeline in GitLab to build a Docker image, push it to the GitLab Container Registry, and optionally deploy it. GitLab CI/CD simplifies the automation of these processes, ensuring consistency and efficiency in software delivery.

Overview of the Pipeline

The pipeline consists of three stages:

1. Build: Compile the application and generate the JAR file.
2. Package: Build the Docker image and push it to the GitLab Container Registry.
3. Deploy: Deploy the Docker image (customizable based on your deployment strategy).

The .gitlab-ci.yml File

Below is the .gitlab-ci.yml file used to define the CI/CD pipeline:

stages:

  - build

  - package

  - deploy

 

variables:

  DOCKER_IMAGE: "registry.gitlab.com/<your-namespace>/<your-repository>/<your-app-name>"

 

build-jar:

  stage: build

  image: maven:3.8.5-openjdk-11

  script:

    - mvn clean package

  artifacts:

    paths:

      - target/*.jar

    expire_in: 1 day

 

build-docker-image:

  stage: package

  image: docker:20.10.7

  services:

    - docker:dind

  script:

    - echo "Building Docker image"

    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY

    - docker build -t $DOCKER_IMAGE:$CI_COMMIT_SHORT_SHA .

    - docker push $DOCKER_IMAGE:$CI_COMMIT_SHORT_SHA

 

deploy:

  stage: deploy

  script:

    - echo "Deploy stage can be customized here"

Explanation of the Configuration

1. Stages

The pipeline is divided into three stages: build, package, and deploy. Each stage represents a step in the CI/CD process.

2. Variables

• DOCKER_IMAGE: Specifies the name of the Docker image, including the GitLab Container Registry URL, namespace, repository, and app name.
• CI_REGISTRY, CI_REGISTRY_USER, and CI_REGISTRY_PASSWORD are predefined GitLab variables that store credentials for the GitLab Container Registry.

3. Build Stage

This stage compiles the Java application and generates a JAR file using Maven.

build-jar:

  stage: build

  image: maven:3.8.5-openjdk-11

  script:

    - mvn clean package

  artifacts:

    paths:

      - target/*.jar

    expire_in: 1 day

• The image keyword specifies the Docker image for the job environment.
• script runs the Maven commands to build the project.
• artifacts ensures the JAR file is available for the next stage.

4. Package Stage

This stage builds the Docker image and pushes it to the GitLab Container Registry.

build-docker-image:

  stage: package

  image: docker:20.10.7

  services:

    - docker:dind

  script:

    - echo "Building Docker image"

    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY

    - docker build -t $DOCKER_IMAGE:$CI_COMMIT_SHORT_SHA .

    - docker push $DOCKER_IMAGE:$CI_COMMIT_SHORT_SHA

• docker:dind (Docker-in-Docker) is used to enable Docker commands in the pipeline.
• docker login authenticates with the GitLab Container Registry.
• docker build creates the Docker image.
• docker push uploads the image to the registry.

5. Deploy Stage

This stage is a placeholder for deployment logic. You can customize it as needed.

deploy:

  stage: deploy

  script:

    - echo "Deploy stage can be customized here"

Step-by-Step Guide to Set Up the Pipeline

1. Enable the GitLab Container Registry
• Go to your GitLab project.
• Navigate to Settings > Packages & Registries > Container Registry.
• Ensure the Container Registry is enabled.
2. Set CI/CD Variables
• Go to Settings > CI/CD > Variables.
• Add the following variables:
• CI_REGISTRY_USER: Your GitLab username.
• CI_REGISTRY_PASSWORD: Your GitLab personal access token with read_registry and write_registry permissions.
• Optionally, override DOCKER_IMAGE if needed.
3. Push Code and Pipeline Configuration
• Commit and push your code along with the .gitlab-ci.yml file to the repository.
• The pipeline will automatically start executing.
4. Verify the Docker Image in the GitLab Registry
• After a successful pipeline run, navigate to Packages & Registries > Container Registry in your GitLab project.
• You should see the newly built Docker image.

Troubleshooting

• Maven Build Errors: Ensure the pom.xml file is correctly configured and in the root of your repository.
• Docker Authentication Issues: Verify the CI_REGISTRY_USER and CI_REGISTRY_PASSWORD variables.
• Deployment Issues: Customize the deploy stage based on your deployment requirements.

Conclusion

By following this guide, you can set up a robust CI/CD pipeline in GitLab to automate building, pushing, and deploying Docker images. This approach ensures a streamlined workflow and minimizes manual effort in managing containerized applications.