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.