Welcome to Knowledge Base!

KB at your finger tips

This is one stop global knowledge base where you can learn about all the products, solutions and support features.

DevOps-Jenkins

Jenkins Handbook

Up to all documentation

Docker

â Installing Jenkins Index

Kubernetes â

Docker

Table of Contents

Installing Docker
Prerequisites
- Downloading and running Jenkins in Docker
- On macOS and Linux
- On Windows
Accessing the Docker container
Accessing the Docker logs
Accessing the Jenkins home directory
Post-installation setup wizard
- Unlocking Jenkins
- Customizing Jenkins with plugins
- Creating the first administrator user

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, follow "prerequisites" section of the Guided Tour page

As an alternative solution you can visit the Dockerhub and select the Docker Community Edition suitable for your operating system or cloud service. Follow the installation instructions on their 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.

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:

4 GB+ of RAM
50 GB+ of drive space

Comprehensive hardware recommendations:

Hardware: see the Hardware Recommendations page

Software requirements:

Java: see the Java Requirements page
Web browser: see the Web Browser Compatibility page
For Windows operating system: Windows Support Policy
For Linux operating system: Linux Support Policy
For servlet containers: Servlet Container Support Policy

Downloading and running Jenkins in Docker

There are several Docker images of Jenkins available.

The recommended Docker image to use is the Official jenkins/jenkins image (from the Docker Hub repository). This image contains the current Long-Term Support (LTS) release of Jenkins (which is production-ready). However this image doesn’t have docker CLI inside it and is not bundled with frequently used Blue Ocean plugins and features. This means that if you want to use the full power of Jenkins and Docker you may want to go through described below installation process.

A new jenkins/jenkins image is published each time a new release of Jenkins Docker is published. You can see a list of previously published versions of the jenkins/jenkins image on the tags page.

On macOS and Linux

Open up a terminal window.
Create a bridge network in Docker using the following docker network create command:
```
docker network create jenkins
```

In order to execute Docker commands inside Jenkins nodes, download and run the docker:dind Docker image using the following docker run command:

docker run \
  --name jenkins-docker \(1)
  --rm \(2)
  --detach \(3)
  --privileged \(4)
  --network jenkins \(5)
  --network-alias docker \(6)
  --env DOCKER_TLS_CERTDIR=/certs \(7)
  --volume jenkins-docker-certs:/certs/client \(8)
  --volume jenkins-data:/var/jenkins_home \(9)
  --publish 2376:2376 \(10)
  docker:dind \(11)
  --storage-driver overlay2(12)

1	( Optional ) Specifies the Docker container name to use for running the image. By default, Docker will generate a unique name for the container.
2	( Optional ) Automatically removes the Docker container (the instance of the Docker image) when it is shut down.
3	( Optional ) Runs the Docker container in the background. This instance can be stopped later by running `docker stop jenkins-docker` .
4	Running Docker in Docker currently requires privileged access to function properly. This requirement may be relaxed with newer Linux kernel versions.
5	This corresponds with the network created in the earlier step.
6	Makes the Docker in Docker container available as the hostname `docker` within the `jenkins` network.
7	Enables the use of TLS in the Docker server. Due to the use of a privileged container, this is recommended, though it requires the use of the shared volume described below. This environment variable controls the root directory where Docker TLS certificates are managed.
8	Maps the `/certs/client` directory inside the container to a Docker volume named `jenkins-docker-certs` as created above.
9	Maps the `/var/jenkins_home` directory inside the container to the Docker volume named `jenkins-data` . This will allow for other Docker containers controlled by this Docker container’s Docker daemon to mount data from Jenkins.
10	( Optional ) Exposes the Docker daemon port on the host machine. This is useful for executing `docker` commands on the host machine to control this inner Docker daemon.
11	The `docker:dind` image itself. This image can be downloaded before running by using the command: `docker image pull docker:dind` .
12	The storage driver for the Docker volume. See "Docker storage drivers" for supported options.

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

docker run --name jenkins-docker --rm --detach \
  --privileged --network jenkins --network-alias docker \
  --env DOCKER_TLS_CERTDIR=/certs \
  --volume jenkins-docker-certs:/certs/client \
  --volume jenkins-data:/var/jenkins_home \
  --publish 2376:2376 \
  docker:dind --storage-driver overlay2

Customise official Jenkins Docker image, by executing below two steps:

Create Dockerfile with the following content:

FROM jenkins/jenkins:2.375.1
USER root
RUN apt-get update && apt-get install -y lsb-release
RUN curl -fsSLo /usr/share/keyrings/docker-archive-keyring.asc \
  https://download.docker.com/linux/debian/gpg
RUN echo "deb [arch=$(dpkg --print-architecture) \
  signed-by=/usr/share/keyrings/docker-archive-keyring.asc] \
  https://download.docker.com/linux/debian \
  $(lsb_release -cs) stable" > /etc/apt/sources.list.d/docker.list
RUN apt-get update && apt-get install -y docker-ce-cli
USER jenkins
RUN jenkins-plugin-cli --plugins "blueocean:1.26.0 docker-workflow:563.vd5d2e5c4007f"

Build a new docker image from this Dockerfile and assign the image a meaningful name, e.g. "myjenkins-blueocean:2.375.1-1":
```
docker build -t myjenkins-blueocean:2.375.1-1 .
```
Keep in mind that the process described above will automatically download the official Jenkins Docker image if this hasn’t been done before.

Run your own myjenkins-blueocean:2.375.1-1 image as a container in Docker using the following docker run command:

docker run \
  --name jenkins-blueocean \(1)
  --restart=on-failure \(2)
  --detach \(3)
  --network jenkins \(4)
  --env DOCKER_HOST=tcp://docker:2376 \(5)
  --env DOCKER_CERT_PATH=/certs/client \
  --env DOCKER_TLS_VERIFY=1 \
  --publish 8080:8080 \(6)
  --publish 50000:50000 \(7)
  --volume jenkins-data:/var/jenkins_home \(8)
  --volume jenkins-docker-certs:/certs/client:ro \(9)
  myjenkins-blueocean:2.375.1-1 (10)

1	( Optional ) Specifies the Docker container name for this instance of the Docker image.
2	Always restart the container if it stops. If it is manually stopped, it is restarted only when Docker daemon restarts or the container itself is manually restarted.
3	( Optional ) Runs the current 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.
4	Connects this container to the `jenkins` network defined in the earlier step. This makes the Docker daemon from the previous step available to this Jenkins container through the hostname `docker` .
5	Specifies the environment variables used by `docker` , `docker-compose` , and other Docker tools to connect to the Docker daemon from the previous step.
6	Maps (i.e. "publishes") port 8080 of the current 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.
7	( Optional ) Maps port 50000 of the current container to port 50000 on the host machine. This is only necessary if you have set up one or more inbound Jenkins agents on other machines, which in turn interact with your `jenkins-blueocean` container (the Jenkins "controller"). Inbound Jenkins agents communicate with the Jenkins controller through TCP port 50000 by default. You can change this port number on your Jenkins controller through the Configure Global Security page. If you were to change the TCP port for inbound Jenkins agents of your Jenkins controller 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 `--publish 52000:51000` , where the last value matches this changed value on the Jenkins controller and the first value is the port number on the machine hosting the Jenkins controller. Inbound Jenkins agents communicate with the Jenkins controller on that port (52000 in this example). Note that WebSocket agents do not need this configuration.
8	Maps the `/var/jenkins_home` directory in the container to the Docker volume with the name `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 `--volume $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` . Note that if you change the source volume or directory for this, the volume from the `docker:dind` container above needs to be updated to match this.
9	Maps the `/certs/client` directory to the previously created `jenkins-docker-certs` volume. This makes the client TLS certificates needed to connect to the Docker daemon available in the path specified by the `DOCKER_CERT_PATH` environment variable.
10	The name of the Docker image, which you built in the previous step.

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

docker run --name jenkins-blueocean --restart=on-failure --detach \
  --network jenkins --env DOCKER_HOST=tcp://docker:2376 \
  --env DOCKER_CERT_PATH=/certs/client --env DOCKER_TLS_VERIFY=1 \
  --publish 8080:8080 --publish 50000:50000 \
  --volume jenkins-data:/var/jenkins_home \
  --volume jenkins-docker-certs:/certs/client:ro \
  myjenkins-blueocean:2.375.1-1

Proceed to the Post-installation setup wizard.

On Windows

The Jenkins project provides a Linux container image, not a Windows container image. Be sure that your Docker for Windows installation is configured to run Linux Containers rather than Windows Containers . See the Docker documentation for instructions to switch to Linux containers. Once configured to run Linux Containers , the steps are:

Open up a command prompt window and similar to the macOS and Linux instructions above do the following:
Create a bridge network in Docker
```
docker network create jenkins
```

Run a docker:dind Docker image

docker run --name jenkins-docker --rm --detach ^
  --privileged --network jenkins --network-alias docker ^
  --env DOCKER_TLS_CERTDIR=/certs ^
  --volume jenkins-docker-certs:/certs/client ^
  --volume jenkins-data:/var/jenkins_home ^
  --publish 2376:2376 ^
  docker:dind

Customise official Jenkins Docker image, by executing below two steps:

Create Dockerfile with the following content:

FROM jenkins/jenkins:2.375.1
USER root
RUN apt-get update && apt-get install -y lsb-release
RUN curl -fsSLo /usr/share/keyrings/docker-archive-keyring.asc \
  https://download.docker.com/linux/debian/gpg
RUN echo "deb [arch=$(dpkg --print-architecture) \
  signed-by=/usr/share/keyrings/docker-archive-keyring.asc] \
  https://download.docker.com/linux/debian \
  $(lsb_release -cs) stable" > /etc/apt/sources.list.d/docker.list
RUN apt-get update && apt-get install -y docker-ce-cli
USER jenkins
RUN jenkins-plugin-cli --plugins "blueocean:1.26.0 docker-workflow:563.vd5d2e5c4007f"

Build a new docker image from this Dockerfile and assign the image a meaningful name, e.g. "myjenkins-blueocean:2.375.1-1":
```
docker build -t myjenkins-blueocean:2.375.1-1 .
```
Keep in mind that the process described above will automatically download the official Jenkins Docker image if this hasn’t been done before.

Run your own myjenkins-blueocean:2.375.1-1 image as a container in Docker using the following docker run command:

docker run --name jenkins-blueocean --restart=on-failure --detach ^
  --network jenkins --env DOCKER_HOST=tcp://docker:2376 ^
  --env DOCKER_CERT_PATH=/certs/client --env DOCKER_TLS_VERIFY=1 ^
  --volume jenkins-data:/var/jenkins_home ^
  --volume jenkins-docker-certs:/certs/client:ro ^
  --publish 8080:8080 --publish 50000:50000 myjenkins-blueocean:2.375.1-1

Proceed to the Setup wizard.

Accessing the Docker container

If you have some experience with Docker and you wish or need to access your Docker container through a terminal/command prompt using the docker exec command, you can add an option like --name jenkins-tutorial to the docker exec command. That will access the Jenkins Docker container named "jenkins-tutorial".

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

docker exec -it jenkins-blueocean bash

Accessing the 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.

The Jenkins console log is easily accessible through the terminal/command prompt window from which you executed the docker run … command. In case if needed you can also access the Jenkins console log through the Docker logs of your container using the following command:

docker logs <docker-container-name>

Your <docker-container-name> can be obtained using the docker ps command.

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 --volume jenkins-data:/var/jenkins_home option in the docker run … command, you can access the contents of the Jenkins home directory through your container’s terminal/command prompt using the docker container exec command:

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

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

docker container exec -it jenkins-blueocean bash

Post-installation setup wizard

After downloading, installing and running Jenkins using one of the procedures above (except for installation with Jenkins Operator), the post-installation setup wizard begins.

This setup wizard takes you through 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.

Browse to http://localhost:8080 (or whichever port you configured for Jenkins when installing it) and wait until the Unlock Jenkins page appears.
From the Jenkins console log output, copy the automatically-generated alphanumeric password (between the 2 sets of asterisks).

Note:
- The command: sudo cat /var/lib/jenkins/secrets/initialAdminPassword will print the password at console.
- If you are running Jenkins in Docker using the official jenkins/jenkins image you can use sudo docker exec ${CONTAINER_ID or CONTAINER_NAME} cat /var/jenkins_home/secrets/initialAdminPassword to print the password in the console without having to exec into the container.
On the Unlock Jenkins page, paste this password into the Administrator password field and click Continue .
Notes:
- You can always 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 administrator 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.

When the Create First Admin User page appears, specify the details for your administrator user in the respective fields and click Save and Finish .
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.
If required, log in to Jenkins with the credentials of the user you just created and you are ready to start using Jenkins!

â Installing Jenkins Index

Kubernetes â

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.

Read article

Installing Jenkins

â User Handbook Overview

Index

Docker â

Installing Jenkins

Chapter Sub-Sections

The procedures in this chapter are for new installations of Jenkins.

Jenkins is typically run as a standalone application in its own process. The Jenkins WAR file bundles Winstone, a Jetty servlet container wrapper, and can be started on any operating system or platform with a version of Java supported by Jenkins.

Theoretically, Jenkins can also be run as a servlet in a traditional servlet container like Apache Tomcat or WildFly, but in practice this is largely untested and there are many caveats. In particular, support for WebSocket agents is only implemented for the Jetty servlet container. See the Servlet Container Support Policy page for details.

â User Handbook Overview

Index

Docker â

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.

Read article

Initial Settings

â Offline Installations

â Installing Jenkins Index

Using Jenkins â

Initial Settings

Table of Contents

Jenkins Parameters
- Networking parameters
- Miscellaneous parameters
- Jenkins properties
Configuring HTTP
- HTTPS with an existing certificate
- Using HTTP/2
- HTTPS certificates with Windows

Most Jenkins configuration changes can be made through the Jenkins user interface or through the configuration as code plugin. There are some configuration values that can only be modified while Jenkins is starting. This section describes those settings and how you can use them.

Jenkins Parameters

Jenkins initialization can also be controlled by run time parameters passed as arguments. Command line arguments can adjust networking, security, monitoring, and other settings.

Networking parameters

Jenkins networking configuration is generally controlled by command line arguments. The networking configuration arguments are:

Table 1. Jenkins Networking Command Line Parameters
Command Line Parameter	Description
`--httpPort=$HTTP_PORT`	Runs Jenkins listener on port $HTTP_PORT using standard http protocol. The default is port 8080. To disable (because you’re using https ), use port `-1` . This option does not impact the root URL being generated within Jenkins logic (UI, inbound agent files, etc.). It is defined by the Jenkins URL specified in the global configuration.
`--httpListenAddress=$HTTP_HOST`	Binds Jenkins to the IP address represented by $HTTP_HOST. The default is 0.0.0.0 â i.e. listening on all available interfaces. For example, to only listen for requests from localhost, you could use: `--httpListenAddress=127.0.0.1`
`--httpsPort=$HTTPS_PORT`	Uses HTTPS protocol on port $HTTPS_PORT. This option does not impact the root URL being generated within Jenkins logic (UI, inbound agent files, etc.). It is defined by the Jenkins URL specified in the global configuration.
`--httpsListenAddress=$HTTPS_HOST`	Binds Jenkins to listen for HTTPS requests on the IP address represented by $HTTPS_HOST.
`--http2Port=$HTTP_PORT`	Uses HTTP/2 protocol on port $HTTP_PORT. This option does not impact the root URL being generated within Jenkins logic (UI, inbound agent files, etc.). It is defined by the Jenkins URL specified in the global configuration.
`--http2ListenAddress=$HTTPS_HOST`	Binds Jenkins to listen for HTTP/2 requests on the IP address represented by $HTTPS_HOST.
`--prefix=$PREFIX`	Runs Jenkins to include the $PREFIX at the end of the URL. For example, set --prefix=/jenkins to make Jenkins accessible at http://myServer:8080/jenkins
`--sessionTimeout=$TIMEOUT`	Sets the http session timeout value to $SESSION_TIMEOUT minutes. Default to what webapp specifies, and then to 60 minutes

Miscellaneous parameters

Other Jenkins initialization options are also controlled by command line arguments. The miscellaneous configuration arguments are:

Table 2. Jenkins Miscellaneous Command Line Parameters
Command Line Parameter	Description
`--argumentsRealm.passwd.$USER=$PASS`	Assigns the password for user $USER. If Jenkins security is enabled, you must log in as a user who has an admin role to configure Jenkins.
`--argumentsRealm.roles.$USER=admin`	Assigns user $USER the admin role. The user can configure Jenkins even if security is enabled in Jenkins. Refer to Securing Jenkins for more information.
`--paramsFromStdIn`	Reads parameters from standard input (stdin). When parameters are passed via the command line, they can be viewed using `ps(1)` in Unix or Process Explorer in Windows as long as the process keeps running. This is undesirable when passing sensitive parameters like `--httpsKeyStorePassword` . With the `--paramsFromStdIn` parameter you can replace e.g. `java -jar jenkins.war --httpPort=-1 --httpsPort=443 --httpsKeyStore=path/to/keystore --httpsKeyStorePassword=keystorePassword` with `echo '--httpPort=-1 --httpsPort=443 --httpsKeyStore=path/to/keystore --httpsKeyStorePassword=keystorePassword' \| java -jar jenkins.war --paramsFromStdIn` .
`--useJmx`	Enable Jetty Java Management Extension (JMX)

Jenkins passes all command line parameters to the Winstone servlet container. More information about Jenkins Winstone command line parameters is available from the Winstone Command Line Parameter Reference.

Be Careful with Command Line Parameters
Jenkins ignores command line parameters it doesn’t understand instead of producing an error. Be careful when using command line parameters and make sure you have the correct spelling. For example, the parameter needed for defining the Jenkins administrative user is --argument s Realm and not --argumentRealm .

Jenkins properties

Some Jenkins behaviors are configured with Java properties. Java properties are set from the command line that started Jenkins. Property assignments use the form -DsomeName=someValue to assign the value someValue to the property named someName . For example, to assign the value true to a property testName , the command line argument would be -DtestName=true .

Refer to the detailed list of Jenkins properties for more information.

Configuring HTTP

HTTPS with an existing certificate

If you’re setting up Jenkins using the built-in Winstone server and want to use an existing certificate for HTTPS:

--httpPort=-1 \
--httpsPort=443 \
--httpsKeyStore=path/to/keystore \
--httpsKeyStorePassword=keystorePassword

Using HTTP/2

The HTTP/2 protocol allows web servers to reduce latency over encrypted connections by pipelining requests, multiplexing requests, and allowing servers to push, in some cases, before receiving a client request for the data. The Jetty server used by Jenkins supports HTTP/2 with the addition of the Application-Layer Protocol Negotiation (ALPN) TLS extension.

Enabling HTTP/2 implicitly enables TLS even if no HTTPS port is set, and as of Jenkins 2.339, which uses Winstone 5.23, you have to also specify an HTTPS key store file.

--httpPort=-1 \
--http2Port=9090 \
--httpsKeyStore=path/to/keystore \
--httpsKeyStorePassword=keystorePassword

HTTPS certificates with Windows

These instructions use a stock Jenkins installation on Windows Server. The instructions assume a certificate signed by a Certificate Authority such as Digicert. If you are making your own certificate skip steps 3, 4, and 5.

This process utilizes Java’s keytool. Use the Java keytool included with your Java installation.

Step 1 : Create a new keystore on your server. This will place a 'keystore' file in your current directory.

C:\>keytool -genkeypair -keysize 2048 -keyalg RSA -alias jenkins -keystore keystore
Enter keystore password:
Re-enter new password:
What is your first and last name?
[Unknown]: server.example.com
What is the name of your organizational unit?
[Unknown]: A Unit
What is the name of your organization?
[Unknown]: A Company
What is the name of your City or Locality?
[Unknown]: A City
What is the name of your State or Province?
[Unknown]: A State
What is the two-letter country code for this unit?
[Unknown]: US
Is CN=server.example.com, OU=A Unit, O=A Company, L=A City, ST=A State, C=US correct?
[no]: yes

Enter key password for <jenkins>
(RETURN if same as keystore password):

Step 2 : Verify the keystore was created (your fingerprint will vary).

C:\>keytool -list -keystore keystore
Enter keystore password:

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 1 entry

jenkins, May 6, 2015, PrivateKeyEntry,
Certificate fingerprint (SHA1): AA:AA:AA:AA:AA:AA:AA:AA:AA:AA ...

Step 3 : Create the certificate request. This will create a 'certreq.csr' file in your current directory.

C:\>keytool -certreq -alias jenkins -keyalg RSA ^
-file certreq.csr ^
-ext SAN=dns:server-name,dns:server-name.your.company.com ^
-keystore keystore
Enter keystore password:

Step 4 : Use the contents of the certreq.csr file to generate a certificate from your certificate provider. Request a SHA-1 certificate (SHA-2 is untested but will likely work). If using DigiCert, download the resulting certificate as Other format "a .p7b bundle of all the certs in a .p7b file".

Step 5 : Add the resulting .p7b into the keystore you created above.

C:\>keytool -import ^
-alias jenkins ^
-trustcacerts ^
-file response_from_digicert.p7b ^
-keystore keystore
Enter keystore password:
Certificate reply was installed in keystore

Step 6 : Copy the 'keystore' file to your Jenkins secrets directory. On a stock installation, this will be at

C:\Program Files (x86)\Jenkins\secrets

Step 7 : Modify the <arguments> section of your C:\Program Files (x86)\Jenkins\jenkins.xml file to reflect the new certificate. NOTE: This example disables http via --httpPort=-1 and places the server on 8443 via --httpsPort=8443 .

<arguments>
  -Xrs
  -Xmx256m
  -Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle
  -jar "%BASE%\jenkins.war"
  --httpPort=-1
  --httpsPort=8443
  --httpsKeyStore="%BASE%\secrets\keystore"
  --httpsKeyStorePassword=your.password.here
</arguments>

Step 8 : Restart the jenkins service to initialize the new configuration.

net stop jenkins
net start jenkins

Step 9 : After 30-60 seconds, Jenkins will have completed the startup process and you should be able to access the website at https://server.example.com:8443 . Verify the certificate looks good via your browser’s tools. If the service terminates immediately, there’s an error somewhere in your configuration. Useful error information can be found in:

C:\Program Files (x86)\Jenkins\jenkins.err.log
C:\Program Files (x86)\Jenkins\jenkins.out.log

â Offline Installations

â Installing Jenkins Index

Using Jenkins â

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.

Read article

Kubernetes

â Docker

â Installing Jenkins Index

Linux â

Kubernetes

Table of Contents

Setup Jenkins On Kubernetes
- Jenkins Kubernetes Manifest Files
- Kubernetes Jenkins Deployment
- Accessing Jenkins Using Kubernetes Service
Install Jenkins with Helm v3
- Prerequisites
- Install Helm
- Configure Helm
- Create a persistent volume
- Create a service account
- Install Jenkins
Install Jenkins with YAML files
- Create Jenkins deployment file
- Deploy Jenkins
- Grant access to Jenkins service
- Access Jenkins dashboard
Install Jenkins with Jenkins Operator
Post-installation setup wizard
- Unlocking Jenkins
- Customizing Jenkins with plugins
- Creating the first administrator user
Conclusion

Kubernetes (K8s) is an open-source system for automating deployment, scaling, and management of containerized applications.

A Kubernetes cluster adds a new automation layer to Jenkins. Kubernetes makes sure that resources are used effectively and that your servers and underlying infrastructure are not overloaded. Kubernetes' ability to orchestrate container deployment ensures that Jenkins always has the right amount of resources available.

Hosting Jenkins on a Kubernetes Cluster is beneficial for Kubernetes-based deployments and dynamic container-based scalable Jenkins agents. Here, we see a step-by-step process for setting up Jenkins on a Kubernetes Cluster.

Setup Jenkins On Kubernetes

For setting up a Jenkins Cluster on Kubernetes, we will do the following:

Create a Namespace
Create a service account with Kubernetes admin permissions.
Create local persistent volume for persistent Jenkins data on Pod restarts.
Create a deployment YAML and deploy it.
Create a service YAML and deploy it.

This guide doesnât use local persistent volume as this is a generic guide. For using persistent volume for your Jenkins data, you need to create volumes of relevant cloud or on-prem data center and configure it.

Jenkins Kubernetes Manifest Files

All the Jenkins Kubernetes manifest files used here are hosted on GitHub. Please clone the repository if you have trouble copying the manifest from the document.

git clone https://github.com/scriptcamp/kubernetes-jenkins

Use the GitHub files for reference and follow the steps in the next sections.

Kubernetes Jenkins Deployment

Letâs get started with deploying Jenkins on Kubernetes.

Step 1 : Create a Namespace for Jenkins. It is good to categorize all the DevOps tools as a separate namespace from other applications.

kubectl create namespace devops-tools

Step 2: Create a 'serviceAccount.yaml' file and copy the following admin service account manifest.

---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: jenkins-admin
rules:
  - apiGroups: [""]
    resources: ["*"]
    verbs: ["*"]
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: jenkins-admin
  namespace: devops-tools
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: jenkins-admin
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: jenkins-admin
subjects:
- kind: ServiceAccount
  name: jenkins-admin
  namespace: devops-tools

The 'serviceAccount.yaml' creates a 'jenkins-admin' clusterRole, 'jenkins-admin' ServiceAccount and binds the 'clusterRole' to the service account.

The 'jenkins-admin' cluster role has all the permissions to manage the cluster components. You can also restrict access by specifying individual resource actions.

Now create the service account using kubectl.

kubectl apply -f serviceAccount.yaml

Step 3: Create 'volume.yaml' and copy the following persistent volume manifest.

kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: local-storage
provisioner: kubernetes.io/no-provisioner
volumeBindingMode: WaitForFirstConsumer
---
apiVersion: v1
kind: PersistentVolume
metadata:
  name: jenkins-pv-volume
  labels:
    type: local
spec:
  storageClassName: local-storage
  claimRef:
    name: jenkins-pv-claim
    namespace: devops-tools
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  local:
    path: /mnt
  nodeAffinity:
    required:
      nodeSelectorTerms:
      - matchExpressions:
        - key: kubernetes.io/hostname
          operator: In
          values:
          - worker-node01
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: jenkins-pv-claim
  namespace: devops-tools
spec:
  storageClassName: local-storage
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 3Gi

Important Note: Replace 'worker-node01' with any one of your cluster worker nodes hostname.

You can get the worker node hostname using the kubectl.

kubectl get nodes

For volume, we are using the 'local' storage class for the purpose of demonstration. Meaning, it creates a 'PersistentVolume' volume in a specific node under the '/mnt' location.

As the 'local' storage class requires the node selector, you need to specify the worker node name correctly for the Jenkins pod to get scheduled in the specific node.

If the pod gets deleted or restarted, the data will get persisted in the node volume. However, if the node gets deleted, you will lose all the data.

Ideally, you should use a persistent volume using the available storage class with the cloud provider, or the one provided by the cluster administrator to persist data on node failures.

Letâs create the volume using kubectl

kubectl create -f volume.yaml

Step 4: Create a Deployment file named 'deployment.yaml' and copy the following deployment manifest.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: jenkins
  namespace: devops-tools
spec:
  replicas: 1
  selector:
    matchLabels:
      app: jenkins-server
  template:
    metadata:
      labels:
        app: jenkins-server
    spec:
      securityContext:
            fsGroup: 1000
            runAsUser: 1000
      serviceAccountName: jenkins-admin
      containers:
        - name: jenkins
          image: jenkins/jenkins:lts
          resources:
            limits:
              memory: "2Gi"
              cpu: "1000m"
            requests:
              memory: "500Mi"
              cpu: "500m"
          ports:
            - name: httpport
              containerPort: 8080
            - name: jnlpport
              containerPort: 50000
          livenessProbe:
            httpGet:
              path: "/login"
              port: 8080
            initialDelaySeconds: 90
            periodSeconds: 10
            timeoutSeconds: 5
            failureThreshold: 5
          readinessProbe:
            httpGet:
              path: "/login"
              port: 8080
            initialDelaySeconds: 60
            periodSeconds: 10
            timeoutSeconds: 5
            failureThreshold: 3
          volumeMounts:
            - name: jenkins-data
              mountPath: /var/jenkins_home
      volumes:
        - name: jenkins-data
          persistentVolumeClaim:
              claimName: jenkins-pv-claim

In this Jenkins Kubernetes deployment we have used the following:

'securityContext' for Jenkins pod to be able to write to the local persistent volume.
Liveness and readiness probe to monitor the health of the Jenkins pod.
Local persistent volume based on local storage class that holds the Jenkins data path '/var/jenkins_home'.

The deployment file uses local storage class persistent volume for Jenkins data. For production use cases, you should add a cloud-specific storage class persistent volume for your Jenkins data.

If you donât want the local storage persistent volume, you can replace the volume definition in the deployment with the host directory as shown below.

volumes:
- name: jenkins-data
emptyDir: \{}

Create the deployment using kubectl.

kubectl apply -f deployment.yaml

Check the deployment status.

kubectl get deployments -n devops-tools

Now, you can get the deployment details using the following command.

kubectl describe deployments --namespace=devops-tools

Accessing Jenkins Using Kubernetes Service

We have now created a deployment. However, it is not accessible to the outside world. For accessing the Jenkins deployment from the outside world, we need to create a service and map it to the deployment.

Create 'service.yaml' and copy the following service manifest:

apiVersion: v1
kind: Service
metadata:
  name: jenkins-service
  namespace: devops-tools
  annotations:
      prometheus.io/scrape: 'true'
      prometheus.io/path:   /
      prometheus.io/port:   '8080'
spec:
  selector:
    app: jenkins-server
  type: NodePort
  ports:
    - port: 8080
      targetPort: 8080
      nodePort: 32000

Here, we are using the type as 'NodePort' which will expose Jenkins on all kubernetes node IPs on port 32000. If you have an ingress setup, you can create an ingress rule to access Jenkins. Also, you can expose the Jenkins service as a Loadbalancer if you are running the cluster on AWS, Google, or Azure cloud.

Create the Jenkins service using kubectl.

kubectl apply -f service.yaml

Now, when browsing to any one of the Node IPs on port 32000, you will be able to access the Jenkins dashboard.

http://<node-ip>:32000

Jenkins will ask for the initial Admin password when you access the dashboard for the first time.

You can get that from the pod logs either from the Kubernetes dashboard or CLI. You can get the pod details using the following CLI command.

kubectl get pods --namespace=devops-tools

With the pod name, you can get the logs as shown below. Replace the pod name with your pod name.

kubectl logs jenkins-deployment-2539456353-j00w5 --namespace=devops-tools

The password can be found at the end of the log.

Alternatively, you can run the exec command to get the password directly from the location as shown below.

kubectl exec -it jenkins-559d8cd85c-cfcgk cat /var/jenkins_home/secrets/initialAdminPassword -n devops-tools

Once you enter the password, proceed to install the suggested plugin and create an admin user. All of these steps are self-explanatory from the Jenkins dashboard.

Install Jenkins with Helm v3

A typical Jenkins deployment consists of a controller node and, optionally, one or more agents. To simplify the deployment of Jenkins, weâll use Helm to deploy Jenkins. Helm is a package manager for Kubernetes and its package format is called a chart. Many community-developed charts are available on GitHub.

Helm Charts provide âpush buttonâ deployment and deletion of apps, making adoption and development of Kubernetes apps easier for those with little container or microservices experience.

Prerequisites

Helm command line interface: If you don’t have Helm command line interface installed and configured locally, see the sections below to Install Helm and Configure Helm.

Install Helm

To install Helm CLI, follow the instructions from the Installing Helm page.

Configure Helm

Once Helm is installed and set up properly, add the Jenkins repo as follows:

$ helm repo add jenkinsci https://charts.jenkins.io
$ helm repo update

The helm charts in the Jenkins repo can be listed with the command:

$ helm search repo jenkinsci

Create a persistent volume

We want to create a persistent volume for our Jenkins controller pod. This will prevent us from losing our whole configuration of the Jenkins controller and our jobs when we reboot our minikube. This official minikube doc explains which directories we can use to mount or data. In a multi-node Kubernetes cluster, youâll need some solution like NFS to make the mount directory available in the whole cluster. But because we use minikube which is a one-node cluster we donât have to bother about it.

We choose to use the /data directory. This directory will contain our Jenkins controller configuration.

We will create a volume which is called jenkins-pv:

Paste the content from https://raw.githubusercontent.com/installing-jenkins-on-kubernetes/jenkins-volume.yaml into a YAML formatted file called jenkins-volume.yaml .
Run the following command to apply the spec:
```
$ kubectl apply -f jenkins-volume.yaml
```

Itâs worth noting that, in the above spec, hostPath uses the /data/jenkins-volume/ of your node to emulate network-attached storage. This approach is only suited for development and testing purposes. For production, you should provide a network resource like a Google Compute Engine persistent disk, or an Amazon Elastic Block Store volume.

Minikube configured for hostPath sets the permissions on /data to the root account only. Once the volume is created you will need to manually change the permissions to allow the jenkins account to write its data.

minikube ssh
sudo chown -R 1000:1000 /data/jenkins-volume

Create a service account

In Kubernetes, service accounts are used to provide an identity for pods. Pods that want to interact with the API server will authenticate with a particular service account. By default, applications will authenticate as the default service account in the namespace they are running in. This means, for example, that an application running in the test namespace will use the default service account of the test namespace.

We will create a service account called jenkins:

A ClusterRole is a set of permissions that can be assigned to resources within a given cluster. Kubernetes APIs are categorized into API groups, based on the API objects that they relate to. While creating a ClusterRole, you can specify the operations that can be performed by the ClusterRole on one or more API objects in one or more API groups, just as we have done above. ClusterRoles have several uses. You can use a ClusterRole to:

define permissions on namespaced resources and be granted within individual namespace(s)
define permissions on namespaced resources and be granted across all namespaces
define permissions on cluster-scoped resources

If you want to define a role cluster-wide, use a ClusterRole; if you want to define a role within a namespace, use a Role.

A role binding grants the permissions defined in a role to a user or set of users. It holds a list of subjects (users, groups, or service accounts), and a reference to the role being granted.

A RoleBinding may reference any Role in the same namespace. Alternatively, a RoleBinding can reference a ClusterRole and bind that ClusterRole to the namespace of the RoleBinding. To bind a ClusterRole to all the namespaces in our cluster, we use a ClusterRoleBinding.

Paste the content from https://raw.githubusercontent.com/installing-jenkins-on-kubernetes/jenkins-sa.yaml into a YAML formatted file called jenkins-sa.yaml .
Run the following command to apply the spec:
```
$ kubectl apply -f jenkins-sa.yaml
```

Install Jenkins

We will deploy Jenkins including the Jenkins Kubernetes plugin. See the official chart for more details.

To enable persistence, we will create an override file and pass it as an argument to the Helm CLI. Paste the content from raw.githubusercontent.com/jenkinsci/helm-charts/main/charts/jenkins/values.yaml into a YAML formatted file called jenkins-values.yaml .

The jenkins-values.yaml is used as a template to provide values that are necessary for setup.
Open the jenkins-values.yaml file in your favorite text editor and modify the following:
- nodePort: Because we are using minikube we need to use NodePort as service type. Only cloud providers offer load balancers. We define port 32000 as port.
- storageClass:
  storageClass: jenkins-pv
- serviceAccount: the serviceAccount section of the jenkins-values.yaml file should look like this:
  serviceAccount: create: false # Service account name is autogenerated by default name: jenkins annotations: {}
  Where `name: jenkins` refers to the serviceAccount created for jenkins.
- We can also define which plugins we want to install on our Jenkins. We use some default plugins like git and the pipeline plugin.
Now you can install Jenkins by running the helm install command and passing it the following arguments:
- The name of the release jenkins
- The -f flag with the YAML file with overrides jenkins-values.yaml
- The name of the chart jenkinsci/jenkins
- The -n flag with the name of your namespace jenkins
  $ chart=jenkinsci/jenkins $ helm install jenkins -n jenkins -f jenkins-values.yaml $chart
  This outputs something similar to the following:
  NAME: jenkins LAST DEPLOYED: Wed Sep 16 11:13:10 2020 NAMESPACE: jenkins STATUS: deployed REVISION: 1

Get your 'admin' user password by running:

$ jsonpath="{.data.jenkins-admin-password}"
$ secret=$(kubectl get secret -n jenkins jenkins -o jsonpath=$jsonpath)
$ echo $(echo $secret | base64 --decode)

Get the Jenkins URL to visit by running these commands in the same shell:

$ jsonpath="{.spec.ports[0].nodePort}"
$ NODE_PORT=$(kubectl get -n jenkins -o jsonpath=$jsonpath services jenkins)
$ jsonpath="{.items[0].status.addresses[0].address}"
$ NODE_IP=$(kubectl get nodes -n jenkins -o jsonpath=$jsonpath)
$ echo http://$NODE_IP:$NODE_PORT/login

Login with the password from step 1 and the username: admin
Use Jenkins Configuration as Code by specifying configScripts in your values.yaml file. See the configuration as code documentation and examples.

Visit the Jenkins on Kubernetes solutions page for more information on running Jenkins on Kubernetes. Visit the Jenkins Configuration as Code project for more information on configuration as code. . Depending on your environment, it can take a bit of time for Jenkins to start up. Enter the following command to inspect the status of your Pod:

$ kubectl get pods -n jenkins

Once Jenkins is installed, the status should be set to Running as in the following output:

$ kubectl get pods -n jenkins
NAME                       READY   STATUS    RESTARTS   AGE
jenkins-645fbf58d6-6xfvj   1/1     Running   0          2m

To access your Jenkins server, you must retrieve the password. You can retrieve your password using either of the two options below.

Option 1

Run the following command:

$ jsonpath="{.data.jenkins-admin-password}"
$ secret=$(kubectl get secret -n jenkins jenkins -o jsonpath=$jsonpath)
$ echo $(echo $secret | base64 --decode)

The output should look like this:

Um1kJLOWQY

ðð»Note that your password will be different.

Option 2

Run the following command:

$ jsonpath="{.data.jenkins-admin-password}"
$ kubectl get secret -n jenkins jenkins -o jsonpath=$jsonpath

The output should be a base64 encoded string like this:

WkIwRkdnbDZYZg==

Decode the base64 string and you have your password. You can use this website to decode your output.

Get the name of the Pod running that is running Jenkins using the following command:
```
$ kubectl get pods -n jenkins
```

Use the kubectl command to set up port forwarding:

$ kubectl -n jenkins port-forward <pod_name> 8080:8080
Forwarding from 127.0.0.1:8080 -> 8080
Forwarding from [::1]:8080 -> 8080

Visit 127.0.0.1:8080/ and log in using admin as the username and the password you retrieved earlier.

Install Jenkins with YAML files

This section describes how to use a set of YAML (Yet Another Markup Language) files to install Jenkins on a Kubernetes cluster. The YAML files are easily tracked, edited, and can be reused indefinitely.

Create Jenkins deployment file

Copy the contents here into your preferred text editor and create a jenkins-deployment.yaml file in the âjenkinsâ namespace we created in this section above.

This deployment file is defining a Deployment as indicated by the kind field.
The Deployment specifies a single replica. This ensures one and only one instance will be maintained by the Replication Controller in the event of failure.
The container image name is jenkins and version is 2.32.2
The list of ports specified within the spec are a list of ports to expose from the container on the Pods IP address.
- Jenkins running on (http) port 8080.
- The Pod exposes the port 8080 of the jenkins container.
The volumeMounts section of the file creates a Persistent Volume. This volume is mounted within the container at the path /var/jenkins_home and so modifications to data within /var/jenkins_home are written to the volume. The role of a persistent volume is to store basic Jenkins data and preserve it beyond the lifetime of a pod.

Exit and save the changes once you add the content to the Jenkins deployment file.

Deploy Jenkins

To create the deployment execute:

$ kubectl create -f jenkins-deployment.yaml -n jenkins

The command also instructs the system to install Jenkins within the jenkins namespace.

To validate that creating the deployment was successful you can invoke:

$ kubectl get deployments -n jenkins

Grant access to Jenkins service

We have a Jenkins instance deployed but it is still not accessible. The Jenkins Pod has been assigned an IP address that is internal to the Kubernetes cluster. Itâs possible to log into the Kubernetes Node and access Jenkins from there but thatâs not a very useful way to access the service.

To make Jenkins accessible outside the Kubernetes cluster the Pod needs to be exposed as a Service. A Service is an abstraction that exposes Jenkins to the wider network. It allows us to maintain a persistent connection to the pod regardless of the changes in the cluster. With a local deployment, this means creating a NodePort service type. A NodePort service type exposes a service on a port on each node in the cluster. The service is accessed through the Node IP address and the service nodePort. A simple service is defined here:

This service file is defining a Service as indicated by the kind field.
The Service is of type NodePort. Other options are ClusterIP (only accessible within the cluster) and LoadBalancer (IP address assigned by a cloud provider e.g. AWS Elastic IP).
The list of ports specified within the spec is a list of ports exposed by this service.
- The port is the port that will be exposed by the service.
- The target port is the port to access the Pods targeted by this service. A port name may also be specified.
The selector specifies the selection criteria for the Pods targeted by this service.

To create the service execute:

$ kubectl create -f jenkins-service.yaml -n jenkins

To validate that creating the service was successful you can run:

$ kubectl get services -n jenkins
NAME       TYPE        CLUSTER-IP       EXTERNAL-IP    PORT(S)           AGE
jenkins    NodePort    10.103.31.217    <none>         8080:32664/TCP    59s

Access Jenkins dashboard

So now we have created a deployment and service, how do we access Jenkins?

From the output above we can see that the service has been exposed on port 32664. We also know that because the service is of type NodeType the service will route requests made to any node on this port to the Jenkins pod. All thatâs left for us is to determine the IP address of the minikube VM. Minikube have made this really simple by including a specific command that outputs the IP address of the running cluster:

$ minikube ip
192.168.99.100

Now we can access the Jenkins instance at 192.168.99.100:32664/

To access Jenkins, you initially need to enter your credentials. The default username for new installations is admin. The password can be obtained in several ways. This example uses the Jenkins deployment pod name.

To find the name of the pod, enter the following command:

$ kubectl get pods -n jenkins

Once you locate the name of the pod, use it to access the podâs logs.

$ kubectl logs <pod_name> -n jenkins

The password is at the end of the log formatted as a long alphanumeric string:

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

Jenkins initial setup is required.
An admin user has been created and a password generated.
Please use the following password to proceed to installation:

94b73ef6578c4b4692a157f768b2cfef

This may also be found at:
/var/jenkins_home/secrets/initialAdminPassword

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

You have successfully installed Jenkins on your Kubernetes cluster and can use it to create new and efficient development pipelines.

Install Jenkins with Jenkins Operator

The Jenkins Operator is a Kubernetes native Operator which manages operations for Jenkins on Kubernetes.

It was built with immutability and declarative configuration as code in mind, to automate many of the manual tasks required to deploy and run Jenkins on Kubernetes.

Jenkins Operator is easy to install with applying just a few yaml manifests or with the use of Helm.

For instructions on installing Jenkins Operator on your Kubernetes cluster and deploying and configuring Jenkins there, see official documentation of Jenkins Operator.

Post-installation setup wizard

After downloading, installing and running Jenkins using one of the procedures above (except for installation with Jenkins Operator), the post-installation setup wizard begins.

This setup wizard takes you through 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.

Browse to http://localhost:8080 (or whichever port you configured for Jenkins when installing it) and wait until the Unlock Jenkins page appears.
From the Jenkins console log output, copy the automatically-generated alphanumeric password (between the 2 sets of asterisks).

Note:
- The command: sudo cat /var/lib/jenkins/secrets/initialAdminPassword will print the password at console.
- If you are running Jenkins in Docker using the official jenkins/jenkins image you can use sudo docker exec ${CONTAINER_ID or CONTAINER_NAME} cat /var/jenkins_home/secrets/initialAdminPassword to print the password in the console without having to exec into the container.
On the Unlock Jenkins page, paste this password into the Administrator password field and click Continue .
Notes:
- You can always 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 administrator 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.

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.

When the Create First Admin User page appears, specify the details for your administrator user in the respective fields and click Save and Finish .
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.
If required, log in to Jenkins with the credentials of the user you just created and you are ready to start using Jenkins!

Conclusion

When you host Jenkins on Kubernetes for production workloads, you need to consider setting up a highly available persistent volume, to avoid data loss during pod or node deletion.

A pod or node deletion could happen anytime in Kubernetes environments. It could be a patching activity or a downscaling activity.

Hopefully, this step-by-step guide helps you learn and understand the components involved in setting up a Jenkins server on a Kubernetes cluster.

â Docker

â Installing Jenkins Index

Linux â

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.

Read article

Linux

â Kubernetes

â Installing Jenkins Index

macOS â

Linux

Table of Contents

Prerequisites
Debian/Ubuntu
- Long Term Support release
- Weekly release
- Installation of Java
Fedora
- Long Term Support release
- Weekly release
- Start Jenkins
Red Hat / CentOS
- Long Term Support release
- Weekly release
- Start Jenkins
Post-installation setup wizard
- Unlocking Jenkins
- Customizing Jenkins with plugins
- Creating the first administrator user

Jenkins installers are available for several Linux distributions.

Debian/Ubuntu
Fedora
Red Hat / CentOS

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:

4 GB+ of RAM
50 GB+ of drive space

Comprehensive hardware recommendations:

Hardware: see the Hardware Recommendations page

Software requirements:

Java: see the Java Requirements page
Web browser: see the Web Browser Compatibility page
For Windows operating system: Windows Support Policy
For Linux operating system: Linux Support Policy
For servlet containers: Servlet Container Support Policy

Debian/Ubuntu

On Debian and Debian-based distributions like Ubuntu you can install Jenkins through apt .

Long Term Support release

A LTS (Long-Term Support) release is chosen every 12 weeks from the stream of regular releases as the stable release for that time period. It can be installed from the debian-stable apt repository.

curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io.key | sudo tee \
  /usr/share/keyrings/jenkins-keyring.asc > /dev/null
echo deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] \
  https://pkg.jenkins.io/debian-stable binary/ | sudo tee \
  /etc/apt/sources.list.d/jenkins.list > /dev/null
sudo apt-get update
sudo apt-get install jenkins

Weekly release

A new release is produced weekly to deliver bug fixes and features to users and plugin developers. It can be installed from the debian apt repository.

curl -fsSL https://pkg.jenkins.io/debian/jenkins.io.key | sudo tee \
  /usr/share/keyrings/jenkins-keyring.asc > /dev/null
echo deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] \
  https://pkg.jenkins.io/debian binary/ | sudo tee \
  /etc/apt/sources.list.d/jenkins.list > /dev/null
sudo apt-get update
sudo apt-get install jenkins

Beginning with Jenkins 2.335 and Jenkins 2.332.1, the package is configured with systemd rather than the older System V init . See the DigitalOcean community systemd tutorial to better understand the benefits of systemd and the systemctl command.

The package installation will:

Setup Jenkins as a daemon launched on start. Run systemctl cat jenkins for more details.
Create a ‘jenkins’ user to run this service.
Direct console log output to systemd-journald . Run journalctl -u jenkins.service if you are troubleshooting Jenkins.
Populate /lib/systemd/system/jenkins.service 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 Jenkins fails to start because a port is in use, run systemctl edit jenkins and add the following:

[Service]
Environment="JENKINS_PORT=8081"

Here, "8081" was chosen but you can put another port available.

Installation of Java

Jenkins requires Java in order to run, yet certain distributions don’t include this by default and some Java versions are incompatible with Jenkins.

There are multiple Java implementations which you can use. OpenJDK is the most popular one at the moment, we will use it in this guide.

Update the Debian apt repositories, install OpenJDK 11, and check the installation with the commands:

$ sudo apt update
$ sudo apt install openjdk-11-jre
$ java -version
openjdk version "11.0.12" 2021-07-20
OpenJDK Runtime Environment (build 11.0.12+7-post-Debian-2)
OpenJDK 64-Bit Server VM (build 11.0.12+7-post-Debian-2, mixed mode, sharing)

Why use apt and not apt-get or another command? The apt command has been available since 2014. It has a command structure that is similar to apt-get but was created to be a more pleasant experience for typical users. Simple software management tasks like install, search and remove are easier with apt .

Fedora

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

Long Term Support release

A LTS (Long-Term Support) release is chosen every 12 weeks from the stream of regular releases as the stable release for that time period. It can be installed from the redhat-stable yum repository.

sudo wget -O /etc/yum.repos.d/jenkins.repo \
    https://pkg.jenkins.io/redhat-stable/jenkins.repo
sudo rpm --import https://pkg.jenkins.io/redhat-stable/jenkins.io.key
sudo dnf upgrade
# Add required dependencies for the jenkins package
sudo dnf install java-11-openjdk
sudo dnf install jenkins
sudo systemctl daemon-reload

Weekly release

A new release is produced weekly to deliver bug fixes and features to users and plugin developers. It can be installed from the redhat yum repository.

sudo wget -O /etc/yum.repos.d/jenkins.repo \
    https://pkg.jenkins.io/redhat/jenkins.repo
sudo rpm --import https://pkg.jenkins.io/redhat/jenkins.io.key
sudo dnf upgrade
# Add required dependencies for the jenkins package
sudo dnf install java-11-openjdk
sudo dnf install jenkins

Start Jenkins

You can enable the Jenkins service to start at boot with the command:

sudo systemctl enable jenkins

You can start the Jenkins service with the command:

sudo systemctl start jenkins

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

sudo systemctl status jenkins

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

Loaded: loaded (/lib/systemd/system/jenkins.service; enabled; vendor preset: enabled)
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.

YOURPORT=8080
PERM="--permanent"
SERV="$PERM --service=jenkins"

firewall-cmd $PERM --new-service=jenkins
firewall-cmd $SERV --set-short="Jenkins ports"
firewall-cmd $SERV --set-description="Jenkins port exceptions"
firewall-cmd $SERV --add-port=$YOURPORT/tcp
firewall-cmd $PERM --add-service=jenkins
firewall-cmd --zone=public --add-service=http --permanent
firewall-cmd --reload

Red Hat / CentOS

You can install Jenkins through yum on Red Hat Enterprise Linux, CentOS, and other Red Hat based distributions.

How To Install Jenkins on CentOS 7

You need to choose either the Jenkins Long Term Support release or the Jenkins weekly release.

Long Term Support release

A LTS (Long-Term Support) release is chosen every 12 weeks from the stream of regular releases as the stable release for that time period. It can be installed from the redhat-stable yum repository.

sudo wget -O /etc/yum.repos.d/jenkins.repo \
    https://pkg.jenkins.io/redhat-stable/jenkins.repo
sudo rpm --import https://pkg.jenkins.io/redhat-stable/jenkins.io.key
sudo yum upgrade
# Add required dependencies for the jenkins package
sudo yum install java-11-openjdk
sudo yum install jenkins
sudo systemctl daemon-reload

Weekly release

A new release is produced weekly to deliver bug fixes and features to users and plugin developers. It can be installed from the redhat yum repository.

sudo wget -O /etc/yum.repos.d/jenkins.repo \
    https://pkg.jenkins.io/redhat/jenkins.repo
sudo rpm --import https://pkg.jenkins.io/redhat/jenkins.io.key
sudo yum upgrade
# Add required dependencies for the jenkins package
sudo yum install java-11-openjdk
sudo yum install jenkins

Start Jenkins

You can enable the Jenkins service to start at boot with the command:

sudo systemctl enable jenkins

You can start the Jenkins service with the command:

sudo systemctl start jenkins

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

sudo systemctl status jenkins

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

Loaded: loaded (/lib/systemd/system/jenkins.service; enabled; vendor preset: enabled)
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.

YOURPORT=8080
PERM="--permanent"
SERV="$PERM --service=jenkins"

firewall-cmd $PERM --new-service=jenkins
firewall-cmd $SERV --set-short="Jenkins ports"
firewall-cmd $SERV --set-description="Jenkins port exceptions"
firewall-cmd $SERV --add-port=$YOURPORT/tcp
firewall-cmd $PERM --add-service=jenkins
firewall-cmd --zone=public --add-service=http --permanent
firewall-cmd --reload

Post-installation setup wizard

After downloading, installing and running Jenkins using one of the procedures above (except for installation with Jenkins Operator), the post-installation setup wizard begins.

This setup wizard takes you through 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.

Browse to http://localhost:8080 (or whichever port you configured for Jenkins when installing it) and wait until the Unlock Jenkins page appears.
From the Jenkins console log output, copy the automatically-generated alphanumeric password (between the 2 sets of asterisks).

Note:
- The command: sudo cat /var/lib/jenkins/secrets/initialAdminPassword will print the password at console.
- If you are running Jenkins in Docker using the official jenkins/jenkins image you can use sudo docker exec ${CONTAINER_ID or CONTAINER_NAME} cat /var/jenkins_home/secrets/initialAdminPassword to print the password in the console without having to exec into the container.
On the Unlock Jenkins page, paste this password into the Administrator password field and click Continue .
Notes:
- You can always 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 administrator 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.

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.

When the Create First Admin User page appears, specify the details for your administrator user in the respective fields and click Save and Finish .
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.
If required, log in to Jenkins with the credentials of the user you just created and you are ready to start using Jenkins!

â Kubernetes

â Installing Jenkins Index

macOS â

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.

Read article