.. -*- restructuredtext -*-

pasteuwsgi
===========

*pasteuwsgi* is a simple python paste (http://pythonpaste.org/) plugin
which adds a command that serve the application for using uWSGI
(http://projects.unbit.it/uwsgi/) integrated HTTP server. It can monitor python
files and automatically reload uWSGI on file change. It's focused for local
development to easily test uWSGI specific features.

install
=======

First, to use *pasteuwsgi* you need uWSGI installed, both sistem wide or
in the virtualenv. Check the uWSGI documentation on how to install uWSGI
(http://projects.unbit.it/uwsgi/wiki/Install). The simplest way is to install
uwsgi in the virtualenv, using pip::

 # pip install uwsgi

Then, you can install *pasteuwsgi* via pypi::

 # pip install pasteuwsgi

Or, if you want the last unstable version, directly from bitbucket (again, using pip)::
  
  # pip install -e hg+https://bitbucket.org/gbagnoli/pasteuwsgi#egg=pasteuwsgi

Or you can clone the hg repo and then install::

  # hg clone https://gbagnoli@bitbucket.org/gbagnoli/pasteuwsgi
  # pip install -e ./

usage
=====

Once installed, simply add this line to setup.py of your paste app::

  uwsgi = pasteuwsgi.serve:ServeCommand

in the "[paste.paster_command]" section of the entry_point
argument.

i.e. for a pylons-1.0 application::

   entry_points="""
   [paste.app_factory]
   main = aybu.cms.config.middleware:make_app

   [paste.app_install]
   main = pylons.util:PylonsInstaller

   [paste.paster_command]
   uwsgi = pasteuwsgi.serve:ServeCommand
   """,

You may need to re-run setuptools egg_info after adding the new entry_point::
  
  # cd my-project
  # python setup.py egg_info

options
=======

--address
  Override the http server listening address.
--port
  Override the http server listening port.
--reload
  Setup a monitor (using pyinotify) to watch application code to reload on changes. It also monitors code installed in the virtualenv.
--uwsgi
  Pass additional options to uWSGI directly. Remember that you neeed to wrap uWSGI options with quotes.
--plugins
  Load uWSGI plugins (for uWSGI >= 0.9.7)


examples
========

To simply run it as you did with paster serve::

  paster uwsgi development.ini --reload

You can add uwsgi options using the -w switch ::

  # run with 2 workers with two threads each
  paster uwsgi development.ini --reload -w "-workers 2 --threads 2"

You can even add common options (such the threads or the process one, or
others) to a [uwsgi] section inside the paste ini (development.ini in the above
example)::
  
  [...]
  [uwsgi]
  threads = 2
  workers = 2

This works as *pasteuwsgi* passes --ini option to uwsgi with the same ini it
uses.
