Installing Jenkins
Install Jenkins LTS from the WAR, Docker or Linux packages, unlock the setup wizard, lock down security, and learn what JENKINS_HOME holds and how to back it up.
By The Dark DebuggerUpdated 26 min read
This article gets a Jenkins controller running and makes it safe to leave running. It covers the three common installation methods (the WAR file, Docker and Linux packages), the setup wizard and what happens if you skip it, the first security settings, what lives in JENKINS_HOME, and how to back up and upgrade. It assumes you have read What Jenkins Is and How It Works and are comfortable in a Linux shell; Variables, Quoting, and the Environment covers the shell side.
Why the installation method matters
Installing Jenkins takes five minutes. The decisions you make in those five minutes stay with you for years: where JENKINS_HOME lives decides what you back up, the way you start Jenkins decides how you upgrade it, and whether you secured it on day one decides whether a stranger on your network can run shell commands as the Jenkins user. A common way this goes wrong: someone starts Jenkins in a container "just to try it", without a volume, configures thirty jobs over a month, and loses all of them on the next docker rm.
Everything here was run against Jenkins 2.580.2 LTS. Commands that need root or Docker were not run on my lab machine and are marked as such.
Before you install: Java and hardware
Jenkins is a Java application, and the Java version matters. According to the official Java support policy, Jenkins 2.463 and later (LTS 2.479.1 and later) run on Java 21, Java 25 support arrived in 2.534 (LTS 2.541.1), and Java 17 support ended with weekly 2.544 and LTS 2.541.3. So for any current LTS you need Java 21 or 25. Check what you have:
java -versionopenjdk version "21.0.13" 2026-10-20 LTS
OpenJDK Runtime Environment Temurin-21.0.13+9 (build 21.0.13+9-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.13+9 (build 21.0.13+9-LTS, mixed mode, sharing)The documented hardware floor is 256 MB of RAM and 1 GB of disk (10 GB if you run the Docker image), and the recommendation for a small team is 4 GB+ of RAM and 50 GB+ of disk. Treat the minimum as "it starts", not "it works". The sizing section below shows where the disk actually goes.
LTS or weekly? Jenkins ships a weekly release and, every 12 weeks, picks one as the base of a Long-Term Support line that gets backported fixes. Run LTS unless you need a feature that only exists in weekly.
Option 1: the WAR file
The WAR is the whole of Jenkins in one file, and it runs anywhere Java runs. It is what I used for this series, because it needs no root access and makes every moving part visible. Download it and its checksum, then verify:
curl -fsSLO https://get.jenkins.io/war-stable/2.580.2/jenkins.war
curl -fsSLO https://get.jenkins.io/war-stable/2.580.2/jenkins.war.sha256
ls -l
sha256sum -c jenkins.war.sha256
java -jar jenkins.war --versiontotal 52772
-rw-r--r-- 1 sid sid 54033126 Nov 9 21:28 jenkins.war
-rw-r--r-- 1 sid sid 77 Nov 9 21:28 jenkins.war.sha256
jenkins.war: OK
2.580.2Never skip the checksum. It costs one command and catches truncated downloads and tampered mirrors.
Two settings matter when you start it: JENKINS_HOME (where Jenkins keeps everything; the default is ~/.jenkins) and the HTTP port (default 8080). --help lists the rest:
java -jar jenkins.war --helpRunning from: /opt/jenkins/jenkins.war
webroot: /home/sid/.jenkins/war
Jenkins Automation Server Engine 2.580.2
Usage: java -jar jenkins.war [--option=value] [--option=value]
Options:
--webroot = folder where the WAR file is expanded into. Default is ${JENKINS_HOME}/war
[…]
--prefix = add this prefix to all URLs (eg http://localhost:8080/prefix/resource). Default is none
[…]
--httpPort = set the http listening port. -1 to disable, Default is 8080
--httpListenAddress = set the http listening address. Default is all interfaces
[…]Note --httpListenAddress: by default Jenkins listens on every network interface. If a reverse proxy will terminate TLS in front of it, bind Jenkins to 127.0.0.1 so the only way in is through the proxy. I started a fresh controller like this (in the background, with its output going to a log file):
export JENKINS_HOME="$PWD/home"
java -jar jenkins.war --httpPort=8092 --httpListenAddress=127.0.0.1For a long-running installation you would wrap that command in a systemd service, which is exactly what the Linux packages below do for you.
The setup wizard: unlocking Jenkins
On first start, Jenkins creates an admin account with a random password and refuses to do anything else until you prove you can read the server's files. The log says so:
2026-11-10 02:28:28.295+0000 [id=38] INFO jenkins.model.Jenkins#<init>: Starting version 2.580.2
[…]
2026-11-10 02:28:34.634+0000 [id=51] INFO jenkins.install.SetupWizard#init:
[LF]>
[LF]> *************************************************************
[LF]> *************************************************************
[LF]> *************************************************************
[LF]>
[LF]> Jenkins initial setup is required. An admin user has been created and a password generated.
[LF]> Please use the following password to proceed to installation:
[LF]>
[LF]> 074d325b8bfd4c89b0c6e0f65da19aa9
[LF]>
[LF]> This may also be found at: /home/sid/secrets/initialAdminPassword
[LF]>
[LF]> *************************************************************
[LF]> *************************************************************
[LF]> *************************************************************
2026-11-10 02:28:39.136+0000 [id=51] INFO jenkins.InitReactorRunner$1#onAttained: Completed initialization
2026-11-10 02:28:39.206+0000 [id=38] INFO hudson.lifecycle.Lifecycle#onReady: Jenkins is fully up and runningThe same password is in a file only the Jenkins user can read:
cat home/secrets/initialAdminPassword
ls -l home/secrets074d325b8bfd4c89b0c6e0f65da19aa9
total 16
-rw-r--r-- 1 sid sid 48 Nov 9 21:28 hudson.model.User.DIRNAMES
-rw-r----- 1 sid sid 33 Nov 9 21:28 initialAdminPassword
-rw-r--r-- 1 sid sid 32 Nov 9 21:28 jenkins.model.Jenkins.crumbSalt
-rw-r--r-- 1 sid sid 256 Nov 9 21:28 master.keyUntil the wizard is finished, every page requires the Administer permission. You can see that, and the exact version, in the response headers:
curl -sS -i http://127.0.0.1:8092/ | head -16HTTP/1.1 403 Forbidden
Server: Jetty(12.1.14)
Date: Tue, 10 Nov 2026 02:28:40 GMT
Vary: Accept-Encoding
X-Content-Type-Options: nosniff
Content-Security-Policy-Report-Only: base-uri 'none'; default-src 'self'; form-action 'self'; frame-ancestors 'self'; img-src 'self' data:; script-src 'report-sample' 'self' usage.jenkins.io; style-src 'report-sample' 'self' 'unsafe-inline';
Set-Cookie: JSESSIONID.a18258c5=node0x0yio475gfin17uo137w9v83q0.node0; Path=/; HttpOnly; SameSite=Lax
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: text/html;charset=utf-8
X-Hudson: 1.395
X-Jenkins: 2.580.2
X-Jenkins-Session: 3ad13390
X-You-Are-Authenticated-As: anonymous
X-You-Are-In-Group-Disabled: JENKINS-39402: use -Dhudson.security.AccessDeniedException2.REPORT_GROUP_HEADERS=true or use /whoAmI to diagnose
X-Required-Permission: hudson.model.Hudson.Administer
Transfer-Encoding: chunkedIn the browser, http://localhost:8080/ redirects to the Unlock Jenkins page, which asks for that password. The initial password really is the admin account's password, which is handy for scripting:
curl -sS -u "admin:$(cat home/secrets/initialAdminPassword)" http://127.0.0.1:8092/whoAmI/api/json | jq .{
"_class": "hudson.security.WhoAmI",
"anonymous": false,
"authenticated": true,
"authorities": [
"authenticated",
"FACTOR_PASSWORD"
],
"name": "admin"
}After the unlock, the wizard walks through four screens:
- Customize Jenkins. Choose Install suggested plugins or Select plugins to install.
- Create First Admin User. Create your real account. The generated password stops working once you finish.
- Instance Configuration. Set the Jenkins URL, the address users and webhooks will use. Jenkins puts it in links and emails, and the CLI refuses to connect without it (see Common mistakes).
- Jenkins is ready.
What does "suggested" mean? The list ships inside the WAR, so you can read it before you click:
unzip -p jenkins.war WEB-INF/lib/jenkins-core-2.580.2.jar > jenkins-core.jar
unzip -p jenkins-core.jar jenkins/install/platform-plugins.json \
| jq -r '.[] | .category as $c | .plugins[] | select(.suggested==true) | "\($c): \(.name)"'Organization and Administration: cloudbees-folder
Organization and Administration: antisamy-markup-formatter
Build Features: build-timeout
Build Features: credentials-binding
Build Features: timestamper
Build Features: ws-cleanup
Build Tools: ant
Build Tools: gradle
Pipelines and Continuous Delivery: workflow-aggregator
Pipelines and Continuous Delivery: github-branch-source
Pipelines and Continuous Delivery: pipeline-github-lib
Pipelines and Continuous Delivery: pipeline-graph-view
Source Code Management: git
Distributed Builds: ssh-slaves
User Management and Security: matrix-auth
User Management and Security: ldap
Notifications and Publishing: email-ext
Notifications and Publishing: mailer
Appearance: dark-themeThat is a sensible starting set. If you will never build with Ant or Gradle or authenticate against LDAP, untick those: fewer plugins means fewer updates and a smaller attack surface.
Skipping the wizard, and why that alone is dangerous
Automated installs (containers, configuration management) skip the wizard with the system property jenkins.install.runSetupWizard=false. Here is what you get if you do only that, on a fresh JENKINS_HOME:
export JENKINS_HOME="$PWD/skip-home"
java -Djenkins.install.runSetupWizard=false -jar jenkins.war --httpPort=8093 --httpListenAddress=127.0.0.1curl -sS http://127.0.0.1:8093/whoAmI/api/json | jq .
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8093/script
grep -E 'authorizationStrategy|securityRealm' skip-home/config.xml{
"_class": "hudson.security.WhoAmI",
"anonymous": true,
"authenticated": true,
"authorities": [
"anonymous"
],
"name": "anonymous"
}
200
<authorizationStrategy class="hudson.security.AuthorizationStrategy$Unsecured"/>
<securityRealm class="hudson.security.SecurityRealm$None"/>No users, no login, and the Script Console (/script), which runs arbitrary Groovy on the controller, answers anonymous visitors with HTTP 200. Anyone who can reach that port owns the machine. Skipping the wizard is fine; skipping it without replacing what it does is not.
The wizard does three jobs, and an automated install must do all three itself.
1. Install plugins from a list. The plugin installation manager tool (it is jenkins-plugin-cli inside the official Docker image) resolves dependencies and downloads everything into the plugins directory. Here is the plugins.txt I gave it, one plugin ID per line:
cloudbees-folder
antisamy-markup-formatter
build-timeout
credentials-binding
timestamper
ws-cleanup
workflow-aggregator
pipeline-graph-view
git
ssh-slaves
matrix-auth
mailertime java -jar jenkins-plugin-manager.jar --war jenkins.war \
--plugin-download-directory skip-home/plugins --plugin-file plugins.txt
ls skip-home/plugins | wc -l
du -sh skip-home/pluginsDone
real 0m10.875s
user 0m25.747s
sys 0m6.075s
79
61M skip-home/pluginsTwelve plugins on the list became 79 plugin files once dependencies were resolved. Keep plugins.txt in version control; it is the reproducible answer to "which plugins does our Jenkins have?".
2. Create an admin account and turn on security. Groovy scripts in $JENKINS_HOME/init.groovy.d/ run at every start-up, after Jenkins has loaded its configuration. This one secures a fresh controller on the first start and does nothing on later starts:
// init.groovy.d/01-security.groovy
// Runs at every start-up. On the first start it creates an admin account
// and switches on "logged-in users can do anything, anonymous can do nothing".
import jenkins.model.Jenkins
import hudson.security.HudsonPrivateSecurityRealm
import hudson.security.FullControlOnceLoggedInAuthorizationStrategy
def jenkins = Jenkins.get()
if (!(jenkins.securityRealm instanceof HudsonPrivateSecurityRealm)) {
def password = System.getenv('JENKINS_ADMIN_PASSWORD')
if (!password) {
throw new IllegalStateException('JENKINS_ADMIN_PASSWORD is not set')
}
def realm = new HudsonPrivateSecurityRealm(false) // false = no self sign-up
realm.createAccount('admin', password)
jenkins.setSecurityRealm(realm)
def strategy = new FullControlOnceLoggedInAuthorizationStrategy()
strategy.setAllowAnonymousRead(false)
jenkins.setAuthorizationStrategy(strategy)
jenkins.save()
}I started a fresh controller with that script in place, a password in the environment, and a 512 MB heap:
export JENKINS_ADMIN_PASSWORD='correct-horse-battery-staple'
java -Xmx512m -Djenkins.install.runSetupWizard=false -jar jenkins.war --httpPort=8094 --httpListenAddress=127.0.0.1grep GroovyHookScript tj.log
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8094/api/json
curl -sS -u "admin:$JENKINS_ADMIN_PASSWORD" http://127.0.0.1:8094/whoAmI/api/json | jq -c '{name, authenticated}'
grep -E 'authorizationStrategy|securityRealm|denyAnonymous|disableSignup' "$JENKINS_HOME/config.xml"2026-11-10 06:22:57.940+0000 [id=51] INFO j.util.groovy.GroovyHookScript#execute: Executing /home/sid/install-demo/sec-home/init.groovy.d/01-security.groovy
403
{"name":"admin","authenticated":true}
<authorizationStrategy class="hudson.security.FullControlOnceLoggedInAuthorizationStrategy">
<denyAnonymousReadAccess>true</denyAnonymousReadAccess>
</authorizationStrategy>
<securityRealm class="hudson.security.HudsonPrivateSecurityRealm">
<disableSignup>true</disableSignup>
</securityRealm>Anonymous requests now get 403, and the settings landed in config.xml exactly as if you had clicked them under Manage Jenkins → Security.
3. Set the Jenkins URL. One more small script; this is the value the wizard's Instance Configuration screen asks for:
// init.groovy.d/02-location.groovy - the URL the wizard would have asked for
import jenkins.model.JenkinsLocationConfiguration
def location = JenkinsLocationConfiguration.get()
if (!location.url) {
location.url = 'http://127.0.0.1:8094/'
location.save()
}Init scripts are fine for a handful of settings. Once you are configuring security realms, credentials, agents and tools this way, switch to Jenkins Configuration as Code, which expresses the same thing as declarative YAML.
Option 2: Docker
The official image is jenkins/jenkins. The tag lts-jdk21 tracks the current LTS on Java 21. Docker was not available on my lab machine, so the commands in this section were not run. I did confirm the tag exists on Docker Hub:
curl -fsS https://hub.docker.com/v2/repositories/jenkins/jenkins/tags/lts-jdk21 | jq '{name, last_updated, digest: .digest}'{
"name": "lts-jdk21",
"last_updated": "2026-10-28T13:44:13.27861Z",
"digest": "sha256:74401de6a6f92e1afe1b02d1c8e3d0c33f263bfb5275dd8813f9150355f2367b"
}The command that matters is the one with the volume. Without -v, JENKINS_HOME lives in the container's writable layer and disappears with the container:
docker volume create jenkins_home
docker run -d --name jenkins --restart=on-failure \
-p 8080:8080 -p 50000:50000 \
-v jenkins_home:/var/jenkins_home \
jenkins/jenkins:lts-jdk21
docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPasswordPort 8080 is the web UI. Port 50000 is the TCP port inbound agents connect to; leave it out if you will only use SSH agents or WebSocket connections.
For anything beyond a trial, bake the plugin list into your own image so every container starts with the same plugins:
FROM jenkins/jenkins:lts-jdk21
COPY --chown=jenkins:jenkins plugins.txt /usr/share/jenkins/ref/plugins.txt
RUN jenkins-plugin-cli --plugin-file /usr/share/jenkins/ref/plugins.txtUpgrading a Docker install means pulling the new tag and recreating the container with the same volume. That is clean, as long as the volume really holds everything. One warning: mounting the host's Docker socket into the Jenkins container so builds can run docker gives every build root on the host. Use agents for container builds instead (Agents and Distributed Builds).
Option 3: Linux packages
On a server you will keep, the distribution package is the least surprising choice: it creates a jenkins user, installs a systemd unit, keeps JENKINS_HOME at /var/lib/jenkins, sends logs to the journal, and upgrades with the rest of the system. These commands need root, so I did not run them on the lab machine. They are the current instructions from pkg.jenkins.io for the LTS ("stable") line on Debian and Ubuntu:
sudo apt update
sudo apt install fontconfig openjdk-21-jre
sudo wget -O /etc/apt/keyrings/jenkins-keyring.asc \
https://pkg.jenkins.io/debian-stable/jenkins.io-2026.key
echo "deb [signed-by=/etc/apt/keyrings/jenkins-keyring.asc]" \
https://pkg.jenkins.io/debian-stable binary/ | sudo tee \
/etc/apt/sources.list.d/jenkins.list > /dev/null
sudo apt update
sudo apt install jenkinsTwo details trip people up. First, the repository signing key was rotated: it is jenkins.io-2026.key now, and older guides that use jenkins.io-2023.key will fail at apt update with a signature error. Second, install Java before Jenkins; the official guide warns that the service may otherwise fail with jenkins: failed to find a valid Java installation.
You can check the key without root before trusting it. The fingerprint should match the one published on pkg.jenkins.io:
curl -fsSLO https://pkg.jenkins.io/debian-stable/jenkins.io-2026.key
gpg --show-keys jenkins.io-2026.key[…]
pub rsa4096 2025-12-22 [SC] [expires: 2028-12-21]
5E386EADB55F01504CAE8BCF7198F4B714ABFC68
uid Jenkins Project <jenkinsci-board@googlegroups.com>To change the port of a package install, don't edit the packaged unit file; add an override with sudo systemctl edit jenkins:
[Service]
Environment="JENKINS_PORT=8081"Then sudo systemctl restart jenkins, and read problems with journalctl -u jenkins.service. On Red Hat-family systems the repository file is https://pkg.jenkins.io/rpm-stable/jenkins.repo, saved to /etc/yum.repos.d/jenkins.repo, followed by dnf install fontconfig java-21-openjdk jenkins (also not run here).
Windows and macOS
I did not run either of these; both come from the official installation pages.
- Windows: the MSI installer installs Jenkins as a Windows service. It asks for a destination folder, the service account, the port (default 8080) and the Java home. Use a dedicated local or domain account with the "Log on as a service" right rather than LocalSystem: a compromised plugin running as LocalSystem has the run of the machine. Builds on Windows use
batorpowershellsteps instead ofsh. - macOS: Homebrew packages the LTS line as
jenkins-lts. Install withbrew install jenkins-ltsand run withbrew services start jenkins-lts. This is fine for experimenting on a laptop; I wouldn't host a team's controller on one.
Whatever the platform, Manage Jenkins → System shows the Home directory in use at the top of the page, which settles "where did it put my files?".
Talk to Jenkins from the command line
Every later article drives Jenkins from the shell, so set this up once. Create an API token for your user: click your name in the top-right corner, open Security, and use Add new token under API Token. Tokens can be revoked one at a time and never expose your password. Then download the CLI client from your own controller:
curl -fsSO http://localhost:8090/jnlpJars/jenkins-cli.jar
ls -l jenkins-cli.jar-rw-r--r-- 1 sid sid 11730469 Nov 9 21:41 jenkins-cli.jarThe CLI reads the server and credentials from environment variables, so a small shell function keeps every later command short:
export JENKINS_URL=http://localhost:8090/
export JENKINS_USER_ID=admin
export JENKINS_API_TOKEN='paste-your-token-here'
jcli() { java -jar ~/jenkins-cli.jar "$@"; }
jcli who-am-i
jcli versionAuthenticated as: admin
Authorities:
authenticated
2.580.2The same token works for the REST API with curl -u "admin:$JENKINS_API_TOKEN", which is how the API examples in this series authenticate. Put the export lines in a file only you can read, not in your shell history.
What lives in JENKINS_HOME
Everything Jenkins knows is a file under JENKINS_HOME. Here is the home of the lab controller that ran every build in this series, after a day of use:
ls -l ~/.jenkinstotal 136
drwxr-xr-x 4 sid sid 4096 Nov 9 21:55 caches
-rw-r--r-- 1 sid sid 1662 Nov 10 01:18 config.xml
-rw-r--r-- 1 sid sid 10125 Nov 9 21:57 credentials.xml
drwxr-xr-x 33 sid sid 4096 Nov 10 01:20 fingerprints
-rw-r--r-- 1 sid sid 156 Nov 10 01:18 hudson.model.UpdateCenter.xml
-rw-r--r-- 1 sid sid 217 Nov 9 21:22 hudson.plugins.copyartifact.CopyArtifactConfiguration.xml
-rw-r--r-- 1 sid sid 370 Nov 9 21:22 hudson.plugins.git.GitTool.xml
-rw------- 1 sid sid 1680 Nov 9 21:22 identity.key.enc
drwxr-xr-x 2 sid sid 4096 Nov 9 21:22 init.groovy.d
-rw-r--r-- 1 sid sid 7 Nov 10 01:18 jenkins.install.InstallUtil.lastExecVersion
-rw-r--r-- 1 sid sid 7 Nov 9 21:22 jenkins.install.UpgradeWizard.state
-rw-r--r-- 1 sid sid 179 Nov 10 01:18 jenkins.model.JenkinsLocationConfiguration.xml
-rw-r--r-- 1 sid sid 171 Nov 9 21:22 jenkins.telemetry.Correlator.xml
drwxr-xr-x 67 sid sid 4096 Nov 10 01:20 jobs
drwxr-xr-x 3 sid sid 4096 Nov 9 21:51 logs
-rw-r--r-- 1 sid sid 1037 Nov 10 01:18 nodeMonitors.xml
drwxr-xr-x 2 sid sid 4096 Nov 9 22:01 nodes
-rw-r--r-- 1 sid sid 504 Nov 10 01:21 org.jenkinsci.plugins.resourcedisposer.AsyncResourceDisposer.xml
-rw-r--r-- 1 sid sid 46 Nov 10 01:20 org.jenkinsci.plugins.workflow.flow.FlowExecutionList.xml
drwxr-xr-x 101 sid sid 12288 Nov 9 21:22 plugins
-rw-r--r-- 1 sid sid 260 Nov 10 01:22 queue.xml
-rw-r--r-- 1 sid sid 260 Nov 9 22:06 queue.xml.bak
-rw-r--r-- 1 sid sid 932 Nov 9 22:02 scriptApproval.xml
-rw-r--r-- 1 sid sid 64 Nov 9 21:22 secret.key
-rw-r--r-- 1 sid sid 0 Nov 9 21:22 secret.key.not-so-secret
drwx------ 2 sid sid 4096 Nov 9 21:52 secrets
drwxr-xr-x 2 sid sid 4096 Nov 9 21:22 updates
drwxr-xr-x 2 sid sid 4096 Nov 9 21:22 userContent
drwxr-xr-x 4 sid sid 4096 Nov 9 21:53 users
drwxr-xr-x 10 sid sid 4096 Nov 9 21:22 war
drwxr-xr-x 88 sid sid 4096 Nov 10 01:21 workspace| Path | What it holds | Back it up? |
|---|---|---|
config.xml | Global settings: security realm, authorization, executors, views | Yes |
*.xml at the top level | Settings of individual plugins and features (Git tool, Jenkins URL, script approvals) | Yes |
jobs/ | One directory per job: config.xml plus build history, logs and archived artifacts | Yes, it is the history |
users/ | User accounts, password hashes, API token hashes | Yes |
credentials.xml | Stored credentials, encrypted | Yes, together with secrets/ |
secrets/, secret.key | Keys that decrypt credentials, including secrets/master.key | Yes, and protect the backup |
nodes/ | Agent definitions | Yes |
plugins/ | Plugin archives (.jpi) and their unpacked directories | Optional if you keep plugins.txt |
fingerprints/ | Checksums of archived artifacts and where they were used | Optional |
init.groovy.d/ | Start-up scripts | Yes, or keep them in git |
workspace/ | Build working directories | No, rebuilt by the next build |
war/ | The unpacked WAR | No |
caches/, updates/, logs/ | Git caches, update-center metadata, task logs | No |
Sizing a controller
Where does the disk go? On that same lab controller, after roughly 65 jobs and a few hundred builds:
cd ~/.jenkins && du -sh -- */ | sort -h4.0K nodes/
8.0K init.groovy.d/
8.0K logs/
8.0K userContent/
24K users/
48K secrets/
376K caches/
408K fingerprints/
3.4M updates/
6.5M workspace/
8.2M jobs/
66M war/
206M plugins/On a toy installation, plugins dominate. On a real one, jobs/ overtakes everything: every build keeps its log, test results and archived artifacts until a build discarder removes them. That is why every job in this series sets one (Freestyle Jobs shows it working). Practical guidance:
- Disk: put
JENKINS_HOMEon its own volume so a runaway job fills that volume and not the root filesystem. Start at 50 GB and watch growth weekly. - Memory: the JVM heap (
-Xmx) is what matters. The controller for this series ran with-Xmx768m, and my throwaway test controllers ran fine with-Xmx512mbecause they carried a handful of jobs. A team controller with many jobs and agents usually wants a few gigabytes. Raise the heap if the log showsOutOfMemoryErroror long garbage-collection pauses. - CPU and executors: the controller only schedules work. Builds belong on agents, where executors roughly match CPU cores.
Backups and upgrades
A backup is a copy of the parts of JENKINS_HOME you cannot rebuild. This script archives the home and skips what Jenkins regenerates:
#!/usr/bin/env bash
# Archive the parts of JENKINS_HOME that cannot be rebuilt.
set -euo pipefail
home=${JENKINS_HOME:?set JENKINS_HOME}
dest=${1:?usage: jenkins-backup.sh DEST_DIR}
archive="$dest/jenkins-home-$(date +%Y%m%d-%H%M%S).tar.gz"
tar -C "$home" -czf "$archive" \
--exclude=./workspace --exclude=./war --exclude=./caches \
--exclude=./updates --exclude=./logs \
.
ls -lh "$archive"I ran it against the throwaway controller from the security section after creating one job (nightly-cleanup) and building it once:
./jenkins-backup.sh /home/sid/install-demo/backups
tar -tzf backups/jenkins-home-*.tar.gz | sort-rw-r--r-- 1 sid sid 4.4K Nov 10 01:23 /home/sid/install-demo/backups/jenkins-home-20261110-012357.tar.gz
./
./.lastStarted
./config.xml
./hudson.model.UpdateCenter.xml
./init.groovy.d/
./init.groovy.d/01-security.groovy
./init.groovy.d/02-location.groovy
./jenkins.install.InstallUtil.lastExecVersion
./jenkins.install.UpgradeWizard.state
./jenkins.model.JenkinsLocationConfiguration.xml
./jenkins.telemetry.Correlator.xml
./jobs/
./jobs/nightly-cleanup/
./jobs/nightly-cleanup/builds/
./jobs/nightly-cleanup/builds/1/
./jobs/nightly-cleanup/builds/1/build.xml
./jobs/nightly-cleanup/builds/1/changelog.xml
./jobs/nightly-cleanup/builds/1/log
./jobs/nightly-cleanup/builds/permalinks
./jobs/nightly-cleanup/config.xml
./jobs/nightly-cleanup/nextBuildNumber
./nodeMonitors.xml
./plugins/
./queue.xml
./secret.key
./secret.key.not-so-secret
./secrets/
./secrets/hudson.console.ConsoleNote.MAC
./secrets/hudson.model.Job.serverCookie
./secrets/hudson.model.User.DIRNAMES
./secrets/jenkins.model.Jenkins.crumbSalt
./secrets/jenkins.security.csp.ReportingContext.key
./secrets/master.key
./userContent/
./userContent/readme.txt
./users/
./users/admin_2c9c54a53d40846275a4229762e6fb11c44dac26c02f0cabdddfb38ccd6ca47f/
./users/admin_2c9c54a53d40846275a4229762e6fb11c44dac26c02f0cabdddfb38ccd6ca47f/config.xmlThe unpacked WAR alone was 66 MB of that home; the archive is 4.4 KB. A backup you have never restored is a hope, not a backup, so I unpacked it into an empty directory, started Jenkins on it, and asked for the job:
mkdir -p restore && tar -C restore -xzf backups/jenkins-home-*.tar.gz
export JENKINS_HOME="$PWD/restore"
java -Xmx512m -Djenkins.install.runSetupWizard=false -jar jenkins.war --httpPort=8094 --httpListenAddress=127.0.0.1curl -sS -u "admin:correct-horse-battery-staple" "http://127.0.0.1:8094/job/nightly-cleanup/api/json?tree=name,lastBuild%5Bnumber,result%5D" | jq -c .{"_class":"hudson.model.FreeStyleProject","name":"nightly-cleanup","lastBuild":{"_class":"hudson.model.FreeStyleBuild","number":1,"result":"SUCCESS"}}The job, its build history and the admin login all survived. Three rules for real backups:
- The archive contains
secrets/master.key. Anyone holding the archive pluscredentials.xmlcan decrypt every stored credential. Encrypt backups and restrict who can read them. - Back up a quiet controller. Copying files while builds write to them can capture half-written XML. Run the backup when the queue is empty, use Manage Jenkins → Prepare for Shutdown first, or take a filesystem snapshot.
- Schedule it. A crontab line such as
15 2 * * * JENKINS_HOME=/var/lib/jenkins /usr/local/bin/jenkins-backup.sh /var/backups/jenkins(not installed on my lab machine) does the job; System Monitoring and Scheduling with cron and systemd covers cron properly.
Upgrades follow the installation method: replace the WAR and restart, apt upgrade jenkins, or pull a new image tag and recreate the container on the same volume. Before any upgrade:
- Take a backup, and know how to restore it (above).
- Read the LTS upgrade guide for every version you are skipping. It lists breaking changes, such as the Java 17 removal.
- Update plugins first, then core. Manage Jenkins → Plugins flags plugins with known security issues.
Jenkins records the last version that ran against a home, which tells you what you are upgrading from:
cat ~/.jenkins/jenkins.install.InstallUtil.lastExecVersion2.580.2Where you'll use this
A typical small-team controller, end to end:
- A Linux VM with a separate 100 GB volume mounted at
/var/lib/jenkins, the Jenkins package from the LTS repository, and Java 21 installed first. - Jenkins bound to
127.0.0.1(JENKINS_LISTEN_ADDRESSin the systemd override), behind nginx or another reverse proxy that terminates TLS forhttps://ci.example.com/. - The setup wizard completed once by the administrator, or skipped in favour of
plugins.txtplus Configuration as Code so the controller can be rebuilt from git. - The built-in node's executors set to 0 and all builds on agents (Agents and Distributed Builds).
- A nightly backup with the script above, copied off the machine, and a restore test after every LTS upgrade.
None of those steps is exotic, and each one maps to a section of this article.
Common mistakes
The CLI fails with "Jenkins URL is not configured". On my secured throwaway controller (wizard skipped, no Jenkins URL set), the CLI handshake was refused even with correct credentials:
java -jar ~/jenkins-cli.jar -s http://127.0.0.1:8094/ -auth "admin:$JENKINS_ADMIN_PASSWORD" create-job nightly-cleanup < job.xmlCLI handshake failed with status code 403
Content-Length: 0
Content-Security-Policy-Report-Only: base-uri 'none'; default-src 'self'; form-action 'self'; frame-ancestors 'self'; img-src 'self' data:; script-src 'report-sample' 'self' usage.jenkins.io; style-src 'report-sample' 'self' 'unsafe-inline';
Date: Tue, 10 Nov 2026 06:23:02 GMT
Server: Jetty(12.1.14)
Vary: Accept-Encoding
X-CLI-Error: Jenkins URL is not configured (set Jenkins URL in the configuration)
X-Content-Type-Options: nosniffThe X-CLI-Error header gives the cause. Set Jenkins URL under Manage Jenkins → System (or with 02-location.groovy above). On a fresh controller started with both init scripts, the CLI worked first time:
java -jar ~/jenkins-cli.jar -s http://127.0.0.1:8094/ -auth "admin:$JENKINS_ADMIN_PASSWORD" who-am-i
java -jar ~/jenkins-cli.jar -s http://127.0.0.1:8094/ -auth "admin:$JENKINS_ADMIN_PASSWORD" create-job nightly-cleanup < job.xml
java -jar ~/jenkins-cli.jar -s http://127.0.0.1:8094/ -auth "admin:$JENKINS_ADMIN_PASSWORD" build nightly-cleanup -sAuthenticated as: admin
Authorities:
authenticated
FACTOR_PASSWORD
Started nightly-cleanup #1
Completed nightly-cleanup #1 : SUCCESSThe port is already taken. Starting a second Jenkins on a port that is in use doesn't fall back to another port; it dies:
java -jar jenkins.war --httpPort=8090 --httpListenAddress=127.0.0.1[…]
java.io.IOException: Failed to start Jetty
Caused by: java.io.IOException: Failed to bind to /127.0.0.1:8090
... 4 more
Caused by: java.net.BindException: Address already in use
... 19 more
2026-11-10 06:25:33.394+0000 [id=1] SEVERE winstone.Logger#logInternal: Container startup failed
java.net.BindException: Address already in use
Caused: java.io.IOException: Failed to bind to /127.0.0.1:8090
Caused: java.io.IOException: Failed to start JettyThe exit code was 1. Find the owner with ss -ltnp | grep 8090, then pick another port with --httpPort (or JENKINS_PORT for a package install).
Skipping the wizard and forgetting security. Covered above, but worth repeating as a mistake: runSetupWizard=false on its own gives anonymous users the Script Console. If you skip the wizard, the same automation must create users and set authorization before the port is reachable.
Summary
- Current LTS releases need Java 21 or 25; Java 17 support ended with 2.541.3. Install Java before the Jenkins package.
- The WAR runs anywhere with
java -jar jenkins.war;JENKINS_HOMEand--httpPortare the two settings that matter. Always verify the checksum. - The setup wizard unlocks with
secrets/initialAdminPassword, installs plugins, creates the real admin and sets the Jenkins URL. Skipping it withrunSetupWizard=falseleaves Jenkins completely open unless you replace all three steps. - Docker needs a volume for
/var/jenkins_home, or your configuration dies with the container. The Debian packages now use thejenkins.io-2026.keysigning key. - Use API tokens, not passwords, for the CLI and REST API. The CLI reads
JENKINS_URL,JENKINS_USER_IDandJENKINS_API_TOKEN, and refuses to connect until the Jenkins URL is configured. - Back up
config.xml,jobs/,users/,nodes/,credentials.xmlandsecrets/; skipworkspace/,war/and caches. Protect the backup, because it can decrypt your credentials, and test the restore.
Exercises
Download the 2.580.2 WAR and its .sha256 file, verify the checksum, and print the version the WAR reports without starting a server.
Show Solution
curl -fsSLO https://get.jenkins.io/war-stable/2.580.2/jenkins.war
curl -fsSLO https://get.jenkins.io/war-stable/2.580.2/jenkins.war.sha256
sha256sum -c jenkins.war.sha256
java -jar jenkins.war --versionjenkins.war: OK
2.580.2sha256sum -c reads the expected hash and file name from the .sha256 file and prints OK only on a match; on a mismatch it prints FAILED and exits non-zero, so it also works inside scripts.
Your reverse proxy will publish Jenkins at https://ci.example.com/jenkins/. Start a throwaway Jenkins so that its pages live under /jenkins, and prove with curl that /jenkins/login works and /login does not.
Hint
Look for an option in java -jar jenkins.war --help that adds a prefix to all URLs.
Show Solution
java -Xmx512m -Djenkins.install.runSetupWizard=false -jar jenkins.war --httpPort=8094 --httpListenAddress=127.0.0.1 --prefix=/jenkinsFrom another terminal:
curl -sS -o /dev/null -w '/jenkins/login %{http_code}\n' http://127.0.0.1:8094/jenkins/login
curl -sS -o /dev/null -w '/login %{http_code}\n' http://127.0.0.1:8094/login/jenkins/login 200
/login 404The proxy must forward /jenkins/ to http://127.0.0.1:8094/jenkins/ without stripping the prefix, and the Jenkins URL setting must be https://ci.example.com/jenkins/ so generated links are correct.
Start a fresh controller with the wizard disabled so that, on its very first start, anonymous users get 403 and an admin account exists with a password taken from an environment variable. Prove both with curl.
Show Solution
Put 01-security.groovy from Skipping the wizard into $JENKINS_HOME/init.groovy.d/ before the first start, then:
export JENKINS_ADMIN_PASSWORD='correct-horse-battery-staple'
java -Xmx512m -Djenkins.install.runSetupWizard=false -jar jenkins.war --httpPort=8094 --httpListenAddress=127.0.0.1curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8094/api/json
curl -sS -u "admin:$JENKINS_ADMIN_PASSWORD" http://127.0.0.1:8094/whoAmI/api/json | jq -c '{name, authenticated}'403
{"name":"admin","authenticated":true}The instanceof check makes the script safe to leave in place: on later starts the security realm already exists, so it does nothing and won't reset a password someone changed in the UI.
Using the backup script from this article, back up a controller that has at least one job with one build, restore the archive into an empty directory, start Jenkins on it, and show through the API that the job and its last build result survived.
Hint
Stop the original controller before starting the restored one if they share a port. The restored controller will run the same init.groovy.d scripts, which is fine because they check before changing anything.
Show Solution
./jenkins-backup.sh /home/sid/install-demo/backups
mkdir -p restore && tar -C restore -xzf backups/jenkins-home-*.tar.gz
export JENKINS_HOME="$PWD/restore"
java -Xmx512m -Djenkins.install.runSetupWizard=false -jar jenkins.war --httpPort=8094 --httpListenAddress=127.0.0.1curl -sS -u "admin:correct-horse-battery-staple" "http://127.0.0.1:8094/job/nightly-cleanup/api/json?tree=name,lastBuild%5Bnumber,result%5D" | jq -c .{"_class":"hudson.model.FreeStyleProject","name":"nightly-cleanup","lastBuild":{"_class":"hudson.model.FreeStyleBuild","number":1,"result":"SUCCESS"}}The admin password still works because users/ was restored, and the build history is intact because jobs/ was. If you had also excluded secrets/, the controller would start, but every stored credential would be unreadable. That is the classic half-working restore.
Tested with: Jenkins 2.580.2 (LTS) WAR on OpenJDK 21.0.13 (Temurin), Ubuntu 24.04 (WSL2), November 2026. The WAR download and checksum, the setup wizard start-up, skipping the wizard, the plugin manager run, the init.groovy.d scripts, the CLI setup, the backup, the restore and the --prefix exercise were all run as shown, on throwaway controllers bound to 127.0.0.1 and stopped afterwards. The Docker, apt, dnf, systemd, Windows MSI and Homebrew commands were not run (no Docker or root on the lab machine, and no Windows or macOS installs); they follow the official jenkins.io and pkg.jenkins.io instructions as of November 2026, and the Docker tag and apt signing key were checked with the read-only commands shown. Wizard screens were not clicked through; their contents were verified from the controller's HTTP responses. What surprised me: the CLI refuses to connect at all until the Jenkins URL is set, which is easy to hit when you skip the wizard. Paths from the test machine's scratch directories are shown shortened to /home/sid/….
Written by The Dark Debugger
Engineer documenting the things that took me too long to learn, so they take you less time. Every Jenkins tutorial here is tested end to end before publishing.