How to Configure Jenkins with SSL using an Nginx Reverse Proxy

Introduction

By default, Jenkins comes with its own built-in Winstone web server listening on port 8080, which is convenient for getting started. As soon as you’re serious about using Jenkins, however, it should be secured with SSL to protect passwords and other sensitive data transmitted through the web interface.

In this tutorial, we’ll demonstrate how to configure Nginx as a reverse proxy to direct client requests to Jenkins. In order to begin, you’ll need to complete each of the the prerequisites below.

Prerequisites

One Ubuntu 16.04 server configured with a non-root sudo user and a firewall by following the Ubuntu 16.04 initial server setup guide with Jenkins and Nginx installed and configured using the following guides:

How to Install Jenkins on Ubuntu 16.04

How to Install Nginx on Ubuntu 16.04

How to Secure Nginx with Let’s Encrypt on Ubuntu 16.04. Note that this tutorial requires a registered domain name that you own or control.

When you’ve completed these requirements, you’re ready to begin.

Step One — Configuring Nginx

In the prerequisite tutorial, How to Secure Nginx with Let’s Encrypt on Ubuntu 16.04, we configured Nginx to use SSL in the /etc/nginx/sites-available/default file, so we’ll open that file to add our reverse proxy settings.

Then, we’ll configure the proxy settings. Since we’re sending all requests to Jenkins, we’ll comment out the default try_files line which, as written, will return a 404 error before the request reaches Jenkins.

Then, we’ll add the actual proxy settings. The configuration begins by including the Nginx-supplied proxy_params which ensure information like the hostname, the protocol of the client request, and the client IP address are retained will be available in our log files. Next, the proxy_pass sets the protocol and address of the proxied server, which in our case is the Jenkins server accessed on the localhost on port 8080. Then, we increase the proxy_read_timeout from Nginx’s 60 second default to the project’s recommended 90 second value. And finally we add the proxy_redirect to ensure that the responses are properly rewritten to include the proper host name.

Be sure to substitute your SSL-secured domain name in the proxy_redirect line below:

Step Two — Configuring Jenkins

For Jenkins to work with Nginx, we need to update the Jenkins configuration so that the Jenkins server listens only on the localhost interface rather than all interfaces (0.0.0.0). If Jenkins listens on all interfaces, then it’s potentially accessible on its original, unencrypted port (8080).

We will modify the /etc/default/jenkins configuration file to make these adjustments.

sudo nano /etc/default/jenkins

Locate the JENKINS_ARGS line and add --httpListenAddress=127.0.0.1 to the existing arguments:

Now that we’ve restarted both servers, we should be able to visit the domain using either HTTP or HTTPS. HTTP requests will be redirected automatically to HTTPS, and the Jenkins site will be served securely.

Step Three — Testing the Configuration

We’ll test the configuration by resetting the administrative password now that we’ve enabled encryption. We’ll start by visiting the site via http to verify that we reach Jenkins and are redirected to https as we expected:

In your web browser, enter “http://your.ssl.domain.name“, substituting your domain for your.ssl.domain.name. After you press enter, the URL should start with https and the location bar should indicate that the connection is secure.

We’ll enter admin in the “User” field and the auto-generated password that Jenkins created and stored when we installed it.

sudo cat /var/lib/jenkins/secrets/initialAdminPassword

If you’ve reset the admin user’s password, enter that password instead. Either way, once we log in, we’ll change the password to be sure it’s secure.

Click “admin” in the upper-right and select “Configure” from the dropdown menu. Enter and confirm the new password and click “Save”. You can now use the Jenkins web interface securely.

Conclusion

In this tutorial, after completing the prerequisites, we configured Nginx as a reverse proxy to Jenkins’ built-in web server in order to secure our credentials and other information transmitted via the Web interface. Now that Jenkins is secure, you can learn how to set up a continuous integration pipeline to automatically test code changes. Other resources to consider if you are new to Jenkins are the Jenkins project’s “Getting Started: Create your first Pipeline tutorial or the library of community-contributed plugins.