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 -version
openjdk 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 --version
total 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.2

Never 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 --help
Running 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.1

For 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 running

The same password is in a file only the Jenkins user can read:

cat home/secrets/initialAdminPassword
ls -l home/secrets
074d325b8bfd4c89b0c6e0f65da19aa9
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.key

Until 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 -16
HTTP/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: chunked

In 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:

  1. Customize Jenkins. Choose Install suggested plugins or Select plugins to install.
  2. Create First Admin User. Create your real account. The generated password stops working once you finish.
  3. 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).
  4. 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-theme

That 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.1
curl -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
mailer
time 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/plugins
Done
 
real	0m10.875s
user	0m25.747s
sys	0m6.075s
79
61M	skip-home/plugins

Twelve 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.1
grep 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/initialAdminPassword

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

Upgrading 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 jenkins

Two 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 bat or powershell steps instead of sh.
  • macOS: Homebrew packages the LTS line as jenkins-lts. Install with brew install jenkins-lts and run with brew 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.jar

The 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 version
Authenticated as: admin
Authorities:
  authenticated
2.580.2

The 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 ~/.jenkins
total 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
PathWhat it holdsBack it up?
config.xmlGlobal settings: security realm, authorization, executors, viewsYes
*.xml at the top levelSettings 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 artifactsYes, it is the history
users/User accounts, password hashes, API token hashesYes
credentials.xmlStored credentials, encryptedYes, together with secrets/
secrets/, secret.keyKeys that decrypt credentials, including secrets/master.keyYes, and protect the backup
nodes/Agent definitionsYes
plugins/Plugin archives (.jpi) and their unpacked directoriesOptional if you keep plugins.txt
fingerprints/Checksums of archived artifacts and where they were usedOptional
init.groovy.d/Start-up scriptsYes, or keep them in git
workspace/Build working directoriesNo, rebuilt by the next build
war/The unpacked WARNo
caches/, updates/, logs/Git caches, update-center metadata, task logsNo

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 -h
4.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_HOME on 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 -Xmx512m because 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 shows OutOfMemoryError or 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.xml

The 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.1
curl -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 plus credentials.xml can 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:

  1. Take a backup, and know how to restore it (above).
  2. Read the LTS upgrade guide for every version you are skipping. It lists breaking changes, such as the Java 17 removal.
  3. 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.lastExecVersion
2.580.2

Where you'll use this

A typical small-team controller, end to end:

  1. 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.
  2. Jenkins bound to 127.0.0.1 (JENKINS_LISTEN_ADDRESS in the systemd override), behind nginx or another reverse proxy that terminates TLS for https://ci.example.com/.
  3. The setup wizard completed once by the administrator, or skipped in favour of plugins.txt plus Configuration as Code so the controller can be rebuilt from git.
  4. The built-in node's executors set to 0 and all builds on agents (Agents and Distributed Builds).
  5. 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.xml
CLI 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: nosniff

The 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 -s
Authenticated as: admin
Authorities:
  authenticated
  FACTOR_PASSWORD
Started nightly-cleanup #1
Completed nightly-cleanup #1 : SUCCESS

The 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 Jetty

The 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_HOME and --httpPort are 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 with runSetupWizard=false leaves 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 the jenkins.io-2026.key signing key.
  • Use API tokens, not passwords, for the CLI and REST API. The CLI reads JENKINS_URL, JENKINS_USER_ID and JENKINS_API_TOKEN, and refuses to connect until the Jenkins URL is configured.
  • Back up config.xml, jobs/, users/, nodes/, credentials.xml and secrets/; skip workspace/, war/ and caches. Protect the backup, because it can decrypt your credentials, and test the restore.

Exercises

Exercise 1: Verify what you downloadedeasy

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 --version
jenkins.war: OK
2.580.2

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

Exercise 2: Serve Jenkins under a path prefixmedium

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=/jenkins

From 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 404

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

Exercise 3: Secure a controller without the wizardmedium

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.1
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}'
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.

Exercise 4: Prove your backup restoreshard

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.1
curl -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/….

Was this page helpful?
The Dark Debugger

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.