Compass Version1.1

Linux Quick Installation Guide and Setup

Compass consists of two applications, the Compass Server and the Compass Build Client.  Compass must be installed on the computer that will be used as the Compass Server and on each computer that will be used as a Compass Build Client.  The installation is the same for both the server and the build clients.  After downloading Compass.tar.gz, simply extract the files into the directory where you want Compass to run.  

The Compass installation requires Python 2.5.4 to be set up on each computer Compass is installed on.  If Python is not included in your distribution, or is not installed then install the latest version of Python through your distribution's package management system.  

Make sure that your PATH and PYTHONPATH environment variables are correctly defined and point to the correct version of Python.

Once you have verified python is installed and you have extracted the Compass distribution then both the Compass Server and the Compass Build Client are available to be run on that computer.

To Start the Compass Server on the machine you plan to use as your Compass Server, navigate to the extracted 'Compass' directory and in a shell execute the command:

>python start_server.py mastercfg.cfg &

This will start the Compass Server with the default parameters found in the mastercfg.cfg file; for more details on the config file parameters see the administrator manual.  The server should now be started on localhost. Open a web browser and navigate to 'http://localhost'  and you should see a page that looks like this:

To complete the Compass Server installation enter an administrator username and password and click the 'Install Server' Button.  Once you click this button you will be taken to the server Administration page.  This page has the following 9 sections:

• Logs
• Language Settings
• Server Settings
• Scripts
• Build Configurations
• Script Keywords
• User Administration
• Project Administration
• Source-Control Server

Details on each of these are provided in the administrator manual.  To set up a compass server with minimal effort, the only sections that are required to be updated are the last three: Users, Projects and Source-Control.  The rest of this installation guide sets up a Compass server with one non-admin user, one subversion source-control server, and one project that has a single build that runs whenever the repository changes as well as every 2 hours.  Finally we will set up an email notification for when our build fails.

Add a User

The first step is to add a user.  Right after installation the user administration section looks something like this:

Add a Source-Control Server

The next step is to add a source control server.  In the source-control server section there's a button labeled 'Create New Server'.  Click on this button and the new Source-Control Server dialog appears that looks like this:

In this dialog, we give our new source control server a name.  This is the name that is used internal to Compass and can be anything you want that describes which source control server this is.  The Server URL is the URL to access the server.  For a subversion server this would look like: 'svn+ssh:// This e-mail address is being protected from spambots. You need JavaScript enabled to view it /path ./'.  If the repository requires authentication then check the box for authentication and add a valid username and password in the appropriate fields.  

When you have filled out this dialog and click 'Submit',  Compass will verify that it can contact the server and if it is successful then the server will be added to the source-control server list on the administration page; and if it is not successful you will recieve an error dialog with the reason Compass failed to add the source-control server.

Create a Project

Now that we've added a user and soure-control server we need to create a project.  In the 'Project Administration' section.  Click on the 'Create New Project' button and give your new project a name.  This can be any name you like that describes what this project will be building and/or testing.  Click the 'Create' button and confirm your name and then the 'Project Administration' section looks like this:

The Project Administration page now has one row with our new project in it, and the next step is toadd our new user to the project so they have access to the project when they log in.  To do this, click on the 'User Permissions' button.  In this dialog you can add and remove users on each project.  You can let users be project admins or just regular users.  Project admins can schedule builds and help administer the project but do not have site-wide administrative privileges.  After adding our user to the project this dialog looks like this:

Now that our project is added and accessible by our users it's time to set up a build plan to build and test our source code.  To do this we click on the name of the project.  This takes us to the 'Project Admin Page'

Create a New Build Plan

On the Project Admin Page there is 5 sections as described here:

To create a new build click on 'Create Build'  This will ask you for the name you want to give this build plan and the output file or directory you want to save on the server each time this build plan is run.  Both of these can be changed later if need be.  Once you click 'Create' you are taken to the 'Build Plan Editor'. The 'Build Plan Editor' looks like this:

To create your build plan, we enter a list of scripts that will be run in order.  The scripts can do almost anything you want them to do.  In this start-up guide we only use scripts that come with Compass for checking out code, building and testing; to create new scripts see the Scripts Documentation page.  

To add our first script, a check-out script we click the add script button.  This adds a line to the build plan.  We give this step a name: 'My Check Out' and we select which script we want to run ' SVN Revision Checkout'.  Now the build plan looks like this:

We choose to use an SVN Revision checkout.  This will be executed by Compass any time the repository changes, but we also want this build plan to run every 2 hours.  For an SVN revision checkout script, Compass determines the server URL and revision number to check out when the build is triggered by the repository change.  But, if we also want the HEAD revision to be checked out every 2 hours we have to specify the server URL and revision to use.   We provide defaults values by clicking on the defaults button:

This brings up the defaults dialog.  The 'Defaults Dialog' provides a way to specify default values for arguments that are passed to each script.  In this case we have set up a 'revision checkout' script.    In the 'Defaults Dialog' we enter the default value for 'revision' as 'HEAD' and for 'server_url' as 'svn+ssh:// This e-mail address is being protected from spambots. You need JavaScript enabled to view it /path/ ./' as shown here:

We now have a build step  that will check out code for either a change to the repository or for a regularily scheduled build.  Now we add two more steps, one to build our executable and another to run a pyunit test suite.  After adding both of these steps our build plan looks like this:

For the 2nd build step that runs Visual Studio Build we need to edit the defaults to again to specify which project to in the solution to build.  This is exactly the same as for the svn revision checkout bu this time we specify the CONFIG_NAME as the parameter like this:

And finally, on the last build step we have to tell Compass to run a unit test parser.  We also only want to recieve a warning if this build step fails.  To make these changes we open the details dialog: 

Clicking this icon brings up the Details dialog and here we can set the unit test parser to use, and also tell Compass to only give us a warning if there is a failed test.  After making these changes the 'Details Dialog' looks like this:

 After setting the fail condition and the unit test parser and clicking 'OK' we are done setting up steps for our build plan.  We just have the build plan configuration steps remaining.  These appear after the build steps and control how the build saves data and what configurations to run the build on.  Since we are setting up a windows build, the only change we need to make is to uncheck linux from the build configurations list.  After doing that our build configuration looks like this:

Now we click 'Save Build' and our Build Plan is complete.  The next step is to schedule the build. 

Schedule the Build Plan

Just under the Build Plan Editor is the Schedule dialog.  To schedule this build plan click on the 'Schedule Build' button.  This will bring up the 'Schedule New Build' dialog.  This dialog has three tabs to schedule the build three different ways.  You can schedule a build to run immediately - this is useful for testing a new build plan or to test new changes in your repository or codebase.  The second way is to schedule a build to happen when a repository changes.  The third way is to schedule a build at a regular interval.  We will schedule our new build plan for both a repository change and a regular interval.  To schedule a build when a repository changes click the revision tab and select the source-control server to watch, you can optionally have Compass watch a specific path in the repository too, in this case we watch the whole repository:

Then click 'OK'; this schedules our first build.  Now click on 'Schedule New Build' again and this time open the 'Date/Time' tab.  We set the date and time we want the build to run for the first time and then select the radio button for a regular build every per min/hour/day and set it to 2 hours.  Highlighted below are the two things we just changed in the 'Schedule New Build' Dialog:

After setting these two fields we click 'OK' and now both builds are scheduled and the schedule table looks like this:

Add Email Notification

Finally, we add email notification so that team members get an email any time a build fails.  We do this in the email notification box on the project admin page.  Go back to the admin page by hitting back in the browser or by clickin on the project link at the top of the 'Build Plan Editor' page. On the admin page simply fill out the email notification box and presto, every time the build plan fails an email will be sent to the team:

Set Up a Build Client

Now that the Compass Server is all set up with a build plan, ready to start building; it needs a build client to execute the build plan.

The most common Compass configuration is to have a single build client on the same machine as the Compass Server.  To start a Compass Build Client navigate to the Compass directory on a machine you intned to use as a Compass Build Client and in a shell execute the following command:

>python start_server.py clientcfg.cfg &

This starts the Compass Build Client with the default parameters in the clientcfg.cfg file, details of the clientcfg.cfg file can be found in the administrator manual.  To test that the client is correctly started and connected, open a web browser and log in to the Compass web page.   Click on the Build Monitor icon on the top menu and you should see a build client called linux-1:

And now compass is completely set up and ready to go. Builds will start at their next scheduled time or with the next repository change. 

Many more advanced features of Compass are covered in other documentation pages on the Anx Labs partner site.  For questions and comments please contact: This e-mail address is being protected from spambots. You need JavaScript enabled to view it