Jenkings-CI, formerly known as Hudson before Oracle acquired Sun, can be installed on Ubuntu pretty easily with the apt-get package manager, but getting it working with Ruby on Rails app, Github with rollified Users involves some glitches, so I’m writing them down for posterity. A good documentation on this is still missing.
Setting up Users with different permissions and hooking into private Github repos is too tricky. So, this is the post on setting up the Jenkins-CI on Ubuntu with a Githubfied private repository.
- Setup the Jenkins CI
- Integrating with Git and Github
- Run the test build when changes gets pushed to Github
- Run the test build when new branch is pushed to Github
- Notify back to the committer(or team members) if the build fails
SSH into your box. It can be a Vagrant box, VMWare, … I’ve used VMWare Fusion for this write up. Then install it with the following commands.
wget -q -O - [http://pkg.jenkins-ci.org/debian/jenkins-ci.org.key](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](http://pkg.jenkins-ci.org/debian) binary/ > /etc/apt/sources.list.d/jenkins.list sudo aptitude update sudo aptitude install jenkins
Now that Jenkins is installed, we want to get a headless display configured
for our browser based tests. First go to
Manage Jenkins > Manage Plugins >
Available and install the Hudson Xvnc plugin (this works with Jenkins
despite its name). Schedule Jenkins to restart to pickup the plugin. Once
installed this gives us the ability to start a headless display automatically
when we configure our jobs, more on that later.
With Jenkins configured we need to ensure the required software is installed on the server:
$ sudo apt-get install vnc4server
vncserver requires a password to be set before it can be used, this needs to
be set before Jenkins can make use of the vncserver. For this we need to
switch to the jenkins user and set a password.
$ sudo -Hiu jenkins $ vncserver Enter a password, and verify it $ vncserver -kill :1 # or whichever display the vncserver output mentioned
You have to install
imagemagick with to see the screenshot or running
browser via Xvnc. But its optional.
Creating the first Job build
After installing jenkins and going to
[http://the.ip.address:8080](http://the.ip.address:8080), you’ld see the
dashboard of Jenkins. You won’t see any
links. This is one of the trickiest part and I’ve addressed it below.
But for now, lets create our first Job build.
- First click the New Job link
- Give a sensible job name. Your project name can be a good fit but it can be anything
- Select Build a free-style software project radio button
- And OK
Configure the Job
After the above step, you’ll be taken to the job configuration form page. But before adding anything, lets add the Github plugin and some Jenkins configuration.
Install the github plugin
Now go to
Jenkins > Manage Jenkins > Manage Plugins and install
Restart Jenkins if the Bundler is not picked up
sudo /etc/init.d/jenkins restart
Setting up users with authentication
To restrict the CI system and give access to your Team members to use or see the build logs, first you’ve to create an account.
- Go to
Manage Jenkins > Configure System
- Check the
- Under Security Realm, choose
Jenkinss own user database
- Check the
Allow users to sign upcheckbox
Project-based Matrix Authorization Strategy
- Add first user with the name
adminand another with
github(Note: the username for Admin access has to be admin) For github named user, just choose the
Overall Readonly permission. We’ll use this user later with the Github hook.
Note: The admin and github user that we’ve added in the above step does not create the User. Then you’ve to create a real user with that same name. Ya, I know, its a bit weird with Jenkins UI.
Manage Jenkins > Manage Users > Create User. Create both
Lets finish up the Job configuration
Then finally you have to add the user at Project level at `Project > Configure
Enable project-based security`
After installing the gems, when tried to
rake db:migrate, it looks for
config/database.yml file and in many projects its not tracked in the repo.
So a good way is to checkin
config/database.yml.example file into the
repository and copy/rename it to
config/database.yml file before migrating
during the build process.
cp config/database.yml.example config/database.yml
or you can create a executable shell script and put such kind of actions in it
and do check-in this file into your repo. Then you can add
the build step before running the specs.
For a boilerplate rails app
#!/bin/bash -e rvm use ruby-1.9.3@myapp cp config/database.yml.example config/database.yml bundle install --without darwin bundle exec rake db:migrate bundle exec rake
For private projects on Github
If the app is public, skip this step.
Before starting your first build, we need to generate the ssh key for the
jenkins user and the RSA of Github.com has to be in the
So, lets generate the ssh keys for the jenkins user:
ssh-keygen -t rsa
Copy the contents of
/var/lib/jenkins/.ssh/id_rsa.pub file and put it in the
Github repository Admin page under Deploy keys. For the
will be at
Adding github RSA fingerprint in jenkins home (/var/lib/jenkins)
sudo su - jenkins jenkins@jenkins:~$ git clone firstname.lastname@example.org:<github_username>/repo_name.git Initialized empty Git repository in /var/lib/jenkins/github_username/.git/ The authenticity of host github.com (22.214.171.124) cant be established. RSA key fingerprint is 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added github.com,126.96.36.199 (RSA) to the list of known hosts. ^C (Hit Ctrl + C) jenkins@jenkins:~$ ls .ssh/ id_rsa id_rsa.pub known_hosts jenkins@jenkins:~$
Create the tmp directory if ignored in .gitignore which is true quite often
mkdir -p tmp/cache tmp/pids tmp/capybara tmp/sass-cache tmp/sessions tmp/sockets
And if your test has to create some directories, just create them too. In my
case, I’d to had
mkdir -p tmp/media
Hooking with the Github web-hooks
Now to run the build automagically when new commit or branch gets pushed onto Github, we have to setup the repository.
Got to the hooks page for your repository. e.g.
AVAILABLE SERVICE HOOKS > Post-Receive URLs, add
githu:github is the user that we’d created earlier.
Then we have to verify Jenkins with Github. Go to
Manage Jenkins > Configure
System and under
GitHub Web Hook, add your Github username and password and
Test Credential button to authorize once with Github.
Git Gotcha on your first build
If you see the following error after checking out your repo:
FATAL: Could not apply tag jenkins-project hudson.plugins.git.GitException: Could not apply tag jenkins-project .... .... Caused by: hudson.plugins.git.GitException: Error performing command: git tag -a -f -m Jenkins Build #4 jenkins-project Command "git tag -a -f -m Jenkins Build #4 jenkins-project" returned status code 128: *** Please tell me who you are.
You have to add the following in the jenkins user home directory:
# /var/lib/jenkins/.gitconfig [user] name = Jenkins-ci email = jenkins@localhost
Setting up the email to notify if the build fails
Manage Jenkins > Configure System and add the SMTP credentials.
Final Configuration Assertion
Since the post is TL;DR, here are the 2 screenshots of Jenkins Config and Project Config. Your configuration should resemble this.
Bonus(es) and Gotcha(s)
Gotcha with OutBound error
Sometimes we get this error
MoveTargetOutOfBoundsError. This is caused if
the window size is less than the expected one. At least I think so, not
confident. To fix this error, in
Manage Jenkins > Configure System > Xvnc
Command line put this
sh -c "USER=jenkins HOME=/var/lib/jenkins vncserver
:10 -geometry 1440x900 -depth 16". I’d to install
sudo apt-get install fluxbox. And had to
downgrade the Firefox down to
Adding the code coverage metrics
Install the Ruby metrics plugin plugin, to actually display the graphs of your code coverage.
A project called simplecov, that
seems to work really well, but the output format isn’t what jenkins expects.
simplecov-rcov, its just a
formatter for simplecov, that generate rcov style reports. So lets add this to
require simplecov require simplecov-rcov SimpleCov.formatter = SimpleCov::Formatter::RcovFormatter SimpleCov.start rails if ENV["COVERAGE"]
Bonus: Watch your acceptance test run in real graphical window
Download the VNC Viewer viewer for Mac. If you’re on other OS, you can find it by googling around.
Open up a new connection and provide the address and its port.
You can find the port its running on with the cmd:
sudo netstat -tulpn ... tcp 0 0 0.0.0.0:5910 0.0.0.0:* LISTEN 3319/Xvnc4 ...