Quality/QA-tools/OTS/UserDocumentation/Installation

Revision as of 14:22, 11 October 2010

Installation Instructions for OTS 0.1

These instructions have been tested with Ubuntu 10.04.

Network Setup

Using static IP addresses on all OTS machines is strongly recommended. It is possible to setup the system also with dynamic IP addresses but it might cause problems every now and then because IP's and hostnames change.

Server

prerequisites

• An smtp server is needed for OTS to be able to send result emails.
  • You can use the smtp server provided by your ISP or organization
  • Or you can setup your own. for example postfix

Basic Setup

• Download and install RabbitMQ server from http://www.rabbitmq.com/server.html

• Install dependencies from ubuntu repository:

sudo apt-get update
sudo apt-get install python-setuptools python-amqplib python-django

• Install rest of the dependencies with easy_install:

sudo easy_install minixsv

• Get source code from http://gitorious.com/qa-tools/ots/ (tag 0.1.0)

• Install ots.common:

cd ots/ots.common/
sudo python setup.py install

• Install ots.server:

cd ots/ots.server/
sudo python setup.py install

• Install ots.tools: (Required only for triggering testruns easily from command line over xmlrpc)

cd ots/ots.tools/
sudo python setup.py install

• Download and install test definition schema files from http://gitorious.com/qa-tools/test-definition

• Create a directory for testrun logs and make sure the user running ots.server has write permissions to it:

sudo mkdir /var/log/ots

• At this point it should be possible to trigger testruns from python shell if you have a worker already set up and configured to use this server. Here's an example ipython session:

In [1]: from ots.server.xmlrpc.public import request_sync

In [4]: program = "example_sw_product"

In [5]: request = "5"

In [6]: notify_list = ['tvainio@localhost']

In [7]: options = dict()

In [8]: options['image'] = "http://somewhere/some_image.bin"

In [9]: options['email'] = "off"

In [13]: options["device"] = "devicegroup:default"            # Make this match the worker 

In [14]: request_sync(program, request, notify_list, options)
Out[14]: 'FAIL'

The result will be PASS/FAIL/ERROR. ERROR means that something went wrong in server side and testrun was not even started. FAIL means failed testrun and PASS means that everything went fine and all tests passed. Testrun logs with more information about the possible errors are available in /var/log/ots/

Configuring the Server

The previous example was not very useful. To get OTS server running as a real server you have two options. A simple xmlrpc server or a more advanced django based server. First thing you need to do is setup a custom config file.

Custom Config File

Ots server tries to import a configuration module ots_extensions.ots_config. If it does not succeed it uses the default from ots.server.testrun_host.default_ots_config. You can set up your own ots_config by following these instructions:

• Create a directory for your extensions:

mkdir my_ots_extensions

• Add it to your python path

export PYTHONPATH=/full/path/to/my_ots_extensions/:$PYTHONPATH

• Create custom ots_extensions python package:

mkdir my_ots_extensions/ots_extensions
touch my_ots_extensions/ots_extensions/__init__.py

• Copy the default config file from ots/ots.server/ots/server/testrun_host/default_ots_config.py to my_ots_extensions/ots_extensions/ots_config.py

• Modify the file to suit your needs. Check at least the following settings:
  • Email settings (The smtp server OTS uses to send testrun results)
  • xmlrpc server config (if you are setting the simple xmlrpc server setup. More info below.)
  • The default options for your sw product:

You can define default values for all options here. The example_sw_product contains and example how to define options. You cannot use an sw_product if it does not contain the default options in ots_config. Here's a small example. I'm developing a Meego based coffeemaker and creating custom software images for it. To automate the testing I create an sw_product called "my_meego_variant": TODO: Document all options

#
# Defaults for my_meego_variant                             
#                                                                                                                                   

# Lets start with the global_defaults
default_options["my_meego_variant"] = global_defaults.copy()

# The images work only on meego coffeemakers so the default devicegroup will be "meego_coffeemaker"
default_options["my_meego_variant"]['device'] = {'devicegroup':'meego_coffeemaker'}

# Coffeemaker needs to be fast so we define a 3 minutes global timeout for the test execution.
default_options["my_meego_variant"]['timeout'] = 3

Extension Points

OTS uses plugins to do various things during the testrun. You can write your own plugins to add more functionality by implementing a module ots_extensions.extension_points. An example file can be found from ots/ots.server/ots/server/testrun_host/example_extension_points.py

Simple XMLRPC Server

• After you have implemented your custom config file and defined suitable xmlrpc_host and xmlrpc_port values you can start the simple xmlrpc server:

ots_server

• After that you can start testruns on your ots_server by calling the request_sync() method over xmlrpc just like we did locally in the example above. There's also a command line tool called ots_trigger in ots.tools package.

• A testrun can be triggered from command line with ots_trigger:

ots_trigger -s your_xmlrpc_host:your_xmlrpc_port -b 333 -i url_to_dummyimage -p my_meego_variant -e your_email_address

The result should be FAIL and if your email server settings are correct you should also receive an email.

• If we look into the new testrun log file in /var/log/ots/ we should find something like this:

2010-09-24 15:48:21,188  conductorengine ERROR    Device group 'meego_coffeemaker' does not exist
Traceback (most recent call last):
  File "/usr/local/lib/python2.6/dist-packages/ots.server-0.1dev-py2.6.egg/ots/server/conductorengine/conductorengine.py", line 150, in execute
    self._taskrunner.run()
  File "/usr/local/lib/python2.6/dist-packages/ots.server-0.1dev-py2.6.egg/ots/server/distributor/taskrunner.py", line 417, in run
    (self._routing_key))
OtsQueueDoesNotExistError: No queue for meego_coffeemaker

• Next step is to set up an OTS worker into the devicegroup meego_coffeemaker. Instructions can be found below.

Django Based Server

With Django and Apache it's possible to set up a more advanced ots server.

There's for example a global logger application available in ots.server.logger. By setting up the logger it is possible to get log messages for a specific testrun from all parts of the system (ots server, ots conductor and testrunner-lite). The logs are stored into DB and can be accessed with a web UI. It's also easy to implement a result db and web views for the test results.

TODO: Add instructions

Worker

• Install dependencies:

sudo apt-get update
sudo apt-get install python-setuptools python-amqplib

• Get source code from http://gitorious.com/qa-tools/ots/ (tag 0.1.0)

• Install ots.common:

cd ots/ots.common/
sudo python setup.py install

• Install ots.worker:

cd ots/ots.worker/
sudo python setup.py install

• Configure the worker by editing devicegroup and server address in /etc/ots.ini:

[Worker]

###########################################
# REPLACE `fix_me` WITH YOUR DEVICEGROUP
###########################################

queue = meego_coffeemaker                 # 
routing_key = meego_coffeemaker           # Change these 3 lines to the devicegroup this worker belongs to
services_exchange = meego_coffeemaker     # 

###############################
# ADVANCED CONFIGURATION
###############################

host = your_server_address                # Change this to your ots server address
vhost = / 
port = 5672
username = guest
password = guest
consumer_tag = worker
log_file = /var/log/ots.log

• Start the worker:

sudo ots_worker

• If everything went ok, you should see something like this:

010-09-24 11:00:41,373 - amqplib - DEBUG - Open OK! known_hosts [starshollow:5672]
2010-09-24 11:00:41,374 - amqplib - DEBUG - using channel_id: 1
2010-09-24 11:00:41,374 - amqplib - DEBUG - Channel open
2010-09-24 11:00:41,375 - ots.worker.worker - DEBUG - Starting the server. {vhost:'/', queue:'meego_coffeemaker', routing_key:'meego_coffeemaker'}
2010-09-24 11:00:41,377 - ots.worker.task_broker - DEBUG - Starting main loop...

• There's also an init script available in ots.worker/debian/python-ots-worker.ots-worker.init to make running the worker easier

• After that the worker should be ready for receiving tasks. To make sure the actual test execution works please see the instructions for ots.worker.conductor: Conductor