Jenkins User Documentation Home

Guided Tour

Tutorials

User Handbook (PDF)

Resources

Recent Tutorial Blog Posts
View all tutorial blog posts

Index

Installing Jenkins

The procedures on this page are for new installations of Jenkins on a single/local machine.

Jenkins is typically run as a standalone application in its own process with the built-in Java servlet container/application server (Jetty).

Jenkins can also be run as a servlet in different Java servlet containers such as Apache Tomcat or GlassFish. However, instructions for setting up these types of installations are beyond the scope of this page.

Note: Although this page focuses on local installations of Jenkins, this content can also be used to help set up Jenkins in production environments.

Prerequisites

Minimum hardware requirements:

  • 256 MB of RAM

  • 1 GB of drive space (although 10 GB is a recommended minimum if running Jenkins as a Docker container)

Recommended hardware configuration for a small team:

  • 1 GB+ of RAM

  • 50 GB+ of drive space

Software requirements:

Installation platforms

This section describes how to install/run Jenkins on different platforms and operating systems.

Docker

Docker is a platform for running applications in an isolated environment called a "container" (or Docker container). Applications like Jenkins can be downloaded as read-only "images" (or Docker images), each of which is run in Docker as a container. A Docker container is in effect a "running instance" of a Docker image. From this perspective, an image is stored permanently more or less (i.e. insofar as image updates are published), whereas containers are stored temporarily. Read more about these concepts in the Docker documentation’s Getting Started, Part 1: Orientation and setup page.

Docker’s fundamental platform and container design means that a single Docker image (for any given application like Jenkins) can be run on any supported operating system (macOS, Linux and Windows) or cloud service (AWS and Azure) which is also running Docker.

Installing Docker

To install Docker on your operating system, visit the Docker store website and click the Docker Community Edition box which is suitable for your operating system or cloud service. Follow the installation instructions on their website.

Jenkins can also run on Docker Enterprise Edition, which you can access through Docker EE on the Docker store website.

If you are installing Docker on a Linux-based operating system, ensure you configure Docker so it can be managed as a non-root user. Read more about this in Docker’s Post-installation steps for Linux page of their documentation. This page also contains information about how to configure Docker to start on boot.

Downloading and running Jenkins in Docker

There are several Docker images of Jenkins available.

The recommended Docker image to use is the jenkinsci/blueocean image (from the Docker Hub repository). This image contains the current Long-Term Support (LTS) release of Jenkins (which is production-ready) bundled with all Blue Ocean plugins and features. This means that you do not need to install the Blue Ocean plugins separately.

A new jenkinsci/blueocean image is published each time a new release of Blue Ocean is published. You can see a list of previously published versions of the jenkinsci/blueocean image on the tags page.

There are also other Jenkins Docker images you can use (accessible through jenkins/jenkins on Docker Hub). However, these do not come with Blue Ocean, which would need to be installed via the Manage Jenkins > Manage Plugins page in Jenkins. Read more about this in Getting started with Blue Ocean.
On macOS and Linux

  1. Open up a terminal window.

  2. Download the jenkinsci/blueocean image and run it as a container in Docker using the following docker run command:

    docker run \
  -u root \
  --rm \  (1)
  -d \ (2)
  -p 8080:8080 \ (3)
  -p 50000:50000 \ (4)
  -v jenkins-data:/var/jenkins_home \ (5)
  -v /var/run/docker.sock:/var/run/docker.sock \ (6)
  jenkinsci/blueocean (7)
    1 ( Optional ) Automatically removes the Docker container (which is the instantiation of the jenkinsci/blueocean image below) when it is shut down. This keeps things tidy if you need to quit Jenkins.
    2 ( Optional ) Runs the jenkinsci/blueocean container in the background (i.e. "detached" mode) and outputs the container ID. If you do not specify this option, then the running Docker log for this container is output in the terminal window.
    3 Maps (i.e. "publishes") port 8080 of the jenkinsci/blueocean container to port 8080 on the host machine. The first number represents the port on the host while the last represents the container’s port. Therefore, if you specified -p 49000:8080 for this option, you would be accessing Jenkins on your host machine through port 49000.
    4 ( Optional ) Maps port 50000 of the jenkinsci/blueocean container to port 50000 on the host machine. This is only necessary if you have set up one or more JNLP-based Jenkins agents on other machines, which in turn interact with the jenkinsci/blueocean container (acting as the "master" Jenkins server, or simply "Jenkins master"). JNLP-based Jenkins agents communicate with the Jenkins master through TCP port 50000 by default. You can change this port number on your Jenkins master through the Configure Global Security page. If you were to change your Jenkins master’s TCP port for JNLP agents value to 51000 (for example), then you would need to re-run Jenkins (via this docker run …​ command) and specify this "publish" option with something like -p 52000:51000, where the last value matches this changed value on the Jenkins master and the first value is the port number on the Jenkins master’s host machine through which the JNLP-based Jenkins agents communicate (to the Jenkins master) - i.e. 52000.
    5 ( Optional but highly recommended ) Maps the /var/jenkins_home directory in the container to the Docker volume with the name jenkins-data. If this volume does not exist, then this docker run command will automatically create the volume for you. This option is required if you want your Jenkins state to persist each time you restart Jenkins (via this docker run …​ command). If you do not specify this option, then Jenkins will effectively reset to a new instance after each restart.
    Notes: The jenkins-data volume could also be created independently using the docker volume create command:
    docker volume create jenkins-data
    Instead of mapping the /var/jenkins_home directory to a Docker volume, you could also map this directory to one on your machine’s local file system. For example, specifying the option
    -v $HOME/jenkins:/var/jenkins_home would map the container’s /var/jenkins_home directory to the jenkins subdirectory within the $HOME directory on your local machine, which would typically be /Users/<your-username>/jenkins or /home/<your-username>/jenkins.
    6 ( Optional ) /var/run/docker.sock represents the Unix-based socket through which the Docker daemon listens on. This mapping allows the jenkinsci/blueocean container to communicate with the Docker daemon, which is required if the jenkinsci/blueocean container needs to instantiate other Docker containers. This option is necessary if you run declarative Pipelines whose syntax contains the agent section with the docker parameter - i.e.
    agent { docker { …​ } }. Read more about this on the Pipeline Syntax page.
    7 The jenkinsci/blueocean Docker image itself. If this image has not already been downloaded, then this docker run command will automtically download the image for you. Furthermore, if any updates to this image were published since you last ran this command, then running this command again will automatically download these published image updates for you.
    Note: This Docker image could also be downloaded (or updated) independently using the docker pull command:
    docker pull jenkinsci/blueocean

    Note: If copying and pasting the command snippet above does not work, try copying and pasting this annotation-free version here:

    docker run \
  -u root \
  --rm \
  -d \
  -p 8080:8080 \
  -p 50000:50000 \
  -v jenkins-data:/var/jenkins_home \
  -v /var/run/docker.sock:/var/run/docker.sock \
  jenkinsci/blueocean

  3. Proceed to the Post-installation setup wizard.

On Windows

  1. Open up a command prompt window.

  2. Download the jenkinsci/blueocean image and run it as a container in Docker using the following docker run command:

    docker run ^
  -u root ^
  --rm ^
  -d ^
  -p 8080:8080 ^
  -p 50000:50000 ^
  -v jenkins-data:/var/jenkins_home ^
  -v /var/run/docker.sock:/var/run/docker.sock ^
  jenkinsci/blueocean

    For an explanation of each of these options, refer to the macOS and Linux instructions above.

  3. Proceed to the Post-installation setup wizard.

Accessing the Jenkins/Blue Ocean Docker container

If you have some experience with Docker and you wish or need to access the jenkinsci/blueocean container through a terminal/command prompt using the docker exec command, you can add an option like --name jenkins-blueocean (with the docker run above), which would give the jenkinsci/blueocean container the name "jenkins-blueocean".

This means you could access the container (through a separate terminal/command prompt window) with a docker exec command like:

docker exec -it jenkins-blueocean bash

Accessing the Jenkins console log through Docker logs

There is a possibility you may need to access the Jenkins console log, for instance, when Unlocking Jenkins as part of the Post-installation setup wizard.

If you did not specify the detached mode option -d with the docker run …​ command above, then the Jenkins console log is easily accessible through the terminal/command prompt window from which you ran this Docker command.

Otherwise, you can access the Jenkins console log through the Docker logs of the jenkinsci/blueocean container using the following command:

docker logs <docker-container-name>

Your <docker-container-name> can be obtained using the docker ps command. If you specified the
--name jenkins-blueocean option in the docker run …​ command above (see also Accessing the Jenkins/Blue Ocean Docker container), you can simply use the docker logs command:

docker logs jenkins-blueocean

Accessing the Jenkins home directory

There is a possibility you may need to access the Jenkins home directory, for instance, to check the details of a Jenkins build in the workspace subdirectory.

If you mapped the Jenkins home directory (/var/jenkins_home) to one on your machine’s local file system (i.e. in the docker run …​ command above), then you can access the contents of this directory through your machine’s usual terminal/command prompt.

Otherwise, if you specified the -v jenkins-data:/var/jenkins_home option in the docker run …​ command, you can access the contents of the Jenkins home directory through the jenkinsci/blueocean container’s terminal/command prompt using the docker exec command:

docker exec -it <docker-container-name> bash

As mentioned above, your <docker-container-name> can be obtained using the docker ps command. If you specified the
--name jenkins-blueocean option in the docker run …​ command above (see also Accessing the Jenkins/Blue Ocean Docker container), you can simply use the docker exec command:

docker exec -it jenkins-blueocean bash

WAR file

The Web application ARchive (WAR) file version of Jenkins can be installed on any operating system or platform that supports Java.

To download and run the WAR file version of Jenkins:

  1. Download the latest stable Jenkins WAR file to an appropriate directory on your machine.

  2. Open up a terminal/command prompt window to the download directory.

  3. Run the command java -jar jenkins.war.

  4. Browse to http://localhost:8080 and wait until the Unlock Jenkins page appears.

  5. Continue on with the Post-installation setup wizard below.

Notes:

  • Unlike downloading and running Jenkins with Blue Ocean in Docker (above), this process does not automatically install the Blue Ocean features, which would need to installed separately via the Manage Jenkins > Manage Plugins page in Jenkins. Read more about the specifics for installing Blue Ocean on the Getting started with Blue Ocean page.

  • You can change the port by specifying the --httpPort option when you run the java -jar jenkins.war command. For example, to make Jenkins accessible through port 9090, then run Jenkins using the command:
    java -jar jenkins.war --httpPort=9090

macOS

To install from the website, using a package:

Jenkins can also be installed using brew:

  • Install the latest release version

brew install jenkins

  • Install the LTS version

brew install jenkins-lts

Linux

Debian/Ubuntu

On Debian-based distributions, such as Ubuntu, you can install Jenkins through apt.

Recent versions are available in an apt repository. Older but stable LTS versions are in this apt repository.

wget -q -O - https://pkg.jenkins.io/debian/jenkins.io.key | sudo apt-key add -
sudo sh -c 'echo deb http://pkg.jenkins.io/debian-stable binary/ > /etc/apt/sources.list.d/jenkins.list'
sudo apt-get update
sudo apt-get install jenkins

This package installation will:

  • Setup Jenkins as a daemon launched on start. See /etc/init.d/jenkins for more details.

  • Create a ‘jenkins’ user to run this service.

  • Direct console log output to the file /var/log/jenkins/jenkins.log. Check this file if you are troubleshooting Jenkins.

  • Populate /etc/default/jenkins with configuration parameters for the launch, e.g JENKINS_HOME

  • Set Jenkins to listen on port 8080. Access this port with your browser to start configuration.

If your /etc/init.d/jenkins file fails to start Jenkins, edit the /etc/default/jenkins to replace the line ----HTTP_PORT=8080---- with ----HTTP_PORT=8081---- Here, "8081" was chosen but you can put another port available.

Fedora

You can install Jenkins through dnf. You need to add the Jenkins repository from the Jenkins website to the package manager first.

sudo wget -O /etc/yum.repos.d/jenkins.repo http://pkg.jenkins-ci.org/redhat/jenkins.repo
sudo rpm --import https://jenkins-ci.org/redhat/jenkins-ci.org.key

Then, you can install Jenkins. The following command also ensures you have java installed.

sudo dnf upgrade && sudo dnf install jenkins java

Next, start the Jenkins service.

sudo service jenkins start
sudo chkconfig jenkins on

You can check the status of the Jenkins service using this systemctl command:

systemctl status jenkins

If everything has been set up correctly, you should see an output like this:

Loaded: loaded (/etc/rc.d/init.d/jenkins; generated)
Active: active (running) since Tue 2018-11-13 16:19:01 +03; 4min 57s ago
...

If you have a firewall installed, you must add Jenkins as an exception. You must change YOURPORT in the script below to the port you want to use. Port 8080 is the most common.

firewall-cmd --permanent --new-service=jenkins
firewall-cmd --permanent --service=jenkins --set-short="Jenkins Service Ports"
firewall-cmd --permanent --service=jenkins --set-description="Jenkins service firewalld port exceptions"
firewall-cmd --permanent --service=jenkins --add-port=YOURPORT/tcp
firewall-cmd --permanent --add-service=jenkins
firewall-cmd --zone=public --add-service=http --permanent
firewall-cmd --reload

Windows

To install from the website, using the installer:

Other operating systems

OpenIndiana Hipster

On a system running OpenIndiana Hipster Jenkins can be installed in either the local or global zone using the Image Packaging System (IPS).

Disclaimer: This platform is NOT officially supported by the Jenkins team, use it at your own risk. Packaging and integration described in this section is maintained by the OpenIndiana Hipster team, bundling the generic jenkins.war to work in that operating environment.

For the common case of running the newest packaged weekly build as a standalone (Jetty) server, simply execute:

pkg install jenkins
svcadm enable jenkins

The common packaging integration for a standalone service will:

  • Create a jenkins user to run the service and to own the directory structures under /var/lib/jenkins.

  • Pull the OpenJDK8 and other packages required to execute Jenkins, including the jenkins-core-weekly package with the latest jenkins.war.

    Long-Term Support (LTS) Jenkins releases currently do not support OpenZFS-based systems, so no packaging is provided at this time.

  • Set up Jenkins as an SMF service instance (svc:/network/http:jenkins) which  can then be enabled with the svcadm command demonstrated above.

  • Set up Jenkins to listen on port 8080.

  • Configure the log output to be managed by SMF at /var/svc/log/network-http:jenkins.log.

Once Jenkins is running, consult the log (/var/svc/log/network-http:jenkins.log) to retrieve the generated administrator password for the initial set up of Jenkins, usually it will be found at /var/lib/jenkins/home/secrets/initialAdminPassword. Then navigate to localhost:8080 to complete configuration of the Jenkins instance.

To change attributes of the service, such as environment variables like JENKINS_HOME or the port number used for the Jetty web server, use the svccfg utility:

svccfg -s svc:/network/http:jenkins editprop
svcadm refresh svc:/network/http:jenkins

You can also refer to /lib/svc/manifest/network/jenkins-standalone.xml for more details and comments about currently supported tunables of the SMF service. Note that the jenkins user account created by the packaging is specially privileged to allow binding to port numbers under 1024.

The current status of Jenkins-related packages available for the given release of OpenIndiana can be queried with:

pkg info -r '*jenkins*'

Upgrades to the package can be performed by updating the entire operating environment with pkg update, or specifically for Jenkins core software with:

pkg update jenkins-core-weekly

Procedure for updating the package will restart the currently running Jenkins process. Make sure to prepare it for shutdown and finish all running jobs before updating, if needed.

Solaris, OmniOS, SmartOS, and other siblings

Generally it should suffice to install Java 8 and download the jenkins.war and run it as a standalone process or under an application server such as Apache Tomcat.

Some caveats apply:

  • Headless JVM and fonts: For OpenJDK builds on minimalized-footprint systems, there may be issues running the headless JVM, because Jenkins needs some fonts to render certain pages.

  • ZFS-related JVM crashes: When Jenkins runs on a system detected as a SunOS, it tries to load integration for advanced ZFS features using the bundled libzfs.jar which maps calls from Java to native libzfs.so routines provided by the host OS. Unfortunately, that library was made for binary utilities built and bundled by the OS along with it at the same time, and was never intended as a stable interface exposed to consumers. As the forks of Solaris legacy, including ZFS and later the OpenZFS initiative evolved, many different binary function signatures were provided by different host operating systems - and when Jenkins libzfs.jar invoked the wrong signature, the whole JVM process crashed. A solution was proposed and integrated in jenkins.war since weekly release 2.55 (and not yet in any LTS to date) which enables the administrator to configure which function signatures should be used for each function known to have different variants, apply it to their application server initialization options and then run and update the generic jenkins.war without further workarounds. See the libzfs4j Git repository for more details, including a script to try and "lock-pick" the configuration needed for your particular distribution (in particular if your kernel updates bring a new incompatible libzfs.so).

Also note that forks of the OpenZFS initiative may provide ZFS on various BSD, Linux, and macOS distributions. Once Jenkins supports detecting ZFS capabilities, rather than relying on the SunOS check, the above caveats for ZFS integration with Jenkins should be considered.

Post-installation setup wizard

After downloading, installing and running Jenkins using one of the procedures above, the post-installation setup wizard begins.

This setup wizard takes you through are a few quick "one-off" steps to unlock Jenkins, customize it with plugins and create the first administrator user through which you can continue accessing Jenkins.

Unlocking Jenkins

When you first access a new Jenkins instance, you are asked to unlock it using an automatically-generated password.

  1. Browse to http://localhost:8080 (or whichever port you configured for Jenkins when installing it) and wait until the Unlock Jenkins page appears.

    Unlock Jenkins page

  2. From the Jenkins console log output, copy the automatically-generated alphanumeric password (between the 2 sets of asterisks).

    Copying initial admin password

  3. On the Unlock Jenkins page, paste this password into the Administrator password field and click Continue.
    Notes:

    • If you ran Jenkins in Docker in detached mode, you can access the Jenkins console log from the Docker logs (above).

    • The Jenkins console log indicates the location (in the Jenkins home directory) where this password can also be obtained. This password must be entered in the setup wizard on new Jenkins installations before you can access Jenkins’s main UI. This password also serves as the default admininstrator account’s password (with username "admin") if you happen to skip the subsequent user-creation step in the setup wizard.

Customizing Jenkins with plugins

After unlocking Jenkins, the Customize Jenkins page appears. Here you can install any number of useful plugins as part of your initial setup.

Click one of the two options shown:

  • Install suggested plugins - to install the recommended set of plugins, which are based on most common use cases.

  • Select plugins to install - to choose which set of plugins to initially install. When you first access the plugin selection page, the suggested plugins are selected by default.

If you are not sure what plugins you need, choose Install suggested plugins. You can install (or remove) additional Jenkins plugins at a later point in time via the Manage Jenkins > Manage Plugins page in Jenkins.

The setup wizard shows the progression of Jenkins being configured and your chosen set of Jenkins plugins being installed. This process may take a few minutes.

Creating the first administrator user

Finally, after customizing Jenkins with plugins, Jenkins asks you to create your first administrator user.

  1. When the Create First Admin User page appears, specify the details for your administrator user in the respective fields and click Save and Finish.

  2. When the Jenkins is ready page appears, click Start using Jenkins.
    Notes:

    • This page may indicate Jenkins is almost ready! instead and if so, click Restart.

    • If the page does not automatically refresh after a minute, use your web browser to refresh the page manually.

  3. If required, log in to Jenkins with the credentials of the user you just created and you are ready to start using Jenkins!

From this point on, the Jenkins UI is only accessible by providing valid username and password credentials.
Index

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

    


See existing feedback here.