Working with Docker in Pipelines

1. Using Docker Agent

Property	Values	Description
agent	`docker`	Specifies that the pipeline should run inside a Docker container
agent.docker.image	`node:18-alpine`	The Docker image to use for the agent container
agent.docker.registryUrl	`https://my-registry.com`	URL of the Docker registry to pull the image from
agent.docker.credentialsId	`my-docker-credentials`	Credentials ID for accessing private Docker registries
agent.docker.args	`--network my-network`	Additional arguments to pass to the Docker run command

Example: Basic Docker Agent Usage

pipeline {
    agent {
        docker {
            image 'node:18-alpine'
        }
    }
    stages {
        stage('Build') {
            steps {
                sh 'node --version'
            }
        }
    }
}

Example: Docker Agent with Custom Registry

pipeline {
    agent {
        docker {
            image 'myapp:latest'
            registryUrl 'https://my-private-registry.com'
            credentialsId 'docker-credentials'
        }
    }
    stages {
        stage('Test') {
            steps {
                sh 'npm test'
            }
        }
    }
}

Note: Ensure that the Docker image specified has the necessary tools (e.g., Node.js, npm) installed to execute your pipeline steps.

2. Building Docker Images

Property	Description	Example
docker.build()	Builds a Docker image from a Dockerfile	`docker.build("myapp")`
docker.build(imageName, dockerfile)	Builds a Docker image with custom Dockerfile path	`docker.build("myapp", "./Dockerfile.prod")`
docker.build(imageName, dockerfile, args)	Builds a Docker image with build arguments	`docker.build("myapp", "./Dockerfile", ['ARG1=value1'])`

Example: Building a Docker Image

pipeline {
    agent any
    stages {
        stage(&#x27;Build Docker Image&#x27;) {
            steps {
                script {
                    docker.build("myapp", "./Dockerfile")
                }
            }
        }
    }
}

Example: Building with Build Arguments

pipeline {
    agent any
    stages {
        stage(&#x27;Build Docker Image with Args&#x27;) {
            steps {
                script {
                    docker.build("myapp", "./Dockerfile", [&#x27;VERSION=1.0&#x27;, &#x27;ENV=prod&#x27;])
                }
            }
        }
    }
}

3. Running Docker Containers

Property	Description	Example
docker.run()	Runs a Docker container with specified options	`docker.run(image: 'nginx', name: 'my-nginx')`
docker.image()	Defines a Docker image to use in the pipeline	`def nginxImage = docker.image('nginx')`

Example: Running a Docker Container

pipeline {
    agent any
    stages {
        stage('Run Docker') {
            steps {
                script {
                    docker.run('nginx:latest', '--name my-nginx -d') {
                        sh 'curl http://localhost'
                    }
                }
            }
        }
    }
}

Example: Using Docker Image in Pipeline

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                script {
                    def customImage = docker.image('myapp:latest')
                    customImage.run('-d --name my-app')
                }
            }
        }
    }
}

Note: Ensure Docker daemon is running on the Jenkins agent where this pipeline executes.

4. Pushing Images to Registry

Property	Description	Example
docker.image.name	Name of the Docker image to be pushed	`"myapp:latest"`
docker.image.registry	Registry URL to push the image to	`"https://my-registry.com/v2/"`
docker.image.tag	Tag to apply to the image before pushing	`"v1.0.0"`

Example: Pushing Docker Image to Registry

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh 'docker build -t myapp:latest .'
            }
        }
        stage('Push') {
            steps {
                script {
                    docker.withRegistry('https://my-registry.com/v2/', 'docker-credentials') {
                        def image = docker.image('myapp:latest')
                        image.push()
                    }
                }
            }
        }
    }
}

Note: Ensure that the Jenkins agent has Docker CLI installed and configured to access the registry.

5. Using Docker Compose

Option	Values	Description
docker.compose.file	`docker-compose.yml`	Path to the Docker Compose file
docker.compose.projectName	`jenkins-pipeline`	Name of the Docker Compose project
docker.compose.service	`app`	Name of the service to run

Example: Running a service with Docker Compose

pipeline {
    agent any
    stages {
        stage('Run with Docker Compose') {
            steps {
                script {
                    docker.compose.file = 'docker-compose.yml'
                    docker.compose.projectName = 'myapp'
                    docker.compose.service = 'web'
                    docker.compose.run()
                }
            }
        }
    }
}

Note: Ensure the docker-compose.yml file is present in the workspace.

Warning: The Docker Compose plugin must be installed in Jenkins.

Key Features

Supports multi-container applications
Enables easy orchestration of services
Integrates with Jenkins Pipeline DSL

6. Using Multi-Stage Docker Builds

Multi-stage Docker builds in Jenkins pipelines allow you to optimize your Docker images by using multiple build stages, each with a specific purpose. This approach helps reduce the final image size and improves security by minimizing the attack surface.

Stage	Description	Use Case
FROM builder	Builds the application with all dependencies	Compiling code, installing build tools
FROM runtime	Copies only necessary artifacts from the builder stage	Running the application with minimal dependencies

Example: Multi-Stage Docker Build in Jenkins Pipeline

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                script {
                    docker.build("myapp", "Dockerfile")
                }
            }
        }
    }
}

Note: Ensure that your Dockerfile uses multi-stage builds to optimize image size and security.

Key Benefits of Multi-Stage Builds

Reduced image size by excluding build-time dependencies
Improved security through minimized attack surface
Better separation of concerns between build and runtime environments

7. Configuring Docker Registry Credentials

Property	Value	Description
docker.registry.credentials.id	`my-registry-credentials`	ID of the credentials defined in Jenkins Credentials Store
docker.registry.credentials.username	`my-username`	Username for Docker registry authentication
docker.registry.credentials.password	`my-password`	Password or token for Docker registry authentication

Example: Using Docker Registry Credentials in Pipeline

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                script {
                    withCredentials([usernamePassword(credentialsId: 'my-registry-credentials', 
                                                      usernameVariable: 'DOCKER_USER', 
                                                      passwordVariable: 'DOCKER_PASS')]) {
                        sh "docker login -u $DOCKER_USER -p $DOCKER_PASS"
                    }
                }
            }
        }
    }
}

8. Using Docker Volume Mounts

Option	Values	Description
mounts	`string[]`	List of volume mounts to be used in the container

Example: Mounting a Volume in Jenkins Pipeline

pipeline {
    agent {
        docker {
            image 'node:18'
            args '-v /host/path:/container/path'
        }
    }
    stages {
        stage('Build') {
            steps {
                sh 'ls -l /container/path'
            }
        }
    }
}

Note: The -v flag in Docker must be specified as part of the args property when using the docker agent in Jenkins pipelines.

Warning: Ensure that the host directory exists and has appropriate permissions to avoid runtime errors.

9. Cleaning Docker Resources

Resource Type	Clean Command	Notes
Docker Images	`docker rmi $(docker images -q)`	Removes all dangling and unused images
Docker Containers	`docker rm $(docker ps -aq --no-trunc)`	Removes all stopped containers
Docker Volumes	`docker volume prune`	Removes all unused volumes
Docker Networks	`docker network prune`	Removes all unused networks
Docker System	`docker system prune -a`	Removes all unused images, containers, networks, and volumes

Example: Cleaning Docker Resources in Jenkins Pipeline

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh '''docker build -t myapp .'''
            }
        }
        stage('Test') {
            steps {
                sh '''docker run myapp'''
            }
        }
    }
    post {
        always {
            sh '''docker system prune -f'''
        }
    }
}

Note: Use docker system prune -a -f with caution as it removes all unused Docker resources. Ensure that no other processes are using the containers or images.

10. Using Docker Network Options

Option	Description	Default	Notes
docker.network	Network mode to use for the container	`bridge`	Can be `bridge`, `host`, `none`, or custom network name
docker.networkOptions	Additional options to pass to the Docker network command	`null`	Used for custom network creation or configuration

Example: Using Custom Docker Network

pipeline {
    agent {
        docker {
            image 'node:18-alpine'
            network 'custom-network'
        }
    }
    stages {
        stage('Build') {
            steps {
                sh 'echo "Running in custom network"'
            }
        }
    }
}

Note: The custom network must already exist in Docker or be created separately before running the pipeline.