Jenkins architecture and installation · Prasanta Kumar Behera

How Jenkins is put together (controller, agents, executors, plugins and JENKINS_HOME) and how to run it: a quick Docker install for learning, a Helm install on Kubernetes for real use, and the first settings that keep it healthy.

The controller schedules builds and holds configuration; agents do the work; plugins add almost every feature.

The moving parts

Part	What it does
Controller	Web UI and API, schedules builds, stores configuration, jobs, build history and credentials in JENKINS_HOME
Agent (node)	A machine, VM, container or Kubernetes pod that runs build steps
Executor	A slot on a node that runs one build at a time
Plugins	Almost every feature: Git, pipelines, Kubernetes agents, credentials, SSO (1,800+ exist)
Job / Pipeline	What to build and how, ideally defined in a `Jenkinsfile` in the repository

Agents connect to the controller over the inbound agent protocol (port 50000 by default, or WebSocket over the web port), or the controller starts them over SSH or through the Kubernetes API.

The controller is the head chef who reads the orders and keeps the recipe book; agents are the line cooks who actually cook. A head chef who also cooks every dish gets overwhelmed, and might spill sauce on the recipe book.

Quick start with Docker (learning)

$ docker volume create jenkins_home
$ docker run -d --name jenkins -p 8080:8080 -p 50000:50000 \
    -v jenkins_home:/var/jenkins_home jenkins/jenkins:lts-jdk21
$ docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword

Open http://localhost:8080, paste the password, install the suggested plugins and create an admin user. Use the LTS line for anything real: it's released on a slower, more tested cadence than the weekly releases.

On Kubernetes with Helm (real use)

The official chart runs the controller as a StatefulSet with a persistent volume, and configures the Kubernetes plugin so every build gets its own agent pod (lesson 06):

# values.yaml (excerpt; check the chart's values for your version)
controller:
  image:
    tag: lts-jdk21
  numExecutors: 0                 # no builds on the controller
  resources:
    requests: { cpu: "1", memory: 2Gi }
    limits:   { memory: 4Gi }
  installPlugins:                 # pin versions in production (lesson 07)
    - kubernetes
    - workflow-aggregator
    - git
    - configuration-as-code
  ingress:
    enabled: true
    hostName: jenkins.example.com
persistence:
  size: 50Gi

$ helm repo add jenkins https://charts.jenkins.io && helm repo update
$ helm install jenkins jenkins/jenkins -n jenkins --create-namespace -f values.yaml
$ kubectl -n jenkins get pods

First settings that matter

0 executors on the built-in node: builds run on agents only.
Security: a proper security realm (SSO via OIDC/SAML, or LDAP) and authorization (lesson 07). Never leave "anyone can do anything".
Build discarders: keep a bounded number of builds per job, or JENKINS_HOME fills up.
Jenkins URL set correctly (Manage Jenkins → System), so links in notifications and webhooks work.
Plugins: install only what you need; each one is code running with controller privileges.

Try it: first Jenkins

Start Jenkins with the Docker command above and complete the setup wizard.
Create a "Freestyle" job that runs echo hello and look at its console output; then set the built-in node's executors to 0 and see the job wait for an agent.
Add an agent: another container running jenkins/inbound-agent, connected with the secret Jenkins shows for a new node.
Browse JENKINS_HOME inside the container (/var/jenkins_home): jobs/, plugins/, credentials.xml.

Going deeper: high availability

Open-source Jenkins has a single active controller. Resilience comes from fast rebuild rather than clustering: configuration as code (JCasC), plugins pinned in a file, jobs defined as Jenkinsfiles discovered by multibranch pipelines, JENKINS_HOME on a persistent volume with backups. Large organisations split load across several controllers (per department or product) instead of one giant one.

Recap

Controller (schedules, stores everything in JENKINS_HOME), agents (run builds), executors (build slots), plugins (features).
Learn with the Docker image; run for real with the Helm chart on Kubernetes and ephemeral agent pods.
0 executors on the controller, real authentication, build discarders, minimal plugins, LTS releases.

This site is a public version of my personal engineering knowledge hub. It intentionally excludes confidential company information and internal operational details.