Running Jenkins behind an NGINX reverse proxy

One of the newer web server solutions to take the Internet by storm is NGinX (pronounced Engine X). Developed in 2004 under the supervision of Igor Sysoev, NGINX was created to facilitate scalability and the load-balancing requirements of high-traffic web sites. Since its inception, this tool has gained wide acceptance and notoriety. Let's look at how to apply a reverse proxy to Jenkins. This can be accomplished in a straightforward manner. Let's take a few minutes to look at how to achieve this.

If NGINX has not already been installed on the target system, the first step will be to install it. NGINX can easily be installed onto an Ubuntu/Debian or CentOS-based system using the following terminal commands:

CENTOS#> yum install nginx
DEBIAN#> apt-get install nginx

Upon completing the installation of the NGINX web server, verify that the installation was successful by executing the nginx –v command. This will display the version information for the NGINX web server on the terminal and provide us with the assurance that it is installed properly.

Now that the NGINX web server has been installed onto the target system, the system will need to be configured to act as a reverse proxy for the Jenkins JVM. To accomplish this, simply update the nginx configuration files to contain a proxy pass. The configuration files for nginx on Ubuntu can be found in the following location:

/etc/nginx/sites-enabled/default

An example (provided at http://www.jenkins-ci.org) of a Jenkins proxy pass entry with Jenkins running under a subdomain (Jenkins.domain.com) is provided below.

server {
    listen 80;
    server_name jenkins.domain.com;
    return 301 https://$host$request_uri;
}

server {

    listen 80;
    server_name jenkins.domain.com;

    location / {

      proxy_set_header        Host $host;
      proxy_set_header        X-Real-IP $remote_addr;
      proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header        X-Forwarded-Proto $scheme;

      # Fix the "It appears that your reverse proxy set up is broken" error.
      proxy_pass          http://127.0.0.1:8080;
      proxy_read_timeout  90;

      proxy_redirect      http://127.0.0.1:8080 https://jenkins.domain.com;
    }
  }

Once the configuration file has been updated, save the file to the disk, and restart nginx with the following command:

#>sudo service nginx restart

For the Jenkins UI and the NGINX reverse proxy to properly integrate, the context paths of Jenkins and the NGINX subdirectory must match. For example, if the Jenkins system is configured to use a context path of http://localhost:8080/jenkins, the proxy pass context defined in the web server's configuration file must also reflect the /Jenkins suffix.

To set the context path for Jenkins, add the --prefix= entry to the JENKINS_ARGS= property. An example of this configuration entry is provided below.

--prefix=/Jenkins
--prefix=/somecontextpathhere

The JENKINS_ARGS configuration line is located inside the Jenkins startup bash/dash script. This file is typically found in one of the following locations on the filesystem (dependent on the Linux distribution):

/etc/default/Jenkins

/etc/sysconfig/Jenkins (line 151)

Once everything has been configured, restart the NGINX and Jenkins services to finalize the implementation of the reverse proxy redirect solution.

After this has been completed, navigate from a web browser to your Jenkins URL on port 80, and verify that the Jenkins UI behaves properly.