1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
|
.. _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 and 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`.
|
