Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 40 ยท Meet Jenkins

Installing Jenkins

Install Jenkins with Docker, the WAR file, Linux packages or the Windows installer. Covers Java, ports, the first-run unlock, plugin setup and reverse proxies.

Jenkins is a Java program, so installing it comes down to three questions: where does Java come from, how does the program start (and restart after a reboot), and where does JENKINS_HOME live? There are four common answers: a Docker container, the plain WAR file, a Linux package, or the Windows installer. All of them end in the same place, a web page on port 8080 asking you to unlock Jenkins.

Everything in this lesson that touches a real machine is shown as read-only commands. A web page cannot start a server, so the runnable example is a small stand-in that checks the settings you would choose (port, home directory, Java version) the way a pre-flight checklist would.

Four ways to install

Docker One command, easy to throw away.
WAR file java -jar, great for a quick try.
Linux package Runs as a service with updates.
Windows installer A wizard that sets up the service.

Pick Docker for learning, a package or installer for a long-lived server.

1 / 2

Java requirements

Jenkins runs on the Java Virtual Machine. Each Jenkins release line supports only certain Java versions, and old ones are dropped regularly. At the time of writing, current releases need Java 17 or newer, and Java 21 is a safe, long-supported choice. Always read the requirements page for the exact version you install. Packages and the Docker image bring or declare a suitable Java for you; with the WAR file you supply it.

Terminal
java -version

If this prints a version older than what your Jenkins release needs, Jenkins will refuse to start and tell you so in its log.

Option 1: Docker (best for learning)

The official image contains Jenkins and a matching Java. Mount a volume for JENKINS_HOME, or you lose everything when the container is removed.

Terminal
docker run -d --name jenkins \
  -p 8080:8080 -p 50000:50000 \
  -v jenkins_home:/var/jenkins_home \
  --restart=on-failure \
  jenkins/jenkins:lts-jdk21
  • -p 8080:8080 publishes the web interface.
  • -p 50000:50000 is the port that classic inbound agents use to connect. You can leave it out if you only use SSH or WebSocket agents.
  • -v jenkins_home:/var/jenkins_home is a named volume that holds JENKINS_HOME.
  • The lts tag follows the Long-Term Support line, which gets fewer, more stable updates than the weekly releases. Prefer LTS for anything you rely on.

Docker basics are covered in the Docker tutorial (see especially its CI lesson). Note that a Jenkins container that must run Docker builds needs extra setup, discussed in Docker Agents and Building Images.

Option 2: the WAR file

Jenkins is distributed as one file, jenkins.war, with a built-in web server. After downloading it from the official site:

Terminal
export JENKINS_HOME=$HOME/jenkins-data
java -jar jenkins.war --httpPort=8080

This runs in your terminal and stops when you close it. It is the fastest way to try Jenkins and a poor way to run it permanently, because nothing restarts it. If you do not set JENKINS_HOME, Jenkins uses a .jenkins folder in your home directory.

Option 3: a Linux package

The Jenkins project publishes apt (Debian, Ubuntu) and yum/dnf (Fedora, RHEL) repositories. The steps are always the same: add the repository and its signing key, install Java, install the jenkins package. The exact lines change over time, so copy them from the official installation page rather than from a tutorial.

After installation Jenkins is a systemd service:

Terminal
sudo systemctl enable --now jenkins   # start now and at every boot
sudo systemctl status jenkins         # is it running?
sudo journalctl -u jenkins -f         # follow the log

Package installs run as a dedicated jenkins user and keep data in /var/lib/jenkins. Because it comes from a repository, apt upgrade also updates Jenkins, which makes security updates easy.

Option 4: the Windows installer

Download the .msi installer, run it, choose a service account, a port and the Java location. Jenkins is installed as a Windows service and JENKINS_HOME is a folder you choose during setup. Everything after that (browser unlock, plugins) is identical to the other options.

First run: unlock and set up

Open http://localhost:8080. Jenkins shows an Unlock Jenkins page. The one-time administrator password is printed in the startup log and stored in a file:

Terminal
# Docker
docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword

# Linux package
sudo cat /var/lib/jenkins/secrets/initialAdminPassword

Then:

  1. Customize Jenkins. Choose Install suggested plugins if you are learning. It installs Git, Pipeline, credentials and other basics. Choose Select plugins to install if you want a minimal set.
  2. Create the first admin user. Use a real account instead of staying on the temporary password.
  3. Instance configuration. Confirm the Jenkins URL. Jenkins puts this URL in emails and webhook links, so it should be the address people really use, not localhost.

Do not expose a fresh Jenkins to the internet before you have created your own admin user and reviewed its security settings. An open Jenkins with a script console is effectively a remote shell on your server. See Security, Users and Authorization.

Ports and a reverse proxy

Jenkins listens on 8080 by default. People usually put a reverse proxy such as nginx in front, to serve HTTPS on port 443. Two details cause most trouble: the proxy must forward the Host and protocol headers, and the Jenkins URL setting must match the public address. A minimal read-only nginx sketch:

NGINX
server {
  listen 443 ssl;
  server_name jenkins.example.com;

  location / {
    proxy_pass         http://127.0.0.1:8080;
    proxy_set_header   Host              $host;
    proxy_set_header   X-Real-IP         $remote_addr;
    proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header   X-Forwarded-Proto $scheme;
    proxy_read_timeout 90s;
  }
}

If you see Jenkins warn "It appears that your reverse proxy set up is broken", the headers or the Jenkins URL are usually the reason.

A stand-in pre-flight checker

The code below is a stand-in, not part of Jenkins. It models the checklist you just read: is Java new enough, is the port free, is JENKINS_HOME set to somewhere persistent, and is the public URL consistent with the proxy? Change the values and run it again.

JS A stand-in install pre-flight checker

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Plan A passes. Plan B trips five checks: old Java, a busy port, a temporary home directory, a URL that says localhost, and a URL that is not HTTPS. Real Jenkins reports similar problems in its startup log and its "Manage Jenkins" warnings, which you will see in A Tour of the Jenkins Interface.

Keep JENKINS_HOME safe from day one

Whatever method you choose, decide early where JENKINS_HOME lives, how it is backed up and how big the disk is. Moving it later is possible but annoying. The checklist is short: use a real disk or volume (not /tmp), schedule backups (see Backup, Monitoring and Troubleshooting), and monitor free space.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why must a Docker-based Jenkins mount a volume at /var/jenkins_home?

    JENKINS_HOME contains all state. A container's own filesystem disappears with the container, a named volume does not.
  2. 2. Where do you find the first-run administrator password?

    Jenkins generates a random one-time password and writes it to that file and to its log.
  3. 3. What does the 'lts' tag or package line give you?

    LTS releases are chosen for stability and receive backported fixes, which is why they are recommended for production.
  4. 4. Behind an HTTPS reverse proxy, which setting must match the address users type?

    Jenkins builds links for emails, webhooks and redirects from this URL. If it says localhost, links and proxy checks break.

Summary

  • Jenkins needs a supported Java; check the requirements for your release and prefer the LTS line.
  • Docker is the easiest way to learn; Linux packages and the Windows installer give you a managed service; the WAR file is for quick trials.
  • Always persist JENKINS_HOME on a real volume or disk.
  • First run: unlock with the initial admin password, install plugins, create your own admin and confirm the Jenkins URL.
  • Behind a reverse proxy, forward the host and protocol headers and keep the Jenkins URL accurate.

Now that Jenkins is running, find your way around in A Tour of the Jenkins Interface.