Skip to main content
In this lesson you’ll learn how to build a custom Docker image from a Dockerfile and run a Jenkins pipeline stage inside a container created from that image using the dockerfile agent. This approach is useful when the base image from Docker Hub lacks command-line tools or libraries required by your pipeline steps. Problem overview
  • The example uses node:18-alpine as the agent image, which includes Node and npm but does not include the cowsay CLI.
  • Running cowsay in that container fails because the binary is missing.
Reproducing the failure Below is the initial declarative pipeline stage that attempts to use node:18-alpine as an agent and run node, npm, and cowsay inside the container:
Example console output (excerpt):
Cause
  • The node:18-alpine image includes Node.js and npm but not the cowsay package, so invoking cowsay fails.
  • To fix this, create a custom image that extends node:18-alpine and installs the missing CLI(s).
Create a custom Dockerfile Create a file (for example Dockerfile.cowsay) in your repository workspace with the following contents. Because the base image uses Alpine Linux, use apk to install required packages, then clone and install cowsay from its GitHub repo:
Switch the pipeline to the dockerfile agent Update the pipeline stage to use the dockerfile agent so Jenkins will build the image from the Dockerfile in the workspace and run the stage inside a container created from that image.
Note: This is dockerfile (not docker). The dockerfile agent builds the image from the specified Dockerfile in the workspace, then runs your steps inside a container created from that image.
Corrected pipeline stage (using Dockerfile.cowsay):
What Jenkins will do when this runs
  • Read Dockerfile.cowsay from the workspace.
  • Build a Docker image (you’ll see a docker build -t ... -f Dockerfile.cowsay . invocation in the logs).
  • Start a container from the built image and run your sh steps inside it.
Build log excerpt showing the image build and install step:
After successful build and run, cowsay executes as expected. Example final output:
Quick reference table Troubleshooting and important notes
Warning: The Jenkins node that builds the Docker image must have Docker (or a compatible container runtime) available and properly configured for the Jenkins user. If Docker is not accessible from the agent, the docker build step will fail. Ensure the agent has permission to run Docker (or use a dedicated Docker-in-Docker or privileged agent).
  • If builds are slow, consider pushing a pre-built image to a registry and using agent { docker { image 'your-registry/your-image:tag' } } in production.
  • For complex images, include a small changelog or versioning tag in the Dockerfile to help with caching and reproducible builds.
  • Monitor Jenkins logs to confirm the docker build and container start steps.
Summary
  • Use a Dockerfile when the base image lacks required CLI tools or libraries.
  • Add the Dockerfile to your repository workspace (e.g., Dockerfile.cowsay).
  • Configure the declarative pipeline with agent { dockerfile { filename 'Dockerfile.cowsay' } }.
  • Verify Jenkins build logs show docker build and that cowsay (or other tools) run successfully inside the container.
Links and references

Watch Video