.. _usage:

=====
Usage
=====

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

.. code-block:: python

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

Press :kbd:`Ctrl-C` (or :kbd:`Ctrl-Break` on Windows) to exit the server.

The following will run waitress on port 8080 on all available IPv4 addresses, but not IPv6.

.. code-block:: python

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

By default Waitress binds to any IPv4 address 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)

If you want to serve your application through a UNIX domain socket (to serve a downstream HTTP server/proxy such as nginx, lighttpd, and so on), 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:`access-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 analogous:

.. 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

Heroku
------

Waitress can be used to serve WSGI apps on Heroku, include waitress in your requirements.txt file a update the Procfile as following:

.. code-block:: bash

   web: waitress-serve \
       --listen "*:$PORT" \
       --trusted-proxy '*' \
       --trusted-proxy-headers 'x-forwarded-for x-forwarded-proto x-forwarded-port' \
       --log-untrusted-proxy-headers \
       --clear-untrusted-proxy-headers \
       --threads ${WEB_CONCURRENCY:-4} \
       myapp:wsgifunc

The proxy config informs Waitress to trust the `forwarding headers <https://devcenter.heroku.com/articles/http-routing#heroku-headers>`_ set by the Heroku load balancer.
It also allows for setting the standard ``WEB_CONCURRENCY`` environment variable to tweak the number of requests handled by Waitress at a time.

Note that Waitress uses a thread-based model and careful effort should be taken to ensure that requests do not take longer than 30 seconds or Heroku will inform the client that the request failed even though the request is still being processed by Waitress and occupying a thread until it completes.

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