Prerequisites
=============

The following instructions assume that you are using a Debian or Ubuntu
Linux system and have the packages `virtualenvwrapper` and `rabbitmq`
installed.

::

	$ apt-get install python-dev virtualenvwrapper rabbitmq

RabbitMQ_ is only required if you want to run the the unit tests or you
are planning to use the inter process communication using message queues
in your own applications. virtualenvwrapper_ is optional, too. You can
also use virtualenv_ directly or make sure that the required python
modules are in your `PYTHONPATH` environment variable.

.. _RabbitMQ: http://www.rabbitmq.com/
.. _virtualenvwrapper: https://pypi.python.org/pypi/virtualenvwrapper
.. _virtualenv: https://pypi.python.org/pypi/virtualenv

Create virtualenv and install requirements
------------------------------------------

::

	$ mkvirtualenv --no-site-packages mushroom
	$ pip install -r test-requirements.txt

.. note::

	Running `setup.py test` without a virtualenv does not work as the
	selenium tests need to start a second python tasks with the same
	environment. This task will not be able to find the packages which
	are installed in the project dir by `setup.py test`.


Running the examples
====================

::

	$ workon mushroom
	$ cd examples
	$ ./chat-server.py

All examples start a server at port `39288`. This port was choosen
by `random.randint(1024, 65535)`. Once the server is up and
running open a browser and open up the URL http://127.0.0.1:39288/.

For more information about the included examples see :ref:`examples`.


Running the unit tests
======================

Prerequisites
-------------

Mushroom is compatible with gevent 0.x but the selenium test case does
require `gevent.subprocess` which is only part of gevent 1.x. If you
plan to run the mushroom unit tests you should use gevent 1.x.

At the time this document was written gevent 1.x was not released and
can only be obtained from the Git repository: https://github.com/surfly/gevent

Configure RabbitMQ
------------------

In order to run the test suite you need RabbitMQ installed with a
vhost `/mushroom` and a user with bosh `mushroom` as username and
password with full access to the `/mushroom` vhost.

Use the following commands to create the vhost, user and permissions:

::

	$ rabbitmqctl add_vhost /mushroom
	$ rabbitmqctl add_user mushroom mushroom
	$ rabbitmqctl set_permissions -p /mushroom mushroom ".*" ".*" ".*"


Running the tests
-----------------

::

	$ workon mushroom
	$ python setup.py test
