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