How to Use Docker in GitLab CI: Simple Guide

To use docker in GitLab CI, specify a Docker-enabled runner and use the docker service in your .gitlab-ci.yml. Then run Docker commands inside your job script to build or run containers.

Syntax

In GitLab CI, you define jobs in a .gitlab-ci.yml file. To use Docker, you specify a docker image for the job, enable the docker:dind (Docker-in-Docker) service, and run Docker commands in the script section.

Key parts:

• image: The Docker image used to run the job.
• services: Additional containers like docker:dind to enable Docker commands.
• variables: Environment variables to configure Docker, e.g., DOCKER_HOST.
• script: Commands to run, including Docker commands.

yaml

build_job:
  image: docker:20.10.16
  services:
    - docker:20.10.16-dind
  variables:
    DOCKER_HOST: tcp://docker:2375
    DOCKER_TLS_CERTDIR: ""
  script:
    - docker info
    - docker build -t my-image .
    - docker run my-image

Example

This example shows a GitLab CI job that builds a Docker image from a Dockerfile and runs it. It uses the docker:dind service to allow Docker commands inside the job.

yaml

build_and_run:
  image: docker:20.10.16
  services:
    - docker:20.10.16-dind
  variables:
    DOCKER_HOST: tcp://docker:2375
    DOCKER_TLS_CERTDIR: ""
  script:
    - echo "Building Docker image..."
    - docker build -t hello-world .
    - echo "Running Docker container..."
    - docker run --rm hello-world

Output

Building Docker image...
Sending build context to Docker daemon  2.048kB
Step 1/2 : FROM alpine
 ---> a24bb4013296
Step 2/2 : CMD ["echo", "Hello from Docker in GitLab CI!"]
 ---> Running in 123abc456def
Removing intermediate container 123abc456def
Successfully built abcdef123456
Successfully tagged hello-world:latest
Running Docker container...
Hello from Docker in GitLab CI!

Common Pitfalls

Common mistakes when using Docker in GitLab CI include:

• Not enabling the docker:dind service, so Docker commands fail.
• Missing DOCKER_HOST variable, causing connection errors.
• Using the latest tag for Docker images, which can cause unpredictable builds.
• Running Docker commands without proper permissions or on runners not configured for Docker.

Always specify exact Docker versions and configure variables correctly.

yaml

wrong_job:
  image: docker:latest
  script:
    - docker build -t my-image .

correct_job:
  image: docker:20.10.16
  services:
    - docker:20.10.16-dind
  variables:
    DOCKER_HOST: tcp://docker:2375
    DOCKER_TLS_CERTDIR: ""
  script:
    - docker build -t my-image .

Quick Reference

Tips for using Docker in GitLab CI:

• Use docker:dind service to enable Docker commands.
• Set DOCKER_HOST to tcp://docker:2375 and disable TLS with DOCKER_TLS_CERTDIR="".
• Use specific Docker image versions, not latest.
• Run Docker commands inside the script section.
• Ensure your GitLab runner supports Docker and is configured properly.

Key Takeaways

Enable the docker:dind service and set DOCKER_HOST to run Docker commands in GitLab CI.

Use specific Docker image versions to avoid unpredictable builds.

Run Docker commands inside the script section of your .gitlab-ci.yml job.

Ensure your GitLab runner supports Docker and is configured for Docker-in-Docker.

Avoid using the latest tag and disable TLS for Docker-in-Docker with DOCKER_TLS_CERTDIR="".