How jenkinsci/docker works
1. This repository builds and ships the official jenkins/jenkins container images. The main product boundary is a Docker image that wraps a Jenkins controller runtime, not a standalone application codebase.
2. The image matrix is split by operating system and distribution: Linux variants for Debian, Alpine, and RHEL, plus a Windows Server Core line under windows/. The Alpine tree also has a hotspot variant, indicating JVM/runtime flavor differences are part of the image lineup.
3. Runtime startup is centered around the top-level shell and PowerShell launcher scripts (jenkins.sh, jenkins.ps1) and the shared support files in jenkins-support/. These are responsible for initializing the container, wiring environment variables, preparing Jenkins home, and launching the Jenkins process.
4. Persistent state is explicit and containerized: Jenkins data lives in /var/jenkins_home. The repo’s architecture assumes that configuration, plugins, secrets, and build state are all stored there and survive image upgrades through Docker volumes or bind mounts.
5. There is a strong “reference content” model. Files placed under /usr/share/jenkins/ref are copied into JENKINS_HOME on first start, which is how default config, init Groovy scripts, plugins, and override files are injected into a new instance.
6. Plugin management is its own subsystem. The repo bundles jenkins-plugin-cli wrappers (jenkins-plugin-cli.sh, jenkins-plugin-cli.ps1) around the Jenkins plugin installation manager tool, and images can preinstall plugins either from plugins.txt manifests or by copying custom .hpi files into the reference tree.
7. The container supports controlled initialization and upgrade behavior. Marker files and environment flags govern whether bundled plugins are upgraded, whether existing plugins are preserved, and whether init Groovy content is cleared or overridden. This makes image upgrades deterministic without replacing user-managed state in JENKINS_HOME.
8. Configuration is driven heavily by environment variables rather than extra services. Key runtime knobs include JAVA_OPTS, JENKINS_JAVA_OPTS, JENKINS_OPTS, JENKINS_SLAVE_AGENT_PORT, JENKINS_ENABLE_ENV_SUBST, and PRE_CLEAR_INIT_GROOVY_D. Reverse-proxy prefixing, logging, executors, HTTPS, and agent port settings are all configured this way.
9. Agent connectivity is an architectural boundary. Jenkins exposes the web UI on 8080 and, for inbound TCP agents, the remoting/agent port 50000. The README also distinguishes outbound SSH agents and WebSocket agents, which do not require the TCP agent port.
10. The build pipeline is Docker-centric and multi-platform. Makefile, docker-bake.hcl, and per-distro Dockerfiles define how images are assembled, while jdk-download.sh and jdk-download-url.sh pull runtime dependencies from external sources during build. Windows build scripts mirror the Linux flow with PowerShell counterparts.
11. External services matter mainly at build and plugin-resolution time. Jenkins update centers and the Jenkins plugin metadata service are used by the plugin CLI, while release/version automation tracks upstream Jenkins, JDK, and distro tag changes through updatecli/. This repo is therefore coupled to upstream release metadata, but not to any custom backend.
12. The repository has substantial test coverage around image behavior rather than unit logic. Bats tests exercise Linux container behavior, PowerShell tests cover Windows scripts, and golden files assert expected tags, platforms, and environment outputs. Specialized test directories simulate plugin installation, custom WAR contents, runtime startup, and upgrade scenarios.
13. CI/release automation is split between GitHub Actions, Jenkins, and helper scripts. .github/workflows/, Jenkinsfile, and .ci/publish.sh coordinate validation and publishing, while updatecli files keep base-image tags, tool versions, and release metadata in sync.
14. For an architecture diagram, the key flows are: upstream binaries and metadata into the image build; build outputs into versioned Docker images; and at runtime the image initializing JENKINS_HOME from /usr/share/jenkins/ref, then running Jenkins with optional plugin installation and agent connectivity over the configured ports.
Main entry points: jenkins.sh Launch scripts · jenkins-plugin-cli.sh Plugin CLI · docker-bake.hcl Build orchestration · jenkins-support.psm1 Support lib
Components 23
Build images
Dockerfiles, bake files, and download scripts that assemble the distribution matrix.
- Linux variants · Debian, Alpine, Alpine HotSpot, and RHEL image lines.
- Windows variant · Windows Server Core image line with PowerShell-based packaging.
- Debian image · Primary Linux image definition for the Debian-based line.
debian/Dockerfile - Alpine image · Alpine-based image definition.
alpine/hotspot/Dockerfile - RHEL image · RHEL-based image definition.
rhel/Dockerfile - Win image · Windows Server Core HotSpot image definition.
windows/windowsservercore/hotspot/Dockerfile - Build orchestration · Makefile and docker-bake.hcl define multi-platform image assembly.
docker-bake.hcl - JDK fetch · Scripts that resolve and download upstream JDK binaries during builds.
jdk-download.sh
Runtime launch
Entry scripts and shared support code that initialize Jenkins inside the container.
- Launch scripts · Top-level shell and PowerShell launchers for container startup.
jenkins.sh - Support lib · Shared runtime support functions for environment setup and launch behavior.
jenkins-support.psm1 - Env config · Environment-driven knobs for JVM, ports, proxying, HTTPS, and init behavior.
- Agent ports · HTTP on 8080 and optional inbound agent TCP on 50000; SSH and WebSocket are alternate paths.
Reference content
Default files copied into Jenkins home on first start, including plugins and init content.
- Jenkins home · Containerized persistent data volume at /var/jenkins_home.
- Reference tree · /usr/share/jenkins/ref files copied into Jenkins home on first start.
- Default config · Initial config, Groovy init scripts, and override files used to seed a new controller.
- Plugin CLI · Shell and PowerShell wrappers around the plugin installation manager.
jenkins-plugin-cli.sh - Plugin manifest · plugins.txt manifests and copied .hpi files that define preinstalled plugins.
tests/plugins-cli/pluginsfile/plugins.txt
Automation
CI, release, and dependency update workflows.
- CI release · GitHub Actions, Jenkinsfile, and publish scripts that validate and publish images.
Jenkinsfile - Update CLI · Updatecli manifests keep base image tags, JDKs, and Jenkins/plugin metadata current.
updatecli/updatecli.d/jenkins-version.yaml
Tests
Behavioral tests for Linux, Windows, plugins, runtime, and upgrade flows.
- Linux tests · Bats-based container behavior tests for Linux image flows.
tests/runtime.bats - Windows tests · PowerShell tests for Windows startup and plugin CLI behavior.
tests/functions.Tests.ps1 - Plugin tests · Image scenarios covering plugin install, update, custom WAR, and reference-tree behavior.
tests/plugins-cli.bats
Other components
- Jenkins Docker · Official jenkins/jenkins container image definitions and release automation.
Connections 26
- Jenkins Docker → Linux variants: ships · Repository defines the Linux image family.
- Jenkins Docker → Windows variant: ships · Repository defines the Windows image family.
- Linux variants → Debian image: includes · Debian line is built from its Dockerfile.
- Linux variants → Alpine image: includes · Alpine line is built from its Dockerfile.
- Linux variants → RHEL image: includes · RHEL line is built from its Dockerfile.
- Windows variant → Win image: includes · Windows line is built from its Dockerfile.
- Jenkins Docker → Build orchestration: builds with · Multi-platform image assembly is coordinated by Make and bake.
- Build orchestration → JDK fetch: downloads · Builds fetch upstream JDK runtime artifacts.
- Jenkins Docker → Launch scripts: starts with · Container startup begins in the launcher scripts.
- Launch scripts → Support lib: uses · Entrypoints delegate common initialization to shared helpers.
- Launch scripts → Env config: reads · Runtime behavior is driven primarily by environment variables.
- Support lib → Jenkins home: initializes · Support code prepares Jenkins home and runtime state.
- Jenkins home → Reference tree: seeded from · On first start, reference content is copied into Jenkins home.
- Reference tree → Default config: contains · Reference tree holds default config and init content.
- Reference tree → Plugin CLI: contains · Reference tree can include plugin installer inputs and wrappers.
- Plugin CLI → Plugin manifest: installs from · Plugin manager consumes manifests and custom plugin files.
- Plugin CLI → Jenkins home: writes · Installed plugins land in the persistent Jenkins home.
- Env config → Agent ports: controls · Ports and connectivity mode are configured through environment.
- Jenkins Docker → CI release: validated and published by · CI and release workflows coordinate checks and image publication.
- Jenkins Docker → Update CLI: kept in sync by · Release metadata and base versions are refreshed by updatecli.
- Jenkins Docker → Linux tests: verified by · Linux behavior is exercised by Bats tests.
- Jenkins Docker → Windows tests: verified by · Windows behavior is exercised by PowerShell tests.
- Jenkins Docker → Plugin tests: verified by · Plugin and startup scenarios are covered by dedicated tests.
- Plugin tests → Plugin CLI: covers · Tests validate plugin CLI and installation/update flows.
- Linux tests → Launch scripts: covers · Tests exercise runtime startup behavior.
- Windows tests → Launch scripts: covers · Tests exercise PowerShell launch and helper behavior.