Installing Jenkins

This is still very much a work in progress

This section is part of Getting Started. It provides instructions for basic Jenkins configuration on a number of platforms. It DOES NOT cover the full range of considerations or options for installing Jenkins. See Advanced Jenkins Installation

Overview

Pre-install

System Requirements

These are starting points. For a full discussion of factors see Discussion of hardware recommendations.

Minimum Recommended Configuration:

  • Java 8 (either JRE or JDK)

    • Note: Since Jenkins weekly 2.77, a JRE compatible with Let’s Encrypt! is needed for default Jenkins Update Center connectivity. Oracle JRE 8u101 is a known sufficient version, while earlier releases would fail and claim they are offline.

  • 256MB free memory

  • 1GB+ free disk space

Recommended Configuration for Small Team:

  • Java 8

  • 1GB+ free memory

  • 50GB+ free disk space

Experimentation, Staging, or Production?

How you configure Jenkins will differ significantly depending on your intended use cases. This section is specifically targeted to initial use and experimentation. For other scenarios, see Advanced Jenkins Installation.

Stand-alone or Servlet?

Jenkins can run stand-alone in its own process using its own built-in web server (Jetty). It can also run as one servlet in an existing framework, such as Tomcat or Glassfish application servers. This section is specifically targeted to stand-alone install and execution. For other scenarios, see Advanced Jenkins Installation

Installation

These are clean install instructions for non-production environments. If you have a non-production Jenkins server already running on a system and want to upgrade, see Upgrading Jenkins. If you are installing or upgrading a production Jenkins server, see Advanced Jenkins Installation.

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

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.

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

Windows

To install from the website, using the installer:

Docker

You must have Docker properly installed on your machine. See the Docker installation guide for details.

First, pull the official jenkins image from Docker repository.

docker pull jenkins/jenkins

Next, run a container using this image and map data directory from the container to the host; e.g in the example below /var/jenkins_home from the container is mapped to jenkins/ directory from the current path on the host. Jenkins 8080 port is also exposed to the host as 49001.

docker run -d -p 49001:8080 -v $PWD/jenkins:/var/jenkins_home -t jenkins/jenkins

Post-install (Setup Wizard)

Create Admin User and Password for Jenkins

Jenkins is initially configured to be secure on first launch. Jenkins can no longer be accessed without a username and password and open ports are limited. During the initial run of Jenkins a security token is generated and printed in the console log:

*************************************************************

Jenkins initial setup is required. A security token is required to proceed.
Please use the following security token to proceed to installation:

41d2b60b0e4cb5bf2025d33b21cb

*************************************************************

The install instructions for each of the platforms above includes the default location for when you can find this log output. This token must be entered in the "Setup Wizard" the first time you open the Jenkins UI. This token will also serve as the default password for the user admin if you skip the user-creation step in the Setup Wizard.

Initial Plugin Installation

The Setup Wizard will also install the initial plugins for this Jenkins server. The recommended set of plugins available are based on the most common use cases. You are free to add more during the Setup Wizard or install them later as needed.