Revamping Jenkins Tutorials: A Journey to Simplicity and Inclusivity

Bruno Verachten October 25, 2024

Introduction: Transforming Jenkins tutorials

Technical tutorials often present challenges to developers, particularly when learning complex systems like Jenkins. The existing Jenkins tutorials, while comprehensive, had become a significant barrier to entry for many developers, especially those new to continuous integration and deployment.

During the Open Source Summit Europe 2024, the Continuous Delivery Foundation (CDF) organized a mini summit. The CFP committee accepted our presentation on the Jenkins tutorials modernization project, which was completed during Google Summer of Code 2023. This initiative was presented alongside other valuable contributions from various CDF projects. We are grateful to the CDF for providing this platform to share our work.

This blog post accompanies that presentation and details our systematic approach to redesigning the Jenkins tutorials. We’ll examine how we transformed complex setup procedures into streamlined, accessible guides using modern tooling and best practices. The discussion will cover the challenges we encountered, the technical solutions we implemented, and the measurable improvements achieved through these changes.

The Problem: Old Jenkins tutorials

A visual comparison

Before we dive into the specifics, let’s take a visual journey through the old and new tutorial experiences:

Did you notice how much scrolling was required on the right side? It was like a never-ending story. And did you see the amount of code users had to copy-paste? While we’ll always need a certain quantity of code for the Jenkins pipeline itself, the setup process should be as simple as possible. That wasn’t the case with the old tutorials.

Breaking down the issues

Our old tutorials, while comprehensive, presented several significant challenges:

Overwhelming complexity: Users were bombarded with Docker commands before they could even start learning about Jenkins. The tutorial assumed users were Docker gurus, throwing commands at them like there’s no tomorrow.
Assumptions about user knowledge: The tutorials assumed a high level of Docker expertise. But let me ask you this: how many of you knew Docker really well the first time you tried Jenkins? That’s not a fair expectation.
Lengthy setup process: A significant portion of the tutorial was dedicated to setup rather than learning Jenkins itself. We were spending more time with Docker than with Jenkins!
Reliance on outdated tools: We were heavily dependent on the deprecated Blue Ocean plugin, which was no longer recommended.
Docker in Docker: The old tutorial used Docker in Docker, which is considered a bad practice from a security standpoint.
Lack of context: The tutorials often lacked explanations for why certain steps were necessary, leaving users to blindly follow instructions without understanding.

Here’s a snippet from the old Maven tutorial to illustrate these points:

docker network create jenkins
docker run \
  --name jenkins-docker \
  --rm \
  --detach \
  --privileged \
  --network jenkins \
  --network-alias docker \
  --env DOCKER_TLS_CERTDIR=/certs \
  --volume jenkins-docker-certs:/certs/client \
  --volume jenkins-data:/var/jenkins_home \
  --publish 2376:2376 \
  docker:dind \
  --storage-driver overlay2

This command, while functional, is overwhelming for beginners and lacks context. Why do we need a Docker network? Why are we running Docker in Docker? These questions were left unanswered.

The Solution: Revamping with Docker Compose

After much deliberation and feedback, we decided to leverage Docker Compose to simplify the entire setup process.

Why Docker Compose?

Docker Compose can encapsulate complex multi-container setups into a single, easy-to-understand file. It is the only tool that can handle the complexity of the Jenkins controller and agent setup while making it accessible to newcomers.

Here’s an example of how Docker Compose simplifies things:

services:
  jenkins:
    image: jenkins/jenkins:lts
    ports:
      - "8080:8080"
    volumes:
      - jenkins_home:/var/jenkins_home
  agent:
    image: jenkins/ssh-agent:jdk17
    environment:
      - JENKINS_AGENT_SSH_PUBKEY=<your_public_key>
volumes:
  jenkins_home:

With this setup, users can start Jenkins and an agent with a single command: docker compose up -d.

Key improvements

Simplified setup: Instead of a series of complex Docker commands, users can now get started with a single Docker Compose command.
Reduced assumptions: By encapsulating the setup in Docker Compose, we removed the need for extensive Docker knowledge.
Focus on Jenkins: With a streamlined setup, users can dive into learning Jenkins faster.
Modernized tools: We replaced outdated plugins like Blue Ocean with more current solutions.
Elimination of Docker in Docker: Our new setup avoids this security risk entirely.
Contextual guidance: We’ve added explanations for each step, helping users understand why they’re performing certain actions.

The Process: Collaboration and innovation

This revamp was a collaborative effort, with significant contributions from our Google Summer of Code participant, Ashutosh Saxena. His fresh perspective as a newcomer to Jenkins was invaluable in identifying pain points that we, as experienced developers, had overlooked.

Key innovations

Multi-architecture support: We ensured our Docker images work on both x86_64 and ARM64 architectures. This was a significant challenge that Ashutosh tackled using Docker’s buildx tool.
GitPod integration: We made Jenkins accessible directly from the browser, reducing hardware barriers to entry. This was particularly important for users with less powerful machines or those in environments with limited resources.
Docker Compose profiles: We introduced profiles for different languages and technologies, making it easy to switch between setups. For example, users can start a Maven-specific setup with docker compose --profile maven up -d.
Automated updates: We implemented automation to keep our Docker images up-to-date, using tools like Dependabot and UpdateCLI.

The Result: A More inclusive Jenkins

The outcome of our efforts is a Jenkins experience that’s more inclusive than ever. Let’s break down the key improvements:

1. Simplified setup

Users can now get Jenkins running with a single command. Here’s how straightforward it is:

Clone the repository: git clone https://github.com/jenkins-docs/quickstart-tutorials.git
Navigate to the directory: cd quickstart-tutorials
Start Jenkins: docker compose --profile <tutorial_name> up -d

That’s it! No more complex Docker commands or manual configuration.

2. Browser-based access with GitPod

Thanks to GitPod integration, Jenkins is now just a click away, even on less powerful devices. This cloud-based approach brings several key advantages for accessibility and ease of use:

*One-Click Setup*: The repository’s README contains a GitPod link that launches Jenkins instantly. With the GitPod Chrome extension installed, you’ll see a prominent green button that makes the process even smoother.
*Resource-Friendly*: GitPod provides 50 hours of free monthly usage, making Jenkins accessible to users regardless of their local hardware capabilities.
*Bandwidth Optimization*: Since GitPod handles the heavy lifting of downloading Docker images, users can get started quickly even with limited internet connectivity - whether they’re working from a train, a remote location, or a region with restricted bandwidth.
*Familiar Development Environment*: Users get instant access to a Visual Studio Code-like IDE and terminal, complete with clear instructions for their chosen tutorial.

Here’s a quick demonstration of the GitPod integration in action:

As you can see, users have some instructions and a command to copy-paste in the terminal.

After pasting the command in the terminal, the setup process begins automatically. Docker images are pulled efficiently through GitPod’s infrastructure, preserving your local bandwidth. The Jenkins controller and agent containers are launched, and a browser tab automatically opens to display the Jenkins interface. The entire process takes less than a minute - a significant improvement over traditional setup methods. Since we’ve streamlined the authentication process, you can log in immediately using the credentials (admin/admin) and begin your Jenkins journey.

Expanding the window reveals the full Jenkins interface. Upon logging in with the tutorial credentials (admin/admin), you’ll immediately notice several key features: a pre-configured job and an active agent visible in the left sidebar. This job, while simple, serves an important purpose — it demonstrates that both your Jenkins controller is operational and the agent is properly connected. Navigating to "`Manage Jenkins`" shows that all plugins are current, eliminating any need for initial administrative setup. The bottom right corner displays the current Jenkins LTS version (2.462.2 at the time of recording), confirming you’re working with the latest stable release. This streamlined environment allows users to focus entirely on learning Jenkins, without getting caught up in configuration details. The entire setup process, from start to finish, takes less than two minutes and requires no local installation — perfectly aligned with our goal of making Jenkins more accessible to everyone.

The GitPod terminal output illustrates another key innovation: our implementation of Docker Compose profiles for various programming languages and technologies. This feature exemplifies our commitment to simplicity — switching between different technology stacks, whether Maven, Python, or Node.js, requires only a single command: docker compose --profile maven up -d. The system handles all the complexity behind the scenes, delivering a seamless experience that lets developers focus on learning Jenkins rather than wrestling with configuration.

This streamlined approach reflects our broader commitment to inclusivity. Through multi-architecture support and browser-based accessibility via GitPod, we’ve created an environment where developers of all experience levels and technical resources can engage with Jenkins effectively.

3. Flexible configurations

Docker Compose profiles allow easy switching between different tech stacks. Whether you’re working with Maven, Python, or Node.js, you can start the appropriate environment with a simple profile switch.

4. Up-to-date and secure

By eliminating Docker in Docker and implementing automated updates, we’ve made the tutorials more secure and easier to maintain.

The Impact: Before and after

The impact of these changes has been significant and far-reaching:

Increased adoption: Our Docker images have been downloaded over 26,000 times since launch. We’ve seen multiple forks of the project, with people using it to create their own Jenkins instances for other technologies.
Educational benefits: University professors have incorporated these tutorials into their CI/CD curricula. One teacher reported that his students, most of whom had never used Jenkins before, were able to get up and running in minutes. The simplification helped them focus on learning Jenkins rather than fighting with the setup process.
Community engagement: We’ve seen regular clones and forks of the repository, indicating active use of our tutorials. Referrals come not just from jenkins.io, but also from Reddit, Medium, and Google searches.
Unexpected benefits: The new setup has even facilitated testing of major Jenkins upgrades. For example, it’s being used to test the ongoing migration to Spring Security 6.x and Spring Framework 6.x. This allows anyone to launch transitional versions of Jenkins with one command and provide valuable feedback on the progress.

The Future: Call to action

While we’ve made significant strides, our work is far from over. We’re constantly looking for ways to improve Jenkins, and that’s where you come in. Whether you’re a seasoned developer or a complete newcomer, your feedback and contributions are invaluable.

We encourage you to:

Try out the new tutorials.
Provide feedback on your experience.
Contribute ideas or code to further improve the tutorials.
Share your experience with the community.

Remember, Jenkins is a community-driven project. Your input shapes its future!

Upcoming improvements

We’re already planning the next phase of improvements:

Expanding the range of technology-specific profiles.
Further refining the GitPod experience.
Exploring integration with other cloud development environments.
Continuously updating our documentation to reflect best practices.

Conclusion

The Jenkins tutorials modernization project has significantly transformed the onboarding experience for new users. Through careful redesign and modern tooling, we’ve created a more accessible and efficient learning environment that accommodates developers across all experience levels.

The implementation of Docker Compose, GitPod integration, and comprehensive documentation has established a robust foundation for future Jenkins users. These improvements serve our core mission of making continuous integration and deployment accessible to all developers, regardless of their prior experience with DevOps tools.

We invite you to experience these improvements firsthand by exploring our updated tutorials. Your feedback and contributions will help shape the future of Jenkins documentation and training resources. For a detailed overview of this modernization effort, you can view the complete presentation from the CDF Summit here: presentation recording.

About the author

Bruno Verachten

Bruno is a father of two, husband of one, geek in denial, beekeeper, permie and a Developer Relations for the Jenkins project. He’s been tinkering with continuous integration and continuous deployment since 2013, with various products/tools/platforms (Gitlab CI, Circle CI, Travis CI, Shippable, Github Actions, …), mostly for mobile and embedded development.
He’s passionate about embedded platforms, the ARM&RISC-V ecosystems, and Edge Computing. His main goal is to add FOSS projects and platforms to the ARM&RISC-V architectures, so that they become as boring as X86_64.
He is also the creator of miniJen, the smallest multi-cpu architectures Jenkins instance known to mankind.