==========================================
Hudson CI server installation step by step
==========================================

Why Hudson
==========

One of the advantages of `Hudson <hudson-ci.org/>`_ over 
`Buildbot <http://buildbot.net/>`_, for instance, is that
almost everything is done via its web interface. So anyone can
manage the continuous integration server easily.
Another advantage over the other alternatives is Hudson has many
`available plugins <http://wiki.hudson-ci.org/display/HUDSON/Plugins>`_,
so you don't need to write your own.

Hudson runs on Java, so the next step is to install Java and its dependencies.


Java and its dependencies
=========================

You can install all Java related packages this [not recommended] way::

    $ [sudo] apt-get install ca-certificates-java daemon default-jre\
    > default-jre-headless gcj-4.4-base gcj-4.4-jre-headless gcj-4.4-jre-lib\
    > icedtea-6-jre-cacao java-common libaccess-bridge-java\
    > libaccess-bridge-java-jni libgcj-common libgcj10 libjline-java \
    > openjdk-6-jre openjdk-6-jre-headless openjdk-6-jre-lib\
    > rhino tzdata-java tzdata
    

Or try installing with the information in the next section and
if you have problems, run::
    
    $ [sudo] apt-get install -f




Installation
============

The recommended installation from `Hudson site for Debian users
<http://hudson-ci.org/debian/>`_ is installing through the `.deb` package.
The advantages are: you can automatically upgrade hudson via apt and
use the `service` or `/etc/init.d` resource to start the daemon on boot.

To install Hudson as they recommend, do the following:

* Add the key to your system::
    
    $ wget -O /tmp/key http://hudson-ci.org/debian/hudson-ci.org.key
    $ [sudo] apt-key add /tmp/key


* Then install Hudson::

    $ wget -O /tmp/hudson.deb http://hudson-ci.org/latest/debian/hudson.deb
    $ [sudo] dpkg --install /tmp/hudson.deb


When you reboot the computer the web daemon will be started at
http://localhost:8080. If you don't want to reboot the computer, run::

    $ [sudo] service hudson start
    or
    $ [sudo] /etc/init.d/hudson start




Apache
======

It is not necessary for all users, but if you want to set up apache to run
the web interface, you should follow this tutorial:
http://wiki.hudson-ci.org/display/HUDSON/Running+Hudson+behind+Apache


Plugins
=======

Installing plugins in Hudson is very easy.
Just click *Manage Hudson*, then *Manage Plugins*.
The tab *Updates* shows all available updates to installed plugins.
But what we need now is to install plugins. So we must go to the
*Available* tab and check what we want to be installed and then press the
*Install* button in the end of the page.

The Hudson server hosted at http://ci.cloudsilverlining.org has the following
plugins installed for pip project:

* Hudson IRC Plugin
* Green Balls
* Hudson Continuous Integration game
* Hudson instant-messaging plugin
* Hudson Jabber notifier plugin
* Hudson Email Extension Plugin
* Hudson Mercurial plugin


Creating a Job
==============

Before Creating a Job for pip
-----------------------------

Hudson manages "jobs". Jobs are complete builds to Hudson. For instance,
you want to build pip project and run its tests with nosetests.
This section  assumes you have all needed `dependencies installed`_.

You need to set up some configuration in Hudson before creating your first job.
Go to Hudson home page, "Manage Hudson", then "Configure System".

In the Mercurial section, fill the "Add Mercurial" section with:

* Name: `hg`
* Installation directory: `/usr`
* Executable: `INSTALLATION/bin/hg`

In the Shell section fill the shell executable with `/bin/bash`.

Then press the "Save" button in the bottom of the page.


    
    
Configuring a Job Step by Step
------------------------------

* Go to the home of the Hudson web interface
* Click *New Job*
* Pick a name for the job - pip, for instance
* Mark the option "Build a free-style software project"
* Press "OK" button

Now you were redirected to the job's configuration page. Here you will
tell Hudson how it will build your job. The most important
steps are listed (assume Mercurial plugin is installed):

* Check "Mercurial" in Source Control Management section
* Fill in the repository URL with **https://github.com/pypa/pip**
* Mark "Build periodically" in *Build Triggers* section
* Add "0 0 \* \* \*" (without quotes) to tell hudson you want to
  run your build everyday at midnight
* Click "Add Build Step" in the *Build* section and pick "Execute Shell"

This box will contain all code you want your build run. To run pip's tests
we need to install pip tests's depencies and run nosetests.
Add the following lines to the box (it assumes you have virtualenv
in your system's python)::

    python -mvirtualenv --no-site-packages pip_virtualenv
    source pip_virtualenv/bin/activate
    cd $WORKSPACE/..
    easy_install -U pip
    cd $WORKSPACE
    pip install virtualenv scripttest nose
    nosetests tests -v
    
The *$WORKSPACE* environment variable is the current build workspace,
in the case above it is the clone repository path. The `cd` stuff is
a work around to a pip's bug.

The process execute above means:

* create a virtualenv called **pip_virtualenv** without shared site-packages
* activate the environment
* updates system's pip
* install pip tests's dependencies
* run nosetests in the current directory


Press the "Save" button and in the next page test if the build is correct
by clicking "Build now" button.

In the left sidebar will appear the run builds and the running (if exists).
Click the top build, then "Console Output". Now you can
watch what Hudson is doing to build your job and watch the results.




Notes
=====

If you change anything in your system environment, like updating
your environment configuration files, and realize Hudson
didn't catch your changes, try restarting it::

    $ [sudo] service hudson stop
    $ [sudo] service hudson start
    
If when you run the `start` command you get an error telling you the port
is being used, wait about 2 or 3 seconds and try the command again - it's the
time the port releasing may take.

What is covered here is the basic knowledge to start setting up and using
a Hudson server, the goal is not teaching all about Hudson or all about
how to set up every detail.

There is a running Hudson server aimed for pip project here:
http://ci.cloudsilverlining.org/view/pip


Creating a Windows Slave to Run Jobs
====================================

After starting Hudson on Linux, start your Windows machine and access the
Hudson web interface.

Adding a Windows Node to Hudson CI Server
-----------------------------------------

Click "Manage Hudson", "Manage Nodes", "New Node". The **Node name** value
must be the Windows machine domain name - mywindowsslave.myhost.com, for
instance.

The "Launch method" should be **Launch slave agents via JNLP**

.. image:: _static/launch-jnlp-slave.JPG
   :width: 500px
   :target: _static/launch-jnlp-slave.JPG

Then press the **Add** button, and in the next page click
the **Launch** icon.

.. image:: _static/slave-launch-icon.png
   :width: 500px
   :target: _static/launch-jnlp-slave.JPG

Now you are able to create jobs tied to this Windows machine.


Creating Tied Jobs
------------------

The process of creating a job is almost the same as the list in the
`Creating a Job`_ section, the only difference is that you need
to mark the **Tie this project to a node** option and select what
node you want to run that build.

There is a difference in build commands, relying on variables. On Linux
they all start with `$`, like `$WORKSPACE`.
In Windows they will be enclosed by `%`,  like `%WORKSPACE%`. And everything
you were doing depending on Bash, you will need to change to DOS
prompt commands and batch files.



.. _dependencies installed: running-tests.html#system-requirements
.. _creating a job: #creating-a-job