This is the second part of the three-part gist for setting up a basic CI environment on a single machine (e.g., a laptop), for dev / test / proof-of-concept, etc.
This CI environment consists of:
- Gitlab (Community Edition) as a source-code repository
- Jenkins for build and continuous integration Gitlab cannot be used without a mail server (Postfix). So, we also set up Postfix.
This part of the three-part gist outlines the steps to configure and sanity-test Gitlab CE, and then install Jenkins. Here we explain:
- Reconfiguring Gitlab after installation
- Creating users and project repos in Gitlab
- Accessing Gitlab through SSH
- Installing Jenkins and accessing the Jenkins dashboard
For reference, please follow the three links below:
- Continuous Integration with Gitlab and Jenkins: Gitlab Setup
- Continuous Integration with Gitlab and Jenkins: Gitlab Configuration and Jenkins Setup
- Continuous Integration Pipeline with Jenkins and Gitlab
Here we describe the setup steps on Ubuntu 19.10 platform (Ubuntu Desktop), allocated 5GB RAM and 4 CPUs.(We actually set this up on a Ubuntu Virtual Machine on VirtualBox, running on Windows.)
A bash-like shell will be needed to run commands for the set-up.
The setup on other Linux flavors will be very similar.
Note: In our setup, the machine name (hostname) was archlab and the OS user running the commands was techie, included in the sudoers list. You will find these two string tokens in the rest of the gist. You should be able to replace these with suitable values for your environment.
In this set-up, the following versions have been used:
Gitlab: Community Edition 12.9.3
Jenkins: 2.222.1
Gitlab CE comes bundled with Postgresql and Redis databases, nginx web server for reverse-proxying the Gitlab server (HTTP), and a few other software components. It also depends on a Postfix to send notifications by email, although this mail server has to be installed separately.
Before Gitlab CE can be accessed even for the first time, it has to be 'reconfigured'.
Reconfiguring Gitlab is simple, but there is one part of this exercise that consists of serveral steps: enabling secure access.
It is recommended that Gitlab CE be configured at the outset, to allow HTTPS access only. By default, Gitlab generates a LetsEncrypt SSL key pair when it is reconfigured for the first time. But in our set-up, we will generate a key pair using OpenSSL on Ubuntu: instead of using LetsEncrypt, we will create a self-signed certificate.
Check if openssl is installed: run openssl version. If it is not installed, for our purpose, it is sufficient to install it as follows:
sudo apt-get install openssl
Create a temporary directory for your SSL key pair: mkdir ~/genkey && cd ~/genkey
Create openssl key: sudo openssl genrsa -des3 -out gitlab.key 2048
You will be prompted to enter a passphrase. Please remember the passphrase.
Check that the key is generated: ls ~/genkey (should display a file gitlab.key)
Create a certificate signing request: sudo openssl req -new -key gitlab.key -out gitlab.csr
The resulting interactive prompts are shown below:
Enter pass phrase for gitlab.key:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:IN
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:BLR
Organization Name (eg, company) [Internet Widgits Pty Ltd]:TYORG
Organizational Unit Name (eg, section) []:TYUNIT
Common Name (e.g. server FQDN or YOUR name) []:TY
Email Address []:
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
The entries above can be fictitious. You will be prompted for the passphrase for the key you had generated earlier. Do not enter enter any challenge password.
At this stage a file named ~/genkey/gitlab.csr is generated.
Now recreate the openssl key by removing the passphrase.
sudo cp -v gitlab.{key,original}
sudo openssl rsa -in gitlab.original -out gitlab.key
At this stage the passphrase previously set, will have to be supplied again.
sudo rm -v gitlab.original
We will now be left with the files: ~/genkey/{gitlab.csr, gitlab.key}
Finally, create the self-signed certificate, and delete the certificate self-signing request.
sudo openssl x509 -req -days 365 -in gitlab.csr -signkey gitlab.key -out gitlab.crt
sudo rm -v gitlab.csr
We will now be left with the key and certificate files: ~/genkey/{gitlab.key, gitlab.crt}
Assign appropriate file permissions to the key pair, and copy the key pair into a directory: /etc/gitlab/ssl
chmod 600 ~/genkey/gitlab.*
sudo mkdir -p /etc/gitlab/ssl
sudo cp ~/genkey/gitlab.* /etc/gitlab/ssl/.
Now we have to update certain configuration settings in the file /etc/gitlab/gitlab.rb.
Tip: Take a back-up of this file (sudo cp /etc/gitlab/gitlab.rb /etc/gitlab/gitlab.rb.bak)
Edit the file /etc/gitlab/gitlab.rb: modify the line below
external_url 'http://gitlab.example.com'
to reflect the following:
external_url 'https://<your_machine_name>'
Edit the file /etc/gitlab/gitlab.rb so that it is consistent with your Postfix installation:
Uncomment the line: # gitlab_rails['smtp_enable'] = true
Uncomment the line: # gitlab_rails['smtp_address'] = "smtp.server" and modify it to: gitlab_rails['smtp_address'] = "localhost"
Uncomment the line: # gitlab_rails['smtp_port'] = 465 and modify it to: gitlab_rails['smtp_port'] = 25
Uncomment the line: # gitlab_rails['smtp_domain'] = "example.com" and modify it to: gitlab_rails['smtp_domain'] = "localhost"
Uncomment the line: # gitlab_rails['smtp_enable_starttls_auto'] = true and set it to: gitlab_rails['smtp_enable_starttls_auto'] = false
Uncomment the line: # gitlab_rails['smtp_tls'] = false
Edit the file /etc/gitlab/gitlab.rb as follows:
Uncomment the following lines:
# nginx['enable'] = true
# nginx['client_max_body_size'] = '250m'
# nginx['redirect_http_to_https'] = false
Since we have set the external URL to https://<your_machine_name>, explicit HTTPS redirect is not required.
Edit the file /etc/gitlab/gitlab.rb as follows:
Add the two lines:
nginx['ssl_certificate'] = "/etc/gitlab/ssl/gitlab.crt"
nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/gitlab.key"
Uncomment the line: # nginx['ssl_protocols'] = "TLSv1.2 TLSv1.3"
Run the following command to reconfigure Gitlab CE:
sudo gitlab-ctl reconfigure
This command will take at least a few minutes to execute, and produce lots of verbose output. In the end, the following message will come up:
gitlab Reconfigured!
Restart Gitlab CE:
sudo gitlab-ctl restart
This should produce the following output:
ok: run: alertmanager: (pid 19093) 1s
ok: run: gitaly: (pid 19113) 1s
ok: run: gitlab-exporter: (pid 19122) 0s
ok: run: gitlab-workhorse: (pid 19133) 0s
ok: run: grafana: (pid 19149) 0s
ok: run: logrotate: (pid 19158) 0s
ok: run: nginx: (pid 19178) 0s
ok: run: node-exporter: (pid 19192) 0s
ok: run: postgres-exporter: (pid 19208) 1s
ok: run: postgresql: (pid 19223) 0s
ok: run: prometheus: (pid 19231) 0s
ok: run: redis: (pid 19243) 0s
ok: run: redis-exporter: (pid 19248) 0s
ok: run: sidekiq: (pid 19263) 1s
timeout: run: unicorn: (pid 31805) 4984s
Now the Gitlab Administration Console (also known as Dashboard) should be accessible, by pointing your browser at:
https://<your_machine_name>
First time this URL is accessed, the browser will raise a warning, since the server-side SSL certificate was self-signed, i.e., not signed by a well-known certificate authority. Choose the option to add this URL as an exception, and the browser will display the Gitlab Dashboard.
Administrator Password: First time after Gitlab CE has been installed and reconfigured, when we access the Dashboard, we will be asked to set a password for the Administrator.
Once we set a suitable administrator password, the login page will be displayed. You can log in as Administrator using the credentials:
Username: root
Password: <Admin Password set just now>
To check if Gitlab CE notifications are working properly, you can verify that a new mail has been sent to your mailbox, i.e., ~/.mail/new folder (please see first part of the gist where Postfix configuration has been explained).
You can open the mail, and a message like the following will be seen:
Subject: Password Changed
...
The password for your GitLab account on https://<your_machine_name>
has successfully been changed.
At this point, we should create a few users in Gitlab CE, and a few project repos. We should push some changes into the repos, and make sure basic functionality is working as expected.
Once logged in as Administrator, we can set a few global policies for creation of project repos.
From the top horizontal menu, select 'Admin Area' (there will be a tool icon for this menu item). Then, from the left-hand panel, scroll down and select Settings.
On the right-hand panel, several settings appear.
- Expand 'Sign Up Restrictions' and uncheck 'Sign-up Enabled'.
- Expand 'Account and Limit' and set Default Project Limit to 100. This means an ordinary user logged in, cannot create (sign up) other user accounts (only the Administrator can do so). And a user can create at most 100 project repositories. This is just to show how Administrative settings can be applied.
Let's first create an OS user 'gitusr01'. On an Ubuntu terminal, run the command: sudo adduser gitusr01.
We will create a user on Gitlab corresponding to this user.
Again, log in to GitLab as UI as 'Administrator'.
From the top horiozontal menu, select 'Admin Area' icon.
From the left-hand panel that shows up, expand 'Overview' and select 'Users'.
From the right-hand panel, click on 'New User' and supply Name (gitusr01), Username (gitusr01) and email. Accept the defaults for the remaining fields and click on 'Create user' button at the end.
A user with username gitusr01 will be created and an email will be sent with a link to specify a password. In our environment, all emails will reach the inbox of the OS user involved in creating this entire setup (including installation of Postfix, Gitlab, Jenkins, etc.). So, we can retrieve the email from the inbox (~/.mail/new), where the home directory is that of the OS user involved with this set-up (not gitusr01).
Just list the files in (~/mail/new) and cat the newest file in that directory. It should contain a link to set password:
...
Subject: Account was created for you
...
Hi gitusr01!
Your account has been created successfully.
login.................. gitusr01@localhost
Click here to set your password:
https://<your_machine_name>/users/password/edit?reset_password_token=<some_token_string>
Now, pretending that you are gitusr01, open the above link in a browser, and set a password. Actually you will receive another notification (email) that your password has been set successfully.
As user gitusr01, from the Gitlab UI, click on 'New Project' button, to create a new Project repo.
Specify a project name testproj01, and keep the project 'Private'. Let's not create a README now. Click on the 'Create Project' button at the end.
A project repo will be created, and a HTTP URL to clone the project will be displayed.
Git Client: In case git client is not installed on your machine, first run the command: sudo apt install git-core.
Open a terminal on Ubuntu, and log in as the OS user named gitusr01, i.e., run the command: su - gitusr01.
Before cloning the repo (testproj01), the following settings are required (run the commands below):
git config --global user.name "gitusr01"
git config --global user.email "gitusr01@archlab"
git config --global http.sslverify false
Now clone the repo: git clone https://archlab/gitusr01/testproj01.git. The output will be like:
Username for 'https://<your_machine_name>': gitusr01
Password for 'https://gitusr01@<your_machine_name>':
warning: You appear to have cloned an empty repository.
Note: You have to supply Gitlab password for user gitusr01.
Troubleshooting: If you had not set http.sslverify false, the following error will occur: server certificate verification failed. CAfile: none CRLfile: none.
A directory named testproj01 would have been created when you cloned the project, under /home/gitusr01. Navigate to this directory: cd ~/testproj01.
Create a README and push the changes to Gitlab CE:
echo "README" >> README.md
git add .
git commit -m "first commit"
The output for git commit will be like:
[master (root-commit) 6795d47] first commit
1 file changed, 1 insertion(+)
create mode 100644 README.md
Now push the changes to Gitlab: git push -u origin master. The output will be:
Username for 'https://<your_machine_name>': gitusr01
Password for 'https://gitusr01@<your_machine_name>':
Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Writing objects: 100% (3/3), 209 bytes | 209.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To https://<your_machine_name>/gitusr01/testproj01.git
* [new branch] master -> master
Branch 'master' set up to track remote branch 'master' from 'origin'.
You can also navigate to the project on Gitlab UI and verify that these changes are reflected.
This shows that Gitlab basic functionality is working.
It is preferable to access Gitlab from an OS terminal through password-less SSH using the Git client. In this section, we will set this up.
Create an OS user on Ubuntu, named gituser02, by running sudo adduser gitusr02.
From Git UI, as Administrator, create another Gitlab user named gitusr02.
As usual, set a Gitlab password for gitusr02, by opening the appropriate link in a browser (sent by email notification - see above for the steps with gitusr01).
Log in to Gitlab UI, as gitusr02, and create an empty project repo testproj02.
Open a terminal on Ubuntu and login as the OS user gitusr02: su - gitusr02
Generate a SSH key pair: ssh-keygen -t rsa -C "gitusr02@archlab". Let the passphrase be empty.
Generating public/private rsa key pair.
Enter file in which to save the key (/home/gitusr02/.ssh/id_rsa):
Created directory '/home/gitusr02/.ssh'.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/gitusr02/.ssh/id_rsa.
Your public key has been saved in /home/gitusr02/.ssh/id_rsa.pub.
The key fingerprint is: ...
Now we have to copy the SSH public key to Gitlab.
Login to Gitlab UI as gitusr02. From the top horizontal menu (extreme right), click on the profile icon and click on 'Settings'.
On the left-hand panel, you can see 'User Settings' open up. Select 'SSH Keys' from the menu items below 'User Settings'.
Now on the right-hand panel, copy paste your public key to the text area named 'Key' and click on the 'Add Key' button.
Note: Your public key is the contents of the file /home/gitusr02/.ssh/id_rsa.pub.
Back on your Ubuntu terminal, add the identity of the SSH user by running these commands:
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa
The output of the last command should be: Identity added: /home/gitusr02/.ssh/id_rsa (gitusr02@<your_machine_name>)
Finally run the command: ssh-add -l. The output should be like:
3072 SHA256:1wRJ7GY8iBK+I4t7991+QU2noVcbQKvjCyHJZ8++XpA gitusr02@<your_machine_name> (RSA)
Now access Gitlab over SSH by running the following command.
ssh -T git@<your_machine_name>
You will get a message like:
The authenticity of host '<your_machine_name> (127.0.1.1)' can't be established.
ECDSA key fingerprint is SHA256:bG2BEJv6er17rV4X7L+T0PxvQ1+FgECCpCpA+wp29y0.
Are you sure you want to continue connecting (yes/no/[fingerprint])?
Type yes and you should see the following output:
Warning: Permanently added '<your_machine_name' (ECDSA) to the list of known hosts.
Welcome to GitLab, @gitusr02!
So you are able to login to Gitlab using SSH, and without a password.
Now we clone and push to, our project repo.
First update the git client settings:
git config --global user.name "gitusr02"
git config --global user.email "gitusr02@archlab"
git config --global http.sslverify false
Then, run the following commands to make changes to the project:
git clone git@<your_machine_name>:gitusr02/testproj02.git
cd testproj02
echo "README" >> "README.md"
git add .
git commit -m "first commit"
git push origin master
All the above commands should succeed.
To run Jenkins, Java must be installed on the system.
Install OpenJDK. We installed one of the recent versions (Open JDK 13). You could install version 8 or later.
sudo apt install openjdk-13-jdk
Note: The current version of Jenkins expects JDK 9. However, it can be configured to use a more recent version (explained later).
Set up the Ubuntu package repo, by running the command:
wget -q -O - https://pkg.jenkins.io/debian/jenkins.io.key | sudo apt-key add -
And then run:
sudo sh -c 'echo deb https://pkg.jenkins.io/debian-stable binary/ > /etc/apt/sources.list.d/jenkins.list'
Run update: sudo apt update
Troubleshooting: You may come across an error message like:
W: GPG error: https://pkg.jenkins.io/debian-stable binary/ Release: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 9B7D32F2D50582E6
In that case, run the following command:
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 9B7D32F2D50582E6
And then run sudo apt update
Install Jenkins: Run sudo apt-get install jenkins
Output messages like the following will be seen:
Preparing to unpack .../jenkins_2.222.1_all.deb ...
Unpacking jenkins (2.222.1) ...
Setting up daemon (0.6.4-1build2) ...
Setting up jenkins (2.222.1) ...
Troubleshooting: At this point Jenkins server may not start up successfully.
- By default Jenkins starts up on port 8080. But Gitlab CE (running on the same machine) may have been already started on that port (although it uses an nginx reverse proxy on port 80). So update the Jenkins configuration file
/etc/default/jenkins: setHTTP_PORT=3030(or any other port that does not conflict). - Jenkins may not run by default on a Java version higher than version 9. You may get an error like:
SEVERE: Running with Java class version 53.0, but 52.0 is required.. Setenable-futur-javainJENKINS_ARGSin the file/etc/default/jenkins. The corresponding line should now read:JENKINS_ARGS="--webroot=/var/cache/$NAME/war --httpPort=$HTTP_PORT --enable-future-java"
Verify Jenkins is up and running: Run the command: sudo systemctl status jenkins
The output message must include:
jenkins.service - LSB: Start Jenkins at boot time
...
Active: active (exited) since ...
When Jenkins is installed as above, an administrative password is generated by the installer, although no user is created. This password can be retrieved from the file: /var/lib/jenkins/secrets/initialAdminPassword.
Access the Jenkins dashboard : http://localhost:3030/ (Note that we have changed the Jenkins port from default 8080 to 3030). First time, you have to supply the administrative password generated by the installer.
You will be prompted to complete a few final configuration steps before using Jenkins further:
- Install suggested plugins (or Select plugins to install): Choose 'Install suggested plugins'. This takes at least a few minutes time.
- Create first admin user: Supply an admin user (say
jenkinsadmin) and a password.
Finish the configuration, and you will be redirected to the login page again. We can supply the login credentials of the admin user just created, and continue to use Jenkins.
Troubleshooting: Some of the suggested plugins may not get installed successfully. Ignore the errors and finish off the configuration step. If necessary, they can be installed later. Usually plugins like timestamper, pipeline, git, workspace cleanup, github branch source, subversion, ldap, etc. get installed smoothly and many of them are useful.