Docker agent in Jenkinsfile - Commands & Configuration

Introduction

Sometimes you want your Jenkins build to run inside a Docker container. This helps keep your build environment clean and consistent. Using a Docker agent in a Jenkinsfile lets Jenkins run your build steps inside a Docker container automatically.

When you want to run your build in a specific environment without installing tools on the Jenkins server.

When you need to isolate builds to avoid conflicts between different projects.

When you want to use the same environment locally and in Jenkins for consistency.

When your build requires software that is only available inside a Docker image.

When you want to easily update or change the build environment by switching Docker images.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
  agent {
    docker {
      image 'maven:3.8.5-jdk-11'
      args '-v /root/.m2:/root/.m2'
    }
  }
  stages {
    stage('Build') {
      steps {
        sh 'mvn clean package'
      }
    }
  }
}

This Jenkinsfile defines a pipeline that uses a Docker agent.

agent docker: tells Jenkins to run the build inside a Docker container.

image: specifies the Docker image to use, here a Maven image with JDK 11.

args: passes extra options to Docker, here mounting the Maven cache to speed up builds.

stages: defines the build steps, here running Maven to build the project.

Commands

Check that Jenkins Job Builder or Jenkins CLI is installed to interact with Jenkins pipelines.

Terminal

jenkins-jobs --version

Expected Output

1.0.0

Download the Docker image that will be used as the build environment in Jenkins.

Terminal

docker pull maven:3.8.5-jdk-11

Expected Output

3.8.5-jdk-11: Pulling from library/maven

Digest: sha256:abc123def456...

Status: Downloaded newer image for maven:3.8.5-jdk-11

Trigger the Jenkins pipeline that uses the Docker agent to run the build inside the Docker container.

Terminal

jenkins-cli build example-pipeline

Expected Output

[Pipeline] Start of Pipeline

[Pipeline] node

Running on Jenkins in /var/jenkins_home/workspace/example-pipeline

[Pipeline] { (agent)

[Pipeline] docker

Using Docker image maven:3.8.5-jdk-11

[Pipeline] sh

+ mvn clean package

[INFO] Scanning for projects...

[INFO] BUILD SUCCESS

[Pipeline] }

[Pipeline] End of Pipeline

Verify that no leftover Docker containers from the Jenkins build are running, ensuring clean environment.

Terminal

docker ps

Expected Output

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

Key Concept

If you remember nothing else from this pattern, remember: using a Docker agent in Jenkinsfile runs your build inside a clean, consistent Docker container automatically.

Common Mistakes

Not specifying the Docker image in the Jenkinsfile agent section.

Jenkins won't know which Docker container to use and the build will fail.

Always specify a valid Docker image under agent { docker { image 'your-image' } }.

Forgetting to mount necessary volumes like caches or credentials.

Builds may be slower or fail because they can't access required files or caches.

Use the args option to mount volumes, for example '-v /root/.m2:/root/.m2' for Maven cache.

Running commands that require tools not present in the Docker image.

The build will fail because the tools are missing inside the container.

Choose or build a Docker image that includes all required tools for your build.

Summary

Define a Docker agent in Jenkinsfile to run builds inside a Docker container.

Specify the Docker image and optional arguments like volume mounts.

Run build commands inside the container for a clean and consistent environment.