docker run \
-u root \ (1)
--rm \ (2)
-d \ (3)
-p 8080:8080 \ (4)
-p 50000:50000 \ (5)
-v jenkins-data:/var/jenkins_home \ (6)
-v /var/run/docker.sock:/var/run/docker.sock \ (7)
jenkinsci/blueocean (8)
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.
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:
Java: see the Java Requirements page
Web browser: see the Web Browser Compatibility page
This section describes how to install/run Jenkins on different platforms and operating systems.
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.
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. |
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 There are also other Jenkins Docker images you can use (accessible through
|
Open up a terminal window.
Download the jenkinsci/blueocean
image and run it as a container in Docker
using the following
docker run
command:
docker run \
-u root \ (1)
--rm \ (2)
-d \ (3)
-p 8080:8080 \ (4)
-p 50000:50000 \ (5)
-v jenkins-data:/var/jenkins_home \ (6)
-v /var/run/docker.sock:/var/run/docker.sock \ (7)
jenkinsci/blueocean (8)
1 | ( Optional ) Since the default jenkins user doesn’t have access to
/var/run/docker.sock , you need to run Jenkins as root to allow Jenkins to
spawn docker containers to execute stages in your pipelines. This only affects
executors on the master Jenkins node, so if you are planning to execute your
pipelines on agents, this is not necessary. |
2 | ( 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. |
3 | ( 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. |
4 | 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. |
5 | ( 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. |
6 | ( 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 . |
7 | ( 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. |
8 | The jenkinsci/blueocean Docker image itself. If this image has not already
been downloaded, then this docker run command will automatically 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
Proceed to the Post-installation setup wizard.
Open up a command prompt window.
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.
Proceed to the Post-installation setup wizard.
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
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
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
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:
Download the latest stable Jenkins WAR file to an appropriate directory on your machine.
Open up a terminal/command prompt window to the download directory.
Run the command java -jar jenkins.war
.
Browse to http://localhost:8080
and wait until the Unlock Jenkins page
appears.
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
To install from the website, using a package:
Open the package and follow the instructions
Jenkins can also be installed using brew
:
Install the latest release version
brew install jenkins
Install the LTS version
brew install jenkins-lts
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 https://pkg.jenkins.io/debian-stable binary/ > /etc/apt/sources.list.d/jenkins.list'
sudo apt-get update
sudo apt-get install jenkins
If you face error "jenkins : Depends: daemon but it is not installable", execute following command after
|
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 |
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
|
To install from the website, using the installer:
Open the package and follow the instructions
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 |
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. |
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.
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.
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).
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.
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.
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!
From this point on, the Jenkins UI is only accessible by providing valid username and password credentials. |
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.