path: root/docs/index.rst

Waitress
--------

Waitress is meant to be a production-quality pure-Python WSGI server with
very acceptable performance.  It has no dependencies except ones which live
in the Python standard library.  It runs on CPython on Unix and Windows under
Python 2.6+ and Python 3.2+.  It is also known to run on PyPy 1.6.0 on UNIX.
It supports HTTP/1.0 and HTTP/1.1.

Usage
-----

Here's normal usage of the server:

.. code-block:: python

   from waitress import serve
   serve(wsgiapp, listen='*:8080')

This will run waitress on port 8080 on all available IP addresses, both IPv4
and IPv6.


.. code-block:: python

   from waitress impot serve
   serve(wsgiapp, host='0.0.0.0', port=8080)

This will run waitress on port 8080 on all available IPv4 addresses.

If you want to serve your application on all IP addresses, on port 8080, you
can omit the ``host`` and ``port`` arguments and just call ``serve`` with the
WSGI app as a single argument:

.. code-block:: python

   from waitress import serve
   serve(wsgiapp)
   
Press Ctrl-C (or Ctrl-Break on Windows) to exit the server.

The default is to bind to any IPv4 address on port 8080:

.. code-block:: python

   from waitress import serve
   serve(wsgiapp)

If you want to serve your application through a UNIX domain socket (to serve
a downstream HTTP server/proxy, e.g. nginx, lighttpd, etc.), call ``serve``
with the ``unix_socket`` argument:

.. code-block:: python

   from waitress import serve
   serve(wsgiapp, unix_socket='/path/to/unix.sock')

Needless to say, this configuration won't work on Windows.

Exceptions generated by your application will be shown on the console by
default.  See :ref:`logging` to change this.

There's an entry point for :term:`PasteDeploy` (``egg:waitress#main``) that
lets you use Waitress's WSGI gateway from a configuration file, e.g.:

.. code-block:: ini

  [server:main]
  use = egg:waitress#main
  listen = 127.0.0.1:8080

Using ``host`` and ``port`` is also supported:

.. code-block:: ini

  [server:main]
  host = 127.0.0.1
  port = 8080

The :term:`PasteDeploy` syntax for UNIX domain sockets is analagous:

.. code-block:: ini

  [server:main]
  use = egg:waitress#main
  unix_socket = /path/to/unix.sock

You can find more settings to tweak (arguments to ``waitress.serve`` or
equivalent settings in PasteDeploy) in :ref:`arguments`.

Additionally, there is a command line runner called ``waitress-serve``, which
can be used in development and in situations where the likes of
:term:`PasteDeploy` is not necessary:

.. code-block:: bash

   # Listen on both IPv4 and IPv6 on port 8041
   waitress-serve --listen=*:8041 myapp:wsgifunc

   # Listen on only IPv4 on port 8041
   waitress-serve --port=8041 myapp:wsgifunc

For more information on this, see :ref:`runner`.

.. _logging:

Logging
-------

``waitress.serve`` calls ``logging.basicConfig()`` to set up logging to the
console when the server starts up.  Assuming no other logging configuration
has already been done, this sets the logging default level to
``logging.WARNING``.  The Waitress logger will inherit the root logger's
level information (it logs at level ``WARNING`` or above).

Waitress sends its logging output (including application exception
renderings) to the Python logger object named ``waitress``.  You can
influence the logger level and output stream using the normal Python
``logging`` module API.  For example:

.. code-block:: python

   import logging
   logger = logging.getLogger('waitress')
   logger.setLevel(logging.INFO)

Within a PasteDeploy configuration file, you can use the normal Python
``logging`` module ``.ini`` file format to change similar Waitress logging
options.  For example:

.. code-block:: ini

   [logger_waitress]
   level = INFO

Using Behind a Reverse Proxy
----------------------------

Often people will set up "pure Python" web servers behind reverse proxies,
especially if they need SSL support (Waitress does not natively support SSL).
Even if you don't need SSL support, it's not uncommon to see Waitress and
other pure-Python web servers set up to "live" behind a reverse proxy; these
proxies often have lots of useful deployment knobs.

If you're using Waitress behind a reverse proxy, you'll almost always want
your reverse proxy to pass along the ``Host`` header sent by the client to
Waitress, in either case, as it will be used by most applications to generate
correct URLs.

For example, when using Nginx as a reverse proxy, you might add the following
lines in a ``location`` section::

    proxy_set_header        Host $host;

The Apache directive named ``ProxyPreserveHost`` does something similar when
used as a reverse proxy.

Unfortunately, even if you pass the ``Host`` header, the Host header does not
contain enough information to regenerate the original URL sent by the client.
For example, if your reverse proxy accepts HTTPS requests (and therefore URLs
which start with ``https://``), the URLs generated by your application when
used behind a reverse proxy served by Waitress might inappropriately be
``http://foo`` rather than ``https://foo``.  To fix this, you'll want to
change the ``wsgi.url_scheme`` in the WSGI environment before it reaches your
application.  You can do this in one of three ways:

1.  You can pass a ``url_scheme`` configuration variable to the
    ``waitress.serve`` function.

2.  You can configure the proxy reverse server to pass a header,
    ``X_FORWARDED_PROTO``, whose value will be set for that request as
    the ``wsgi.url_scheme`` environment value.  Note that you must also
    conigure ``waitress.serve`` by passing the IP address of that proxy
    as its ``trusted_proxy``.

3.  You can use Paste's ``PrefixMiddleware`` in conjunction with
    configuration settings on the reverse proxy server.

Using ``url_scheme`` to set ``wsgi.url_scheme``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can have the Waitress server use the ``https`` url scheme by default.:

.. code-block:: python

   from waitress import serve
   serve(wsgiapp, listen='0.0.0.0:8080', url_scheme='https')

This works if all URLs generated by your application should use the ``https``
scheme.

Passing the ``X_FORWARDED_PROTO`` header to set ``wsgi.url_scheme``
-------------------------------------------------------------------

If your proxy accepts both HTTP and HTTPS URLs, and you want your application
to generate the appropriate url based on the incoming scheme, also set up
your proxy to send a ``X-Forwarded-Proto`` with the original URL scheme along
with each proxied request.  For example, when using Nginx::

    proxy_set_header        X-Forwarded-Proto $scheme;

or via Apache::

   RequestHeader set X-Forwarded-Proto https

.. note::

   You must also configure the Waitress server's ``trusted_proxy`` to
   contain the IP address of the proxy in order for this header to override
   the default URL scheme.

Using ``url_prefix`` to influence ``SCRIPT_NAME`` and ``PATH_INFO``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can have the Waitress server use a particular url prefix by default for all
URLs generated by downstream applications that take ``SCRIPT_NAME`` into
account.:

.. code-block:: python

   from waitress import serve
   serve(wsgiapp, listen='0.0.0.0:8080', url_prefix='/foo')

Setting this to any value except the empty string will cause the WSGI
``SCRIPT_NAME`` value to be that value, minus any trailing slashes you add, and
it will cause the ``PATH_INFO`` of any request which is prefixed with this
value to be stripped of the prefix.  This is useful in proxying scenarios where
you wish to forward all traffic to a Waitress server but need URLs generated by
downstream applications to be prefixed with a particular path segment.

Using Paste's ``PrefixMiddleware`` to set ``wsgi.url_scheme``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If only some of the URLs generated by your application should use the
``https`` scheme (and some should use ``http``), you'll need to use Paste's
``PrefixMiddleware`` as well as change some configuration settings on your
proxy.  To use ``PrefixMiddleware``, wrap your application before serving it
using Waitress:

.. code-block:: python

  from waitress import serve
  from paste.deploy.config import PrefixMiddleware
  app = PrefixMiddleware(app)
  serve(app)

Once you wrap your application in the the ``PrefixMiddleware``, the
middleware will notice certain headers sent from your proxy and will change
the ``wsgi.url_scheme`` and possibly other WSGI environment variables
appropriately.

Once your application is wrapped by the prefix middleware, you should
instruct your proxy server to send along the original ``Host`` header from
the client to your Waitress server, as well as sending along a
``X-Forwarded-Proto`` header with the appropriate value for
``wsgi.url_scheme``.

If your proxy accepts both HTTP and HTTPS URLs, and you want your application
to generate the appropriate url based on the incoming scheme, also set up
your proxy to send a ``X-Forwarded-Proto`` with the original URL scheme along
with each proxied request.  For example, when using Nginx::

    proxy_set_header        X-Forwarded-Proto $scheme;

It's permitted to set an ``X-Forwarded-For`` header too; the
``PrefixMiddleware`` uses this to adjust other environment variables (you'll
have to read its docs to find out which ones, I don't know what they are).  For
the ``X-Forwarded-For`` header::

    proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;

Note that you can wrap your application in the PrefixMiddleware declaratively
in a :term:`PasteDeploy` configuration file too, if your web framework uses
PasteDeploy-style configuration:

.. code-block:: ini

   [app:myapp]
   use = egg:mypackage#myapp

   [filter:paste_prefix]
   use = egg:PasteDeploy#prefix

   [pipeline:main]
   pipeline =
       paste_prefix
       myapp

   [server:main]
   use = egg:waitress#main
   listen = 127.0.0.1:8080

Note that you can also set ``PATH_INFO`` and ``SCRIPT_NAME`` using
PrefixMiddleware too (its original purpose, really) instead of using Waitress'
``url_prefix`` adjustment.  See the PasteDeploy docs for more information.

Extended Documentation
----------------------

.. toctree::
   :maxdepth: 1

   design.rst
   differences.rst
   api.rst
   arguments.rst
   filewrapper.rst
   runner.rst
   glossary.rst

Change History
--------------

.. include:: ../CHANGES.txt
.. include:: ../HISTORY.txt

Known Issues
------------

- Does not support SSL natively.

Support and Development
-----------------------

The `Pylons Project web site <http://pylonsproject.org/>`_ is the main online
source of Waitress support and development information.

To report bugs, use the `issue tracker
<http://github.com/Pylons/waitress/issues>`_.

If you've got questions that aren't answered by this documentation,
contact the `Pylons-devel maillist
<http://groups.google.com/group/pylons-devel>`_ or join the `#pyramid
IRC channel <irc://irc.freenode.net/#pyramid>`_.

Browse and check out tagged and trunk versions of Waitress via
the `Waitress GitHub repository <http://github.com/Pylons/waitress/>`_.
To check out the trunk via ``git``, use this command:

.. code-block:: text

  git clone git@github.com:Pylons/waitress.git

To find out how to become a contributor to Waitress, please see the
`contributor's section of the documentation
<http://docs.pylonsproject.org/index.html#contributing>`_.

Why?
----

At the time of the release of Waitress, there are already many pure-Python
WSGI servers.  Why would we need another?

Waitress is meant to be useful to web framework authors who require broad
platform support.  It's neither the fastest nor the fanciest WSGI server
available but using it helps eliminate the N-by-M documentation burden
(e.g. production vs. deployment, Windows vs. Unix, Python 3 vs. Python 2,
PyPy vs. CPython) and resulting user confusion imposed by spotty platform
support of the current (2012-ish) crop of WSGI servers.  For example,
``gunicorn`` is great, but doesn't run on Windows.  ``paste.httpserver`` is
perfectly serviceable, but doesn't run under Python 3 and has no dedicated
tests suite that would allow someone who did a Python 3 port to know it
worked after a port was completed.  ``wsgiref`` works fine under most any
Python, but it's a little slow and it's not recommended for production use as
it's single-threaded and has not been audited for security issues.

At the time of this writing, some existing WSGI servers already claim wide
platform support and have serviceable test suites.  The CherryPy WSGI server,
for example, targets Python 2 and Python 3 and it can run on UNIX or Windows.
However, it is not distributed separately from its eponymous web framework,
and requiring a non-CherryPy web framework to depend on the CherryPy web
framework distribution simply for its server component is awkward.  The test
suite of the CherryPy server also depends on the CherryPy web framework, so
even if we forked its server component into a separate distribution, we would
have still needed to backfill for all of its tests.  The CherryPy team has
started work on `Cheroot <https://bitbucket.org/cherrypy/cheroot>`_, which
should solve this problem, however.

Waitress is a fork of the WSGI-related components which existed in
``zope.server``.  ``zope.server`` had passable framework-independent test
coverage out of the box, and a good bit more coverage was added during the
fork.  ``zope.server`` has existed in one form or another since about 2001,
and has seen production usage since then, so Waitress is not exactly
"another" server, it's more a repackaging of an old one that was already
known to work fairly well.