Configuring Docker-in-Docker and Jenkins Pipelines with Multi‑Stage Docker Agents

This guide explains how to configure Docker-in-Docker for a Jenkins master, mount Docker sockets, resolve permission issues, and define multi‑stage pipelines that run each stage in a specific Docker container.

First, run Jenkins in a container with Docker socket and binary mounted:

docker run --name jenkins -itd \
    -p 8081:8080 \
    -p 50000:50000 \
    -v ~/jenkins:/var/jenkins_home \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /usr/local/bin/docker:/usr/bin/docker \
    jenkins/jenkins:lts

Execute the container as root or add the jenkins user to the root group to avoid permission problems:

docker exec -it -u root jenkins bash
usermod -aG root jenkins
id jenkins

Example pipeline using a Maven Docker image:

pipeline {
    agent {
        docker {
            image 'maven:3.6.3-jdk-8'
            args '-v $HOME/.m2:/root/.m2'
        }
    }
    stages {
        stage('Build') {
            steps {
                sh 'mvn -v'
            }
        }
    }
}

Running logs show the pipeline executing inside the Docker container and completing successfully.

To run different stages in different containers, set agent none at the top and specify a Docker agent per stage, e.g., Maven for ServiceBuild and Node for WebBuild:

pipeline {
    agent none
    stages {
        stage('ServiceBuild') {
            agent {
                docker {
                    image 'maven:3.6.3-jdk-8'
                    args '-v $HOME/.m2:/root/.m2'
                }
            }
            steps {
                sh 'mvn -v && sleep 15'
            }
        }
        stage('WebBuild') {
            agent {
                docker {
                    image 'node:7-alpine'
                    args '-v $HOME/.m2:/root/.m2'
                }
            }
            steps {
                sh 'node -v && sleep 15'
            }
        }
    }
}

A front‑end pipeline example uses a Node image with root privileges and configures npm cache and registry to speed up builds:

pipeline {
    agent none
    stages {
        stage('WebBuild') {
            agent {
                docker {
                    image 'node:10.19.0-alpine'
                    args '-u 0:0 -v /var/jenkins_home/.npm:/root/.npm'
                }
            }
            steps {
                sh '''
                    id
                    ls /root/.npm
                    npm config set unsafe-perm=true
                    npm config set cache /root/.npm
                    npm config set registry https://registry.npm.taobao.org
                    npm install --unsafe-perm=true && npm run build && ls -l dist/ && sleep 15
                '''
            }
        }
    }
}

FAQ notes that building with npm may require root access, mounting a cache volume, and setting the Taobao registry to improve speed.