Installing and configuring Jenkins Continuous Integration server

This tutorial is part of Jenkins tutorial series on Popularowl.

In this tutorial we learn how to install Jenkins CI server and get it ready to run jobs.

We will use Nginx reverse proxy to make your installation production ready.

After finishing the tutorial you will be able to start using your own continuous integration server and automate development projects.

Prerequisites

Access to the Debian Linux server. You can use VirtualBox locally or one of many cloud platforms which allow you create / destroy virtual servers. We are using Digital Ocean cloud as example for this tutorial.

Installing Jenkins

This tutorial does not cover provisioning new VM server part. See the how start new VM to guide from Digital Ocean. Or if you are using local VM see VirtualBox guide.

For the purpose of installing JenkinsCI, I have booted up a new VPS with the fresh version of Ubuntu Linux on Digital Ocean.

The official Jenkins documentation has steps for installation on Debian/Ubuntu servers. We are following these official guidelines.

sudo wget -O /usr/share/keyrings/jenkins-keyring.asc https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key
sudo 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 sudo apt-get install fontconfig openjdk-17-jre -y
sudo apt-get install jenkins -y

What the above commands do?

Get Jenkins Debian public key and add it to your system.
Install Java runtime environment. Jenkins is Java application and needs JVM to be present on the system to run.
Perform the actual Jenkins CI install on Debian VPS server.

The installation process will create a jenkins user under which CI server will be running.

It will configure Jenkins CI server to be run as linux daemon process. Beginning with Jenkins 2.335 installation will configure systemd to manage your Jenkins installation. You can use systemctl commands to control services which are managed by systemd.

Run the following command to see the status of JenkinsCI

	sudo systemctl status jenkins

Jenkins.service status should be active (running). You are now ready to visit your Jenkins via Internet browser, by default it starts on the port 8080.

Go to http://your-ip-address:8080 and you should see the initial welcome screen.

jenkins initial setup screen after installation

During the installation, Jenkins has created the administrator password and stored it in the specific file.

As it says in the instructions, you can fetch the admin password from /var/lib/jenkins/secrets/initialAdminPassword, enter it and press continue to finish the setup.

Click to install suggested plugins.

Create the admin user. Remember the details you enter in this screen as after the setup is done, you will use them to login as admin user.

Select default options on the following screens and you are ready to start using Jenkins CI server!

jenkins setup completed and ready to use

Congratulations, you now have your own installation of Jenkins CI server!

You can start using it for your projects now.

The next part of this tutorial is about making your Jenkins server production ready and will be helpful if you are planning to make it available publicly.

Making Jenkins CI production ready

First we will install Nginx as reverse proxy for Jenkins server.

Nginx is a powerful web server as well as a great reverse proxy. In our case we want to use it in front of our Jenkins application:

To manage all security configurations like SSL certificates and incoming request security.
To allow all incoming requests to hit traditional http ports 80 / 443 and leave Jenkins CI server running internally on port 8080.

Run the following commands on your linux server to install Nginx and remove default configuration.

sudo apt install nginx
cd /etc/nginx/sites-available
mv default default.backup
vi default

What the above commands do?

Install the Nginx server
Navigate you to Nginx configuration directory.
Backup default Nginx proxy configuration.
Open the new default configuration file for editing

Now you have to add the following contents to the default Nginx configuration file to proxy setup.

# Redirect to Jenkins on port 8080
upstream app_server {
    server 127.0.0.1:8080 fail_timeout=0;
}

server {
	listen   80;
	listen   [::]:80 default ipv6only=on;

	# Make site accessible from http://localhost/
	server_name localhost;

	location / {
	    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
	    proxy_set_header Host $http_host;
	    proxy_redirect off;

	    if (!-f $request_filename) {
	      proxy_pass http://app_server;
	      break;
	    }
	}
}

We need to restart Nginx to apply new configuration

sudo service nginx restart

Custom Url for JenkinsCI server

As one of the readers pointed in the comments under this post, there might be a requirement to run Jenkins under custom url like hostname/jenkinsapp

In this case, you would have to setup the Jenkins to accept custom url.

This can be done via JENKINS_ARGS environment variable. It requires restarting Jenkins server. Several other parameters are supported as well.

export JENKINS_ARGS="--prefix=/jenkinsapp"

Protecting JenkinsCI installation with basic login password

If you are planning to have limited number of users who can access your Jenkins CI server, I would recommend to protect the access to overall site with basic username / password authentication.

This can be implemented by Nginx with the help of .htpasswd file which stores all users who can access the site.

.htpasswd file can be generated with the following htpasswd utility by providing it the path where to store the file (it will prompt for user password)

htpasswd -c /etc/nginx/.htpasswd username

Once you have the file created you will need to update default Nginx configuration file we created in the previous step.

# Redirect to Jenkins on port 8080
upstream app_server {
    server 127.0.0.1:8080 fail_timeout=0;
}

server {
	listen   80;
	listen   [::]:80 default ipv6only=on;

	# Make site accessible from http://localhost/
	server_name localhost;

	location / {
	    # Adding basic authorisation to Nginx
	    auth_basic "Please Login";
	    auth_basic_user_file /etc/nginx/.htpasswd;

	    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
	    proxy_set_header Host $http_host;
	    proxy_redirect off;

	    if (!-f $request_filename) {
	      proxy_pass http://app_server;
	      break;
	    }
	}
}

Note the new added lines auth_basic and auth_basic_user_file we just added.

We now have to restart Nginx in order to apply new configuration

sudo service nginx restart

Disabling access to port 8080 to external requests

Now we have our Jenkins CI server listening 8080 and Nginx proxing all incoming requests from port 80 to 8080. The last step we need in to close direct access to the Jenkins through 8080 so all requests are coming through standard http port 80.

For this we are going to use iptables

Iptables is a very powerful linux tool to configure firewall rules on your VM. For our purpose we only need 2 shell command requests

iptables -A INPUT -p tcp --dport 8080 -s localhost -j ACCEPT
iptables -A INPUT -p tcp --dport 8080 -j DROP

We are instructing Ubuntu to allow all the incoming requests to 8080 port from localhost (internal). And dropping all other requests.

After these are run you shouldn't be able to access http://yourdomain:8080 directly anymore. And http://yourdomain should still redirect to Jenkins as before.

Summary

To sum up, the goal of this part of tutorial was to install and setup your own Jenkins continuous integration server.

After that, we went through the initial steps required to make your Jenkins server production ready.

You can now use this Jenkins installation to complete the next steps of Popularowl Jenkins CI tutorial.

Next part of the tutorial is about automating the above Jenkins CI install steps with Docker and Terraform.