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.

Practice

1. What is the main purpose of using a docker agent in a Jenkinsfile?

easy

A. To speed up the Jenkins UI loading time

B. To run the build inside a container for a consistent environment

C. To deploy the application automatically after build

D. To backup Jenkins configuration files

Solution

1. Step 1: Understand what a Docker agent does in Jenkins

   A Docker agent runs the build steps inside a Docker container, ensuring the environment is consistent and isolated.

2. Step 2: Compare options with this purpose

   Only To run the build inside a container for a consistent environment describes running builds inside containers for consistency. Other options describe unrelated tasks.

3. Final Answer:

   To run the build inside a container for a consistent environment -> Option B

4. Quick Check:

   Docker agent purpose = consistent build environment [OK]

Hint: Docker agent means build runs inside container [OK]

Common Mistakes:

• Confusing Docker agent with deployment step
• Thinking Docker agent speeds up UI
• Assuming Docker agent manages backups

2. Which of the following is the correct syntax to specify a Docker agent in a Jenkinsfile?

easy

A. agent { docker image 'node:14' }

B. agent docker image: 'node:14'

C. agent docker { 'node:14' }

D. agent { docker { image 'node:14' } }

Solution

1. Step 1: Recall Jenkinsfile Docker agent syntax

   The correct syntax uses a block: agent { docker { image 'node:14' } }.

2. Step 2: Check each option

   agent { docker { image 'node:14' } } matches the correct block syntax. Options A, B, and D have syntax errors or missing braces.

3. Final Answer:

   agent { docker { image 'node:14' } } -> Option D

4. Quick Check:

   Correct Docker agent syntax = agent { docker { image 'node:14' } } [OK]

Hint: Docker agent uses nested braces with image key [OK]

Common Mistakes:

• Omitting braces around docker block
• Using colon instead of braces
• Placing image outside docker block

3. Given this Jenkinsfile snippet:

pipeline {
  agent {
    docker {
      image 'python:3.12'
      args '-v /tmp:/tmp'
    }
  }
  stages {
    stage('Test') {
      steps {
        sh 'python --version'
      }
    }
  }
}

What will be the output of the sh 'python --version' command?

medium

A. Python 3.12.x

B. Python 2.7.x

C. Command not found error

D. Python 3.8.x

Solution

1. Step 1: Identify the Docker image used

   The image specified is 'python:3.12', which contains Python version 3.12.

2. Step 2: Understand the command inside the container

   The command python --version runs inside the container, so it will output the Python version installed in that image, which is 3.12.x.

3. Final Answer:

   Python 3.12.x -> Option A

4. Quick Check:

   Docker image version matches command output [OK]

Hint: Output matches Docker image Python version [OK]

Common Mistakes:

• Assuming host Python version is used
• Confusing image tag with Python version
• Expecting command not found error

4. You wrote this Jenkinsfile snippet:

pipeline {
  agent {
    docker {
      image 'ubuntu'
      args '-it'
    }
  }
  stages {
    stage('Build') {
      steps {
        sh 'echo Hello'
      }
    }
  }
}

But the build fails with error: docker: Error response from daemon: the input device is not a TTY. What is the best fix?

medium

A. Change image to ubuntu:latest

B. Add tty true to the docker agent block

C. Remove the -it argument from args

D. Replace sh with bat

Solution

1. Step 1: Understand the error message

   The error says the input device is not a TTY, caused by using -it (interactive + tty) in a non-interactive Jenkins build.

2. Step 2: Fix the Docker args

   Removing -it from args avoids requesting a TTY, fixing the error.

3. Final Answer:

   Remove the -it argument from args -> Option C

4. Quick Check:

   Remove interactive TTY args in Jenkins Docker agent [OK]

Hint: Avoid -it args in Jenkins Docker agents [OK]

Common Mistakes:

• Adding tty true without removing -it
• Changing image without fixing args
• Using Windows bat step on Linux agent

5. You want to run a Jenkins pipeline using a Docker agent with the image maven:3.8.6-jdk-17 and mount the host directory /var/maven-repo to /root/.m2/repository inside the container. Which Jenkinsfile snippet correctly sets this up?

hard

A. agent { docker { image 'maven:3.8.6-jdk-17' args '-v /var/maven-repo:/root/.m2/repository' } }

B. agent { docker { image 'maven:3.8.6-jdk-17' args '-v /root/.m2/repository:/var/maven-repo' } }

C. agent { docker { image 'maven:3.8.6-jdk-17' args '-v /var/maven-repo' } }

D. agent { docker { image 'maven:3.8.6-jdk-17' args '--mount source=/var/maven-repo,target=/root/.m2/repository' } }

Solution

1. Step 1: Understand Docker volume mount syntax

   The syntax to mount a host directory to a container path is -v host_path:container_path.

2. Step 2: Match the mount paths correctly

   The host directory /var/maven-repo should be mounted to /root/.m2/repository inside the container, so the args must be -v /var/maven-repo:/root/.m2/repository.

3. Step 3: Check options

   agent { docker { image 'maven:3.8.6-jdk-17' args '-v /var/maven-repo:/root/.m2/repository' } } matches the correct syntax and paths. agent { docker { image 'maven:3.8.6-jdk-17' args '-v /root/.m2/repository:/var/maven-repo' } } reverses paths. agent { docker { image 'maven:3.8.6-jdk-17' args '-v /var/maven-repo' } } misses container path. agent { docker { image 'maven:3.8.6-jdk-17' args '--mount source=/var/maven-repo,target=/root/.m2/repository' } } uses incorrect mount syntax for Docker CLI.

4. Final Answer:

   agent { docker { image 'maven:3.8.6-jdk-17' args '-v /var/maven-repo:/root/.m2/repository' } } -> Option A

5. Quick Check:

   Correct volume mount syntax = agent { docker { image 'maven:3.8.6-jdk-17' args '-v /var/maven-repo:/root/.m2/repository' } } [OK]

Hint: Use -v host:container for volume mounts in Docker args [OK]

Common Mistakes:

• Reversing host and container paths
• Omitting container path in volume mount
• Using --mount instead of -v in args