# jenkinsci/docker architecture

> Architecture diagram of the GitHub repository jenkinsci/docker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jenkinsci/docker
- Repository: https://github.com/jenkinsci/docker

## Overview

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`](https://github.com/jenkinsci/docker/blob/master/jenkins.sh) (Launch scripts), [`jenkins-plugin-cli.sh`](https://github.com/jenkinsci/docker/blob/master/jenkins-plugin-cli.sh) (Plugin CLI), [`docker-bake.hcl`](https://github.com/jenkinsci/docker/blob/master/docker-bake.hcl) (Build orchestration), [`jenkins-support.psm1`](https://github.com/jenkinsci/docker/blob/master/jenkins-support.psm1) (Support lib)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build images"]
  node_linux_matrix["Linux variants<br/>image family"]
  node_windows_matrix["Windows variant<br/>image family"]
  node_debian_dockerfile["Debian image<br/>Dockerfile"]
  node_alpine_dockerfile["Alpine image<br/>Dockerfile"]
  node_rhel_dockerfile["RHEL image<br/>Dockerfile"]
  node_windows_dockerfile["Win image<br/>Dockerfile"]
  node_bake_make["Build orchestration<br/>bake/make<br/>[docker-bake.hcl]"]
  node_jdk_fetch["JDK fetch<br/>download scripts<br/>[jdk-download.sh]"]
end

subgraph group_runtime["Runtime launch"]
  node_entrypoints["Launch scripts<br/>runtime entrypoints<br/>[jenkins.sh]"]
  node_support_lib["Support lib<br/>startup helpers"]
  node_env_config["Env config<br/>runtime settings"]
  node_agent_ports(("Agent ports<br/>connectivity boundary"))
end

subgraph group_content["Reference content"]
  node_home_seed[("Jenkins home<br/>persistent state")]
  node_ref_tree["Reference tree<br/>seed content"]
  node_default_config["Default config<br/>init content"]
  node_plugin_cli["Plugin CLI<br/>plugin installer"]
  node_plugins_manifest["Plugin manifest<br/>plugin list<br/>[plugins.txt]"]
end

subgraph group_automation["Automation"]
  node_ci_release["CI release<br/>automation"]
  node_updatecli["Update CLI<br/>dependency sync"]
end

subgraph group_tests["Tests"]
  node_linux_tests["Linux tests<br/>behavior tests<br/>[runtime.bats]"]
  node_windows_tests["Windows tests<br/>behavior tests"]
  node_plugin_tests["Plugin tests<br/>scenario tests<br/>[plugins-cli.bats]"]
end

node_repo["Jenkins Docker<br/>container-image repo"]

node_repo -->|"ships"| node_linux_matrix
node_repo -->|"ships"| node_windows_matrix
node_linux_matrix -->|"includes"| node_debian_dockerfile
node_linux_matrix -->|"includes"| node_alpine_dockerfile
node_linux_matrix -->|"includes"| node_rhel_dockerfile
node_windows_matrix -->|"includes"| node_windows_dockerfile
node_repo -->|"builds with"| node_bake_make
node_bake_make -->|"downloads"| node_jdk_fetch
node_repo -->|"starts with"| node_entrypoints
node_entrypoints -->|"uses"| node_support_lib
node_entrypoints -->|"reads"| node_env_config
node_support_lib -->|"initializes"| node_home_seed
node_home_seed -->|"seeded from"| node_ref_tree
node_ref_tree -->|"contains"| node_default_config
node_ref_tree -->|"contains"| node_plugin_cli
node_plugin_cli -->|"installs from"| node_plugins_manifest
node_plugin_cli -->|"writes"| node_home_seed
node_env_config -->|"controls"| node_agent_ports
node_repo -->|"validated and published by"| node_ci_release
node_repo -->|"kept in sync by"| node_updatecli
node_repo -->|"verified by"| node_linux_tests
node_repo -->|"verified by"| node_windows_tests
node_repo -->|"verified by"| node_plugin_tests
node_plugin_tests -->|"covers"| node_plugin_cli
node_linux_tests -->|"covers"| node_entrypoints
node_windows_tests -->|"covers"| node_entrypoints

click node_debian_dockerfile "https://github.com/jenkinsci/docker/tree/master/debian/Dockerfile"
click node_alpine_dockerfile "https://github.com/jenkinsci/docker/tree/master/alpine/hotspot/Dockerfile"
click node_rhel_dockerfile "https://github.com/jenkinsci/docker/tree/master/rhel/Dockerfile"
click node_windows_dockerfile "https://github.com/jenkinsci/docker/tree/master/windows/windowsservercore/hotspot/Dockerfile"
click node_bake_make "https://github.com/jenkinsci/docker/blob/master/docker-bake.hcl"
click node_jdk_fetch "https://github.com/jenkinsci/docker/blob/master/jdk-download.sh"
click node_entrypoints "https://github.com/jenkinsci/docker/blob/master/jenkins.sh"
click node_support_lib "https://github.com/jenkinsci/docker/blob/master/jenkins-support.psm1"
click node_plugin_cli "https://github.com/jenkinsci/docker/blob/master/jenkins-plugin-cli.sh"
click node_plugins_manifest "https://github.com/jenkinsci/docker/blob/master/tests/plugins-cli/pluginsfile/plugins.txt"
click node_ci_release "https://github.com/jenkinsci/docker/tree/master/Jenkinsfile"
click node_updatecli "https://github.com/jenkinsci/docker/blob/master/updatecli/updatecli.d/jenkins-version.yaml"
click node_linux_tests "https://github.com/jenkinsci/docker/blob/master/tests/runtime.bats"
click node_windows_tests "https://github.com/jenkinsci/docker/blob/master/tests/functions.Tests.ps1"
click node_plugin_tests "https://github.com/jenkinsci/docker/blob/master/tests/plugins-cli.bats"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_linux_matrix,node_windows_matrix,node_debian_dockerfile,node_alpine_dockerfile,node_rhel_dockerfile,node_windows_dockerfile,node_bake_make,node_jdk_fetch toneBlue
class node_entrypoints,node_support_lib,node_env_config,node_agent_ports toneAmber
class node_home_seed,node_ref_tree,node_default_config,node_plugin_cli,node_plugins_manifest toneMint
class node_ci_release,node_updatecli toneRose
class node_linux_tests,node_windows_tests,node_plugin_tests toneIndigo
class node_repo toneNeutral
```

## Components

### Build images

Dockerfiles, bake files, and download scripts that assemble the distribution matrix.

- **Linux variants**: image family · Debian, Alpine, Alpine HotSpot, and RHEL image lines.
- **Windows variant**: image family · Windows Server Core image line with PowerShell-based packaging.
- [Debian image](https://github.com/jenkinsci/docker/tree/master/debian/Dockerfile): Dockerfile · Primary Linux image definition for the Debian-based line. · `debian/Dockerfile`
- [Alpine image](https://github.com/jenkinsci/docker/tree/master/alpine/hotspot/Dockerfile): Dockerfile · Alpine-based image definition. · `alpine/hotspot/Dockerfile`
- [RHEL image](https://github.com/jenkinsci/docker/tree/master/rhel/Dockerfile): Dockerfile · RHEL-based image definition. · `rhel/Dockerfile`
- [Win image](https://github.com/jenkinsci/docker/tree/master/windows/windowsservercore/hotspot/Dockerfile): Dockerfile · Windows Server Core HotSpot image definition. · `windows/windowsservercore/hotspot/Dockerfile`
- [Build orchestration](https://github.com/jenkinsci/docker/blob/master/docker-bake.hcl): bake/make · Makefile and docker-bake.hcl define multi-platform image assembly. · `docker-bake.hcl`
- [JDK fetch](https://github.com/jenkinsci/docker/blob/master/jdk-download.sh): download scripts · 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](https://github.com/jenkinsci/docker/blob/master/jenkins.sh): runtime entrypoints · Top-level shell and PowerShell launchers for container startup. · `jenkins.sh`
- [Support lib](https://github.com/jenkinsci/docker/blob/master/jenkins-support.psm1): startup helpers · Shared runtime support functions for environment setup and launch behavior. · `jenkins-support.psm1`
- **Env config**: runtime settings · Environment-driven knobs for JVM, ports, proxying, HTTPS, and init behavior.
- **Agent ports**: connectivity boundary · 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**: persistent state · Containerized persistent data volume at /var/jenkins_home.
- **Reference tree**: seed content · /usr/share/jenkins/ref files copied into Jenkins home on first start.
- **Default config**: init content · Initial config, Groovy init scripts, and override files used to seed a new controller.
- [Plugin CLI](https://github.com/jenkinsci/docker/blob/master/jenkins-plugin-cli.sh): plugin installer · Shell and PowerShell wrappers around the plugin installation manager. · `jenkins-plugin-cli.sh`
- [Plugin manifest](https://github.com/jenkinsci/docker/blob/master/tests/plugins-cli/pluginsfile/plugins.txt): plugin list · 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](https://github.com/jenkinsci/docker/tree/master/Jenkinsfile): automation · GitHub Actions, Jenkinsfile, and publish scripts that validate and publish images. · `Jenkinsfile`
- [Update CLI](https://github.com/jenkinsci/docker/blob/master/updatecli/updatecli.d/jenkins-version.yaml): dependency sync · 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](https://github.com/jenkinsci/docker/blob/master/tests/runtime.bats): behavior tests · Bats-based container behavior tests for Linux image flows. · `tests/runtime.bats`
- [Windows tests](https://github.com/jenkinsci/docker/blob/master/tests/functions.Tests.ps1): behavior tests · PowerShell tests for Windows startup and plugin CLI behavior. · `tests/functions.Tests.ps1`
- [Plugin tests](https://github.com/jenkinsci/docker/blob/master/tests/plugins-cli.bats): scenario tests · Image scenarios covering plugin install, update, custom WAR, and reference-tree behavior. · `tests/plugins-cli.bats`

### Other components

- **Jenkins Docker**: container-image repo · Official jenkins/jenkins container image definitions and release automation.

## Connections

- 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.
