Installing, configuring and running Jenkins Continuous Integration server

installing and configuring jenkinsci tutorial

This tutorial is part of Jenkins tutorial series on Popularowl.

During this tutorial you will learn how to install Jenkins server and perform the initial configuration.

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 your development projects.

Prerequisites

  • Access to Linux server. You can use VirtualBox locally or one of cloud platforms (we will use Digital Ocean in this tutorial but you can use any other).

Installing Jenkins

This tutorial does not cover setting up new servers part. See the how to guide from Digital Ocean. Or use VirtualBox guide.

For the purpose of installing JenkinsCI, I have prepared a new server with the fresh version of Ubuntu 16.04.6 x64 server on Digital Ocean.

The official Jenkins documentation has steps for Ubuntu installation. I’ll summarise the required steps.

Login to your Ubuntu server via ssh run the following shell commands:

$: wget -q -O - http://pkg.jenkins-ci.org/debian/jenkins-ci.org.key | sudo apt-key add -
$: sudo sh -c 'echo deb http://pkg.jenkins-ci.org/debian binary/ > /etc/apt/sources.list.d/jenkins.list'
$: sudo apt-get update
$: sudo apt-get install default-jre
$: sudo apt-get install jenkins

The above commands will:

  • Get Jenkins Debian key, and add it to your system.
  • Update the apt-get package index.
  • Install Java runtime. Jenkins is Java application and needs JVM to be present on the system.
  • Perform the actual Jenkins install on Ubuntu machine.

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. If you want to see the this configuration its in /etc/init.d/jenkins

Logs for Jenkins application are accessible at /var/log/jenkins/jenkins.log

You are now ready to visit your Jenkins CI via Internet browser.

By default Jenkins starts listening on port 8080.

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

jenkins initial setup screen after installation

During 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

This part of tutorial is about making it production ready.

First we will add 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

The above commands will:

  • Install the Nginx server
  • Navigate you to Nginx configuration directory.
  • Backup default Nginx proxy configuration.
  • Open the new default configuration file with vi editor (you can of course use the Linux file editor of your choice)

Now you have to add the following contents to the default configuration file to finish Nginx 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.

For example:

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.

$: cd /etc/nginx/sites-available
$: vi default

The file now looks like this

# 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 lines I 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 very powerful tool to configure firewall rules on your box but for our needs only 2 shell command requests are needed:

$: 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.

Did you like this post?
Subscribe to receive new Popularowl
tutorials and posts

5 Responses

  • We have implemented comments on Popularowl blog and this is quick test of the actual look & feel

    • I have added another part of the tutorial with Docker container and Terraform examples. It lives here.

  • Hector

    hello,
    Thank you very much for the post.
    I have a question, how can I make the url different?

    Example works for me if I place
    location / {......}
    resolves me for my server nginx that by default solves by port 80. In other words http://localhost/ it returns me the page of Jenkins (OK).

    Now what I need is that with
    location /jenkinsapp {......}
    http://localhost/jenkinsapp I return the Jenkins page, however it is returning 404 not found (http://localhost/login?from =% 2Fjenkin)

    • Hector

      I solved it.
      Updated me jenkins.yml for me docker-componse and add:
      - JENKINS_OPTS="--prefix=/jenkinsapp "

      finally it would be:

      environment:
      – JENKINS_OPTS=”–prefix=/jenkinsapp ”
      – JENKINS_HOME=/var/jenkins_home
      – TMP=/var/jenkins_home/tmp
      – TEMP=/var/jenkins_home/tmp
      – TMPDIR=/var/jenkins_home/tmp

      • hi,
        great job for solving it.

        and yes, you have to setup server path on Jenkins master server if you are planning to run it on the custom Url path.

        you did this via environment variables, which is great.
        I have added the section about this to the post.

Post Your Comment

Your email address will not be published.