Jenkins Configuration Instructions

============== Instructions to configure jenkins for building ros industrial repos

Required packages

ros-groovy
Moveit
Moveit for pr2 binaries

Installation steps

Install jenkins

Go to "http://pkg.jenkins-ci.org/debian-stable/" and download the "jenkins_1.509.2_all.deb" package to a local directory

Open a terminal and do the following:

sudo dpkg -i /path/to/debian/jenkins_1.509.2_all.deb
sudo apt-get install -f

Note: This installation procedure is preferred for now since a required plugin (plot plugin) is incompatible with the latest version of jenkins (version 1.524 ). When this issue is fixed then installing jenkins should be done as follows:
```
sudo apt-get install jenkins
```

Install associated tools

	sudo apt-get install cppcheck
	sudo apt-get install cloc
	sudo apt-get install python-rosinstall

Access jenkins from a browser

Open a browser and enter "http://localhost:8080/" in the address bar

Install the following plugins

Go to the jenkins home page and then to the Manage Plugins link:
- Manage Jenkins -> Manage Plugins
Install the plugins listed below:
- Warnings plugin
- Static Code Analysis Plug-ins
- Plot Plugin
- Violations Plugin
- Cppcheck Plugin

Configure jenkins

From jenkins home page go to:
- Manage Jenkins -> Configure System
Under "Home directory" hit the "Advanced..." button
Set the "Workspace Root Directory" as "${ITEM_ROOTDIR}/workspace"
Set the "Build Record Root Directory" as "${ITEM_ROOTDIR}/build"

Installing the "jenkins_config" repo

Open a terminal and login as the jenkins user
```
  sudo su jenkins
```

Clone the "jenkins_config" repository

  cd
  git clone https://github.com/ros-industrial/jenkins_config.git jenkins_config

Change git configuration

  cd jenkins_config
  git config core.fileMode false

Switch to appropriate git branch (required for projects like ros-industrial that have a different workspace config than the default jenkins setup)
```
  git checkout <branch_name>
```
Open the crontab file for editing
```
  crontab -e
```
When asked to "Select and editor" enter "2" for nano.
Append the following lines to the cron file in order to run the trigger script every 5 minutes
```
  */5 * * * * /bin/bash /var/lib/jenkins/jenkins_config/scripts/trigger_jobs.sh > /var/lib/jenkins/cron_log.txt
```
Save the cron file once the changes have been made. From this point on, the "trigger_jobs.sh" script will check your jenkins jobs periodically and will trigger a build if any of their tracked repositories has changed.
This script will also create any jobs listed in the "workspaces" repo directory that don't have a designated directory in the jenkins "jobs" folder. If a build was issued, you can see its current progress in the browser. In addition, the output produced will be saved to the file "cron__log.txt"
(Optional) Run the trigger script inmediately

Instead of waiting for cron to run the script you can call it directly. You must log in as the jenkins user and then run the following from the jenkins home:
```
  jenkins_config/scripts/trigger_jobs.sh
```

User Controls (Optional)

If access controls or other security are used on the jenkins server, then some care must be taken to ensure that the job scripts run correctly.

Credentials are required in order to create jobs. For a terminal session, credentials can be entered using the jenkins login command cd java -jar jenkins-cli.jar -s login --username --password . ./jenkins_config/scripts/trigger_jobs.sh

In most cases, credentials aren't required for the scripts to initiate a build

Email setup (Optional)

The automatically created jenkins jobs aren't configured to send emails after each build. In order to have jenkins send email notifications after each build open jenkins from a browser and do the following:

Go to Manage Jenkins -> Configure System
In the "E-mail Notification" tab, populate each field with the following info:

SMTP server - smtp.gmail.com
Default user e-mail suffix - @gmail.com

Use SMTP Authentication - yes
User Name - your.email
Password - p******d

Use SSL - yes
SMTP Port -465
Reply-To Address - noreply@gmail.com
Charset - UTF-8

Hit "Save" or "Apply" in order to save changes.
In your jenkins job go to: Configure -> Add post build-action-> E-mail Notification
Populate the "Recipients" text box with the email addresses that you would like jenkins to send notifications to.

#####Note:
The configuration above requires a vaild gmail account. If a non gmail account is used then the SMTP server information needs to be changed accordingly. Regardless of the SMTP, the job can send notifications to emails from any domain.

Creating new jenkins jobs

In order to create a new jenkins job, a "my_new_job.rosinstall" file needs to be added to the "workpaces" directory of the repo. The new job will be named the same as the file without the ".rosinstall" extension and must list each tracked repo as in the following example:

my_new_job.rosinstall:

    - git: {local-name: src/great_repo, version: stable-branch, uri: 'https://github.com/my_repos/great_repo.git'}  
    - git: {local-name: src/really_cool_repo, version: awesome-branch, uri: 'https://github.com/my_repos/really_cool_repo.git'}  
    - git: {local-name: src/broken_repo, version: broken-branch, uri: 'https://github.com/my_repos/broken_repo.git'}  
    - git: {local-name: src/much_cooler_repo, version: awesome-branch, uri: 'https://github.com/my_repos/much_cooler_repo.git'}

#####Note:
It is required that each repository gets saved in the "src" directory of the job's workspace, otherwise it will not be built.

The job will be created and added to jenkins the next time that the "trigger_build.sh" script runs.

Jenkins tips

Login as the jenkins user

	sudo su jenkins

Go to the jenkins home

	sudo su jenkins
	cd

Force a jenkins restart from a terminal

	sudo /etc/init.d/jenkins restart

ros-industrial / jenkins_config