WAR file

This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc.

The Jenkins Web application ARchive (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. See the Java Requirements page for details.

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:

Software requirements:

Run the WAR file

The Jenkins Web application ARchive (WAR) file can be started from the command line like this:

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

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

  3. Run the command java -jar jenkins.war

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

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

Notes:

  • This process does not automatically install any specific plugins. They need to installed separately via the Manage Jenkins > Plugins page in Jenkins.

  • 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

  • You can change the directory where Jenkins stores its configuration with the JENKINS_HOME environment variable. For example, to place the Jenkins configuration files in a subdirectory named my-jenkins-config, define JENKINS_HOME=my-jenkins-config before running the java -jar jenkins.war command. Use the Windows commands:

    Windows
    C:\Temp > set JENKINS_HOME=my-jenkins-config
C:\Temp > java -jar jenkins.war

    or the Unix command:

    Unix
    JENKINS_HOME=my-jenkins-config java -jar jenkins.war

For more details of command line arguments that can adjust Jenkins startup, use the command:
java -jar jenkins.war --help

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.

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

    Unlock Jenkins page

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

    Copying initial admin password
    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.

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

    • 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 > Plugins page in Jenkins.

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

Creating the first administrator user

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

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

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

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

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

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