Day 3: Jenkins Basics — What It Is, How to Install, Docker Demo & Freestyle Job

This chapter covers the core concepts of Jenkins, its role as a CI/CD orchestrator, and how it integrates with modern software delivery tools. We will compare various enterprise deployment strategies, walk through a hands-on installation using Docker, build a Freestyle job, explore built-in environment variables, and configure global tools like Maven.

1. What is Jenkins? The Core Mental Model

At its core, Jenkins is an open-source, community-driven automation server. It sits under the umbrella of the Continuous Delivery Foundation (CDF), much like Kubernetes resides under the Cloud Native Computing Foundation (CNCF).

The CI/CD Orchestrator

A common misconception is that Jenkins replaces your existing development, testing, and deployment tools. It does not. Instead, Jenkins acts as an orchestrator that connects all the disparate tools in your software delivery lifecycle.

Real-Life Analogy: The Chief Engineer

Imagine a complex engineering project. You have an infrastructure architect, a DevOps architect, and an application architect. Each is a specialist using specialized tools.

To deliver a cohesive, end-to-end solution, you need a Chief Engineer who does not do everyone's job but instead connects all the dots, coordinates the handoffs, and ensures the workflow moves smoothly from one stage to the next. Jenkins is that Chief Engineer.

2. Key Architectural Pillars of Jenkins

To understand why Jenkins remains an industry standard, we must look at its core design pillars:

• Pipelines as Code: Instead of manually configuring jobs via a graphical user interface (GUI), Jenkins allows you to define your entire build, test, and deployment workflow in a text file called a Jenkinsfile. Because this file is written in code, it can be checked into a version control system (like Git). This provides auditability, peer review (PR) workflows, and a clear history of how your pipeline has evolved over time.
• Rich Plugin Ecosystem: Jenkins itself is a lightweight engine. Its power comes from thousands of community-contributed plugins. If you need to push a container image to AWS Elastic Container Registry (ECR), pull secrets from HashiCorp Vault, or send a notification to Slack, there is a plugin available to handle the integration.
• Git Workflow Friendly: Jenkins integrates seamlessly with Git hosts (GitHub, GitLab, Bitbucket). By configuring webhooks, any developer action—such as pushing code or opening a Pull Request (PR)—can automatically trigger a Jenkins pipeline run.
• Flexible Secrets Management: Jenkins includes a built-in credentials store to securely save SSH keys, API tokens, and passwords. In enterprise environments, it can also integrate directly with external secrets managers like HashiCorp Vault or AWS Secrets Manager.

3. Controller-Agent Architecture

Jenkins scales using a distributed Controller-Agent architecture. This separates administrative tasks from actual workload execution.

Control Plane vs. Data Plane

• The Controller (Control Plane): This is the brain of your Jenkins installation. It hosts the web UI, stores configuration settings, manages credentials, schedules builds, and instructs agents on what tasks to perform. No heavy build jobs should run on the controller.
• The Agents (Data Plane): These are lightweight service instances that receive instructions from the controller. They execute the actual shell commands, compile code, build Docker images, and run tests. Agents can be statically provisioned (VMs) or dynamically spun up on demand (Kubernetes pods).

4. Jenkins Installation Options: Comparative Analysis

When planning a Jenkins deployment, you must match your infrastructure strategy to your organizational needs.

Enterprise Best Practice: If you run Jenkins in a production environment, always secure enterprise-level support (such as CloudBees) rather than relying solely on open-source community forums. If your deployment pipeline breaks, you need guaranteed Service Level Agreements (SLAs) to minimize downtime.

5. Step-by-Step Hands-on: Deploying Jenkins via Docker

For local development and learning, running Jenkins inside a Docker container is the most efficient approach.

Step 1: Run the Jenkins Container

Execute the following command in your terminal to start a Long-Term Support (LTS) version of Jenkins:

docker run -d \
  --name jenkins \
  --restart unless-stopped \
  -p 8080:8080 \
  -p 50000:50000 \
  -v jenkins_home:/var/jenkins_home \
  -e TZ=Asia/Kolkata \
  jenkins/jenkins:lts

Detailed Parameter Breakdown:

• -d: Runs the container in detached mode (in the background).
• --name jenkins: Assigns a friendly name to the container.
• --restart unless-stopped: Ensures the container automatically restarts if the Docker daemon restarts, unless you manually stopped it.
• -p 8080:8080: Maps port 8080 of your host machine to port 8080 of the container. This is the port used to access the web UI.
• -p 50000:50000: Maps port 50000 of the host to port 50000 of the container. This port is used by inbound Jenkins agents to communicate with the controller.
• -v jenkins_home:/var/jenkins_home: Mounts a named Docker volume called jenkins_home to /var/jenkins_home inside the container. This directory stores all jobs, configurations, and plugins. This volume must be backed up regularly.
• -e TZ=Asia/Kolkata: Sets the container's timezone environment variable so that build logs display timestamps matching your local time.
• jenkins/jenkins:lts: Specifies the official Jenkins LTS image from Docker Hub.

6. Initial Jenkins Setup & Plugin Ecosystem

Once the container is running, navigate to http://localhost:8080 in your browser.

Step 1: Retrieve the Administrator Password

To unlock the console, you must retrieve the auto-generated password from inside the container.

1. Access the container's shell:
   BASH

   Copy

   docker exec -it jenkins bash
   

2. Read the password file:
   BASH

   Copy

   cat /var/jenkins_home/secrets/initialAdminPassword
   

3. Copy the output string, paste it into the Jenkins UI, and click Continue.

Step 2: Install Suggested Plugins

Select Install suggested plugins. Jenkins will automatically install a curated set of essential plugins:

• Folders: Allows organizing jobs into hierarchical directories.
• Build Timeout: Aborts builds that run longer than a specified time limit to prevent hung processes from consuming resources.
• Timestamper: Adds timestamps to console output logs.
• Workspace Cleanup: Deletes temporary files after a build completes to save disk space.
• Git: Enables checking out source code from Git repositories.
• Pipeline: Enables the core Jenkins Pipeline engine.
• Dark Theme: Provides a dark user interface.

Step 3: Create the Admin User & Set URL

1. Fill in the administrator details (Username, Password, Full Name, and Email).
2. Confirm the Jenkins URL (defaults to http://localhost:8080).
3. Click Save and Finish, then click Start using Jenkins.

Tip: To enable the dark theme immediately, click on your username in the top-right corner, select Appearance, choose Dark, and click Apply.

7. Creating Your First Freestyle Job

A Freestyle Job is a legacy, GUI-configured job type in Jenkins. While modern pipelines use code-based Jenkinsfiles, Freestyle jobs are excellent for running quick commands, testing scripts, and understanding Jenkins basics.

Step-by-Step Configuration

1. On the Jenkins home screen, click New Item.
2. Enter the name intro-freestyle, select Freestyle project, and click OK.
3. Scroll down to the Build Steps section.
4. Click Add build step and select Execute shell.
5. In the text area, enter a command to inspect the operating system of the host running the build:
   BASH

   Copy

   cat /etc/os-release
   

6. Click Save.

Running the Build

1. On the job dashboard, click Build Now in the left-hand menu.
2. Under Build History, click on build #1.
3. Select Console Output to view the execution logs.

Started by user Admin
Running as SYSTEM
Building in workspace /var/jenkins_home/workspace/intro-freestyle
[intro-freestyle] $ /bin/sh -xe /tmp/jenkins1234567890.sh
+ cat /etc/os-release
PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
NAME="Debian GNU/Linux"
...
Finished: SUCCESS

Interactive vs. Non-Interactive Shells

It is important to understand the difference between running commands inside your terminal versus running them inside a Jenkins build step:

• Interactive Shell (Your Terminal): When you run docker exec -it jenkins bash, you are working in an interactive shell running in the container's default working directory (usually /var/jenkins_home).
• Non-Interactive Shell (Jenkins Build Step): When Jenkins executes a shell build step, it spins up a non-interactive shell inside a dedicated directory called the Workspace (e.g., /var/jenkins_home/workspace/intro-freestyle).

8. Understanding Jenkins Environment Variables & Traceability

Jenkins automatically injects a set of environment variables into every running build step. These variables are critical for script logic, tagging artifacts, and traceability.

Common Built-In Variables

• BUILD_NUMBER: The current build number (e.g., 1, 2, 3).
• BUILD_ID: Equivalent to the build number in newer Jenkins releases.
• JOB_NAME: The name of the project (e.g., intro-freestyle).
• WORKSPACE: The absolute path of the directory allocated for the build.
• NODE_NAME: The name of the agent node where the build is running (e.g., built-in).

Hands-on: Using Environment Variables in a Job

Let's modify our Freestyle job to use these variables to output a build report.

1. Navigate to your intro-freestyle job and click Configure.
2. Replace the existing shell script with the following:
   BASH

   Copy

   echo "=== BUILD METADATA ==="
   echo "Workspace Path: $WORKSPACE"
   echo "Job Name:       $JOB_NAME"
   echo "Build Number:   $BUILD_NUMBER"
   echo "Running on Node: $NODE_NAME"
   echo "======================"
   
   # Generate a report file inside the workspace
   echo "Report for build $BUILD_NUMBER" > build-report.txt
   

3. Click Save and then Build Now.
4. Open the Console Output for the new build to see the populated values:

Verifying the Workspace File

To verify that the file build-report.txt was created in the workspace, you can check the container's file system directly from your terminal:

# Access the container
docker exec -it jenkins bash

# Navigate to the job's workspace
cd /var/jenkins_home/workspace/intro-freestyle

# List files and view content
ls -la
cat build-report.txt

Output:

Report for build 4

9. Global Tool Configuration: Managing Maven Versions

In software development, different projects often require different versions of build tools (e.g., Maven 3.6 vs. Maven 3.9). Jenkins provides a Global Tool Configuration engine to manage these tools automatically.

The Problem: Missing Tools

If you attempt to run a Maven command in a standard Jenkins container without installing it first, the build will fail:

# Inside an Execute Shell build step
mvn --version

This returns:

/tmp/jenkins12345.sh: line 2: mvn: command not found

The Solution: Jenkins Managed Tools

Instead of manually installing Maven inside the container using package managers like apt (which locks you into a single version), you can let Jenkins manage multiple versions dynamically.

Step 1: Configure Maven in Global Tools

1. Go to the Jenkins home page, click Manage Jenkins, and select Tools.
2. Scroll down to the Maven section and click Add Maven.
3. Configure the tool:
   • Name: Maven-3.9.1 (Choose a descriptive name).
   • Install automatically: Check this box.
   • Version: Select 3.9.1 (or your preferred version) from the Apache dropdown menu.
4. Click Apply and Save.

Step 2: Use the Configured Tool in a Job

1. Go to your intro-freestyle job and click Configure.
2. Scroll down to Build Steps.
3. Click Add build step and select Invoke top-level Maven targets.
4. In the Maven Version dropdown, select the tool you just configured (Maven-3.9.1).
5. In the Goals field, enter:
   TEXT

   Copy

   --version
   

6. Click Save and click Build Now.

On the first run, Jenkins will download the specified Maven version from Apache's servers, extract it into the Jenkins home directory, and execute the command.

Unpacking https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.1/apache-maven-3.9.1-bin.zip to /var/jenkins_home/tools/hudson.tasks.Maven_MavenInstallation/Maven-3.9.1 on built-in
[intro-freestyle] $ /var/jenkins_home/tools/hudson.tasks.Maven_MavenInstallation/Maven-3.9.1/bin/mvn --version
Apache Maven 3.9.1 (2e178502fcdccd75013078574410d3aac9948397)
Maven home: /var/jenkins_home/tools/hudson.tasks.Maven_MavenInstallation/Maven-3.9.1
Java version: 17.0.6, vendor: Eclipse Adoptium
...
Finished: SUCCESS

Comparing Tool Installation Methods

10. Jenkins Roles, Responsibilities & Enterprise Best Practices

In a production environment, clear boundaries must be established between who manages the automation infrastructure and who uses it.

1. The Jenkins Administrator (Platform/DevOps Team)

• Responsibilities: System uptime, OS patching, plugin updates, security configurations, and backup management.
• Key Task: Ensuring that the /var/jenkins_home directory is backed up to persistent block storage (like AWS EBS) or network file systems (like AWS EFS).

2. The Job/Pipeline Owners (Developers, QA, DevOps)

• Responsibilities: Writing Jenkinsfiles, configuring build triggers, running test suites, and managing deployment logic.
• Key Task: Ensuring that pipelines are optimized, secure, and do not run indefinitely by configuring appropriate timeouts.

Summary and Key Takeaways

• Jenkins is an orchestrator, not a replacement for specialized tools like Git, Docker, Maven, or Helm. It acts as the central coordinator for your entire CI/CD workflow.
• Pipelines as Code (using a Jenkinsfile) is the industry standard for defining build steps, enabling version control and auditability.
• The Controller-Agent architecture separates administrative tasks (Controller) from job execution (Agents), allowing Jenkins to scale efficiently.
• Docker is the fastest and most consistent way to run Jenkins for local testing and development, but state must be persisted using a named volume mapped to /var/jenkins_home.
• Jenkins environment variables (such as $BUILD_NUMBER and $WORKSPACE) are essential for tracking builds and tagging artifacts.
• Global Tool Configuration allows Jenkins to dynamically download and manage multiple versions of build tools (like Maven), avoiding version conflicts on your build nodes.
• Enterprise support is highly recommended when running Jenkins in a production environment to ensure pipeline reliability and minimize downtime.