# Running TurboGears under `Circus` and `Chaussette`

`Circus` is a process & socket manager. It can be used to monitor and control processes and sockets, when paired with the `Chaussette` WSGI server it can became a powerful tool to deploy your application and manage any related process your applications needs.

Circus can take care of starting your memcached, redis, database server or batch process with your application itself providing a single point where to configure the full application environment.

This guide will outline broad steps that can be used to get a TurboGears application running under `Chaussette` through `Circus`.

1. The tutorial assumes you have `Circus` already installed on your system. If you do not, install it in whatever manner makes sense for your environment.

   A possible way is by performing:

       $ pip install circus

2. Create a virtual environment with the specific TurboGears version your application depends on installed.

       $ virtualenv /var/tg2env
       $ /var/tg2env/bin/pip install  tg.devtools

3. Activate the virtual environment

       $ source /var/tg2env/bin/activate
       (tg2env)$ #virtualenv now activated

4. Once you have the environment enabled you will need to install the `Chaussette` WSGI Server:

       (tg2env)$ pip install chaussette

5. Chaussette supports many backends to serve the requests. The default one is based on `wsgiref`, which is not really fast. Have a look at the Chaussette Documentation for the available backends: `waitress`, `gevent`, `meinheld` and many more are supported.

   For this tutorial we are going to use `Waitress`, which is a multithreaded WSGI server, so we need to install it inside virtual environment:

       (tg2env)$ pip install waitress

6. Now the environment is ready for deploy, you just need to install the TurboGears application.

       (tg2env)$ cd /var/www/myapp
       (tg2env)$ python setup.py develop

7. We now create a circus configuration file (named `circus.ini`) with the informations required to load and start your application. This can be performed using the `gearbox deploy-circus` command from gearbox-tools package or by manually writing it:

       [circus]
       check_delay = 5
       endpoint = tcp://127.0.0.1:5555
       debug = true

       [env:myapp]
       PATH=/var/tg2env/bin:$PATH
       VIRTUAL_ENV=/var/tg2env

       [watcher:myapp]
       working_dir = /var/www/myapp
       cmd = chaussette --backend waitress --fd $(circus.sockets.myapp) paste:production.ini
       use_sockets = True
       warmup_delay = 0
       numprocesses = 1

       stderr_stream.class = FileStream
       stderr_stream.filename = /var/log/circus/myapp.log
       stderr_stream.refresh_time = 0.3

       stdout_stream.class = FileStream
       stdout_stream.filename = /var/log/circus/myapp.log
       stdout_stream.refresh_time = 0.3

       [socket:myapp]
       host = localhost
       port = 8080

8. Now start circus with the configuration file, after being started it will load your application:

       $ circusd circus.ini

       2013-02-15 18:19:54 [20923] [INFO] Starting master on pid 20923
       2013-02-15 18:19:54 [20923] [INFO] sockets started
       2013-02-15 18:19:54 [20923] [INFO] myapp started
       2013-02-15 18:19:54 [20923] [INFO] Arbiter now waiting for commands

9. Visit `http://localhost:8080/` in a browser to access the application. You can now proxy it behind Apache, Nginx or any other web server or even use the VHostino project for circus to serve multiple applications through virtual hosts

See the circus documentation for more in-depth configuration information.