### Start Waitress with Pre-bound Sockets

Source: https://github.com/pylons/waitress/blob/main/docs/socket-activation.md

This example demonstrates how to start Waitress with two pre-bound Internet sockets. Ensure sockets are bound before passing them to Waitress.

```python
import socket
import waitress


def app(environ, start_response):
    content_length = environ.get('CONTENT_LENGTH', None)
    if content_length is not None:
        content_length = int(content_length)
    body = environ['wsgi.input'].read(content_length)
    content_length = str(len(body))
    start_response(
        '200 OK',
        [('Content-Length', content_length), ('Content-Type', 'text/plain')]
    )
    return [body]


if __name__ == '__main__':
    sockets = [
        socket.socket(socket.AF_INET, socket.SOCK_STREAM),
        socket.socket(socket.AF_INET, socket.SOCK_STREAM)]
    sockets[0].bind(('127.0.0.1', 8080))
    sockets[1].bind(('127.0.0.1', 9090))
    waitress.serve(app, sockets=sockets)
    for socket in sockets:
        socket.close()
```

--------------------------------

### serve

Source: https://github.com/pylons/waitress/blob/main/docs/api.md

Starts the Waitress WSGI server to serve the given application.

```APIDOC
## serve(app, listen='0.0.0.0:8080', unix_socket=None, unix_socket_perms='600', threads=4, url_scheme='http', url_prefix='', ident='waitress', backlog=1024, recv_bytes=8192, send_bytes=1, outbuf_overflow=1048576, outbuf_high_watermark=16777216, inbuf_overflow=52488, connection_limit=1000, cleanup_interval=30, channel_timeout=120, log_socket_errors=True, max_request_header_size=262144, max_request_body_size=1073741824, expose_tracebacks=False)

### Description
Starts the Waitress WSGI server to serve the given application.

### Parameters
- **app**: The WSGI application to serve.
- **listen**: The address and port to listen on (e.g., '0.0.0.0:8080'). Defaults to '0.0.0.0:8080'.
- **unix_socket**: Path to a Unix domain socket to listen on instead of a TCP socket.
- **unix_socket_perms**: Permissions for the Unix domain socket file.
- **threads**: The number of worker threads to use.
- **url_scheme**: The scheme to use for URLs generated by the application.
- **url_prefix**: A prefix to prepend to all URLs.
- **ident**: An identifier for the server.
- **backlog**: The maximum number of queued connections.
- **recv_bytes**: The size of the receive buffer in bytes.
- **send_bytes**: The size of the send buffer in bytes.
- **outbuf_overflow**: The maximum size of the output buffer before it overflows.
- **outbuf_high_watermark**: The high watermark for the output buffer size.
- **inbuf_overflow**: The maximum size of the input buffer before it overflows.
- **connection_limit**: The maximum number of concurrent connections.
- **cleanup_interval**: The interval in seconds for cleaning up idle connections.
- **channel_timeout**: The timeout in seconds for channel operations.
- **log_socket_errors**: Whether to log socket errors.
- **max_request_header_size**: The maximum size of the request header in bytes.
- **max_request_body_size**: The maximum size of the request body in bytes.
- **expose_tracebacks**: Whether to expose tracebacks in responses.

See [Arguments to waitress.serve](arguments.md#arguments) for more information.
```

--------------------------------

### Build and Upload Release to PyPI

Source: https://github.com/pylons/waitress/blob/main/RELEASING.txt

Create source and wheel distributions and upload them to PyPI. Requires 'setuptools-git', 'twine', and 'wheel' to be installed.

```bash
python setup.py sdist bdist_wheel
twine upload dist/waitress-X.X-*
```

--------------------------------

### Python Function Call to waitress.serve

Source: https://github.com/pylons/waitress/blob/main/docs/runner.md

This demonstrates the equivalent Python function call for starting the Waitress server.

```python
import myapp

waitress.serve(myapp.wsgifunc, port=8041, url_scheme='https')
```

--------------------------------

### Install Waitress via PyPI

Source: https://github.com/pylons/waitress/blob/main/RELEASING.txt

Install a specific version of Waitress from PyPI using pip. Useful for testing or deploying a particular release.

```bash
pip install waitress==1.X
```

--------------------------------

### Example TransLogger Output

Source: https://github.com/pylons/waitress/blob/main/docs/logging.md

This is an example of the log output generated by TransLogger when a page is requested.

```text
00:50:53,694 INFO [wsgiapp] Returning: Hello World!
                  (content-type: text/plain)
00:50:53,695 INFO [wsgi] 192.168.1.111 - - [11/Aug/2011:20:09:33 -0700] "GET /hello
HTTP/1.1" 404 - "-"
"Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.6) Gecko/20070725
Firefox/2.0.0.6"

```

--------------------------------

### Waitress Serve with --call Flag for Factory Methods

Source: https://github.com/pylons/waitress/blob/main/docs/runner.md

This example illustrates using the --call flag with waitress-serve to invoke a factory method that returns a WSGI application.

```bash
waitress-serve --call myapp.mymodule.app.wsgi_factory
```

--------------------------------

### Serve Image using wsgi.file_wrapper

Source: https://github.com/pylons/waitress/blob/main/docs/filewrapper.md

This example demonstrates how to use `environ['wsgi.file_wrapper']` to serve a JPEG image. The file-like object must support `read()` with a size hint and return bytes. It should also ideally support `seek()`, `tell()`, and `close()`.

```python
import os

here = os.path.dirname(os.path.abspath(__file__))

def myapp(environ, start_response):
    f = open(os.path.join(here, 'myphoto.jpg'), 'rb')
    headers = [('Content-Type', 'image/jpeg')]
    start_response(
        '200 OK',
        headers
        )
    return environ['wsgi.file_wrapper'](f, 32768)
```

--------------------------------

### Serve WSGI App with Default Settings

Source: https://github.com/pylons/waitress/blob/main/docs/usage.md

Run Waitress using default settings, which typically binds to any IPv4 address on port 8080. This is a concise way to start the server.

```python
from waitress import serve
serve(wsgiapp)
```

--------------------------------

### Waitress Serve Boolean Flag Example

Source: https://github.com/pylons/waitress/blob/main/docs/runner.md

Demonstrates how to use a boolean flag like --expose-tracebacks on the command line, which is equivalent to passing expose_tracebacks=True to waitress.serve.

```bash
--expose-tracebacks
```

--------------------------------

### Check PyPI Long Description Rendering

Source: https://github.com/pylons/waitress/blob/main/RELEASING.txt

Verify that the long description for PyPI renders correctly. Requires 'readme_renderer' to be installed.

```python
python setup.py check -r -s -m
```

--------------------------------

### PasteDeploy Configuration (Host and Port)

Source: https://github.com/pylons/waitress/blob/main/docs/usage.md

Configure Waitress using PasteDeploy's INI format to listen on a specific host and port. This is a common setup for development and deployment.

```ini
[server:main]
use = egg:waitress#main
host = 127.0.0.1
port = 8080
```

--------------------------------

### Waitress Serve Negative Boolean Flag Example

Source: https://github.com/pylons/waitress/blob/main/docs/runner.md

Shows how to disable a boolean flag using the --no- prefix, equivalent to passing False for the corresponding argument to waitress.serve.

```bash
--no-expose-tracebacks
```

--------------------------------

### Build Documentation

Source: https://github.com/pylons/waitress/blob/main/contributing.md

Build the project documentation using make and sphinx-build. The SPHINXBUILD variable should point to your virtual environment's sphinx-build executable.

```bash
# Mac and Linux
$ make clean html SPHINXBUILD=$VENV/bin/sphinx-build

# Windows
c:\> make clean html SPHINXBUILD=%VENV%\bin\sphinx-build
```

--------------------------------

### Command Line Runner (IPv4 and IPv6)

Source: https://github.com/pylons/waitress/blob/main/docs/usage.md

Use the `waitress-serve` command-line tool to run a WSGI application, listening on all IPv4 and IPv6 interfaces on a specified port.

```bash
waitress-serve --listen=*:8041 myapp:wsgifunc
```

--------------------------------

### Listen on Multiple Sockets with Waitress

Source: https://github.com/pylons/waitress/blob/main/HISTORY.txt

Demonstrates how to configure Waitress to listen on multiple IP addresses and ports, including IPv4 and IPv6, by providing a space-delineated string of listen addresses.

```python
from waitress import serve
serve(wsgiapp, listen='0.0.0.0:8080 [::]:9090 *:6543')
```

--------------------------------

### Waitress Serve with --app Argument

Source: https://github.com/pylons/waitress/blob/main/docs/runner.md

An alternative command-line syntax for specifying the application using the --app argument.

```bash
waitress-serve --port=8041 --url-scheme=https --app=myapp:wsgifunc
```

--------------------------------

### Listen on Multiple Host:Port Combinations

Source: https://github.com/pylons/waitress/blob/main/docs/arguments.md

Use the 'listen' argument to specify multiple host:port combinations for the server to bind to. Wildcards can be used for hostnames.

```python
listen="127.0.0.1:8080 [::1]:8080"
```

```python
listen="*:8080 *:6543"
```

--------------------------------

### Command Line Runner (IPv4 Only)

Source: https://github.com/pylons/waitress/blob/main/docs/usage.md

Use the `waitress-serve` command-line tool to run a WSGI application, listening only on IPv4 interfaces on a specified port.

```bash
waitress-serve --port=8041 myapp:wsgifunc
```

--------------------------------

### Build Docs with Tox

Source: https://github.com/pylons/waitress/blob/main/contributing.md

Build only the documentation using a specific tox environment. This is faster than running all tests if only docs need to be updated.

```bash
$ tox -e docs
```

--------------------------------

### Serve WSGI App on All IPs

Source: https://github.com/pylons/waitress/blob/main/docs/usage.md

Run Waitress on port 8080, listening on all available IPv4 and IPv6 addresses. Press Ctrl-C to exit.

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

--------------------------------

### Run All Tox Tests

Source: https://github.com/pylons/waitress/blob/main/contributing.md

Execute all test environments and configurations defined in the tox.ini file. This is the standard way to run tests.

```bash
$ tox
```

--------------------------------

### Configure File Handler for TransLogger

Source: https://github.com/pylons/waitress/blob/main/docs/logging.md

Set up a FileHandler named 'accesslog' to direct TransLogger output to 'access.log'. Ensure the 'wsgi' logger uses this handler and propagation is disabled.

```ini
# Begin logging configuration

[loggers]
keys = root, wsgiapp, wsgi

[handlers]
keys = console, accesslog

[logger_wsgi]
level = INFO
handlers = accesslog
qualname = wsgi
propagate = 0

[handler_accesslog]
class = FileHandler
args = ('%(here)s/access.log','a')
level = INFO
formatter = generic

```

--------------------------------

### Commit and Push Changes

Source: https://github.com/pylons/waitress/blob/main/contributing.md

Commit your changes with a descriptive message and push them to your origin repository. The first push might require additional flags.

```bash
git commit -m "commit message"
git push -u origin --all # first time only, subsequent can be just 'git push'.
```

--------------------------------

### PasteDeploy Configuration (Listen Address)

Source: https://github.com/pylons/waitress/blob/main/docs/usage.md

Configure Waitress using PasteDeploy's INI format with the 'listen' directive, which combines host and port. This is a shorthand for specifying both host and port.

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

--------------------------------

### Run Platform Tests with Tox

Source: https://github.com/pylons/waitress/blob/main/RELEASING.txt

Execute platform tests using tox. This command ensures statement coverage is at 100%, failing if it is not.

```bash
tox -r
```

--------------------------------

### Configure Apache Proxy Headers

Source: https://github.com/pylons/waitress/blob/main/docs/reverse-proxy.md

Ensure Apache forwards necessary X-Forwarded-* headers and explicitly set X-Forwarded-Proto. This allows Waitress to correctly interpret the original request scheme.

```apache
RequestHeader set X-Forwarded-Proto https
```

--------------------------------

### Waitress Serve Command-Line Equivalent

Source: https://github.com/pylons/waitress/blob/main/docs/runner.md

This shows the command-line usage of waitress-serve that mirrors the Python function call.

```bash
waitress-serve --port=8041 --url-scheme=https myapp:wsgifunc
```

--------------------------------

### Clone the Waitress Repository

Source: https://github.com/pylons/waitress/blob/main/contributing.md

Clone your forked repository to your local machine. Replace `<username>` with your GitHub username.

```bash
cd ~/projects
git clone git@github.com:<username>/waitress.git
```

--------------------------------

### PasteDeploy Configuration (Socket)

Source: https://github.com/pylons/waitress/blob/main/docs/usage.md

Configure Waitress using PasteDeploy's INI format to serve via a UNIX domain socket. This is an alternative to direct Python calls for configuration.

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

--------------------------------

### Waitress Serve Command Usage

Source: https://github.com/pylons/waitress/blob/main/docs/runner.md

Basic syntax for invoking the waitress-serve command. Specify options and the WSGI application module:object.

```bash
waitress-serve [OPTS] [MODULE:OBJECT]
```

--------------------------------

### Configure Waitress Trusted Proxy Headers

Source: https://github.com/pylons/waitress/blob/main/docs/reverse-proxy.md

Instruct Waitress to trust and use specific X-Forwarded-* headers to reconstruct the WSGI environment. This ensures correct values for HTTP_HOST, SERVER_NAME, wsgi.url_scheme, etc.

```text
trusted_proxy_headers = "x-forwarded-for x-forwarded-host x-forwarded-proto x-forwarded-port"
```

--------------------------------

### Heroku Deployment Configuration

Source: https://github.com/pylons/waitress/blob/main/docs/usage.md

Configure Waitress for deployment on Heroku using `waitress-serve`. This includes trusting Heroku's forwarding headers and setting the number of threads.

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

--------------------------------

### Configure TransLogger via .ini File

Source: https://github.com/pylons/waitress/blob/main/docs/logging.md

Use PasteDeploy's .ini file syntax to define a TransLogger filter and include it in the WSGI pipeline.

```ini
[app:wsgiapp]
use = egg:mypackage#wsgiapp

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

[filter:translogger]
use = egg:Paste#translogger
setup_console_handler = False

[pipeline:main]
pipeline = translogger
           wsgiapp

```

--------------------------------

### Wire Access Log Formatter into File Handler

Source: https://github.com/pylons/waitress/blob/main/docs/logging.md

Update the 'accesslog' FileHandler configuration to use the newly defined 'accesslog' formatter.

```ini
[handler_accesslog]
class = FileHandler
args = ('%(here)s/access.log','a')
level = INFO
formatter = accesslog

```

--------------------------------

### Listen on Specific Host and Port

Source: https://github.com/pylons/waitress/blob/main/docs/runner.md

Configure Waitress to listen on a specific IP address and port. Supports multiple listen directives for multiple sockets.

```bash
--listen=127.0.0.1:8080
```

```bash
--listen=[::1]:8080
```

```bash
--listen=*:8080
```

--------------------------------

### Configure Waitress Logger Level in PasteDeploy

Source: https://github.com/pylons/waitress/blob/main/docs/logging.md

Configure the 'waitress' logger level to INFO within a PasteDeploy .ini file. This is an alternative to Python configuration.

```ini
[logger_waitress]
level = INFO
```

--------------------------------

### Serve WSGI App on IPv4 Only

Source: https://github.com/pylons/waitress/blob/main/docs/usage.md

Run Waitress on port 8080, specifically listening on all available IPv4 addresses, excluding IPv6. This is the default behavior if host is omitted.

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

--------------------------------

### Configure Pass-through Formatter for File Handler

Source: https://github.com/pylons/waitress/blob/main/docs/logging.md

Define a formatter named 'accesslog' that passes through log messages as is. This formatter is then used by the 'accesslog' FileHandler.

```ini
[formatters]
keys = generic, accesslog

[formatter_accesslog]
format = %(message)s

```

--------------------------------

### Trusted Proxy Headers Configuration

Source: https://github.com/pylons/waitress/blob/main/docs/runner.md

Define which proxy headers Waitress should trust when the `--trusted-proxy` option is set. Defaults to 'x-forwarded-proto' for backward compatibility.

```bash
--trusted-proxy-headers=forwarded
```

```bash
--trusted-proxy-headers=x-forwarded-host,x-forwarded-for,x-forwarded-proto,x-forwarded-port,x-forwarded-by
```

--------------------------------

### Configure Nginx Proxy Headers

Source: https://github.com/pylons/waitress/blob/main/docs/reverse-proxy.md

Set Nginx headers to forward protocol, client IP, host, and port information to the backend. Waitress can use these to reconstruct the original request details.

```nginx
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Host $host:$server_port;
proxy_set_header X-Forwarded-Port $server_port;
```

--------------------------------

### Configure Unix Socket Permissions

Source: https://github.com/pylons/waitress/blob/main/docs/arguments.md

Specify octal permissions for a Unix domain socket using the 'unix_socket_perms' argument. This is only used when 'unix_socket' is defined.

```python
unix_socket_perms='600'
```

--------------------------------

### Configure Waitress to Use Forwarded Header

Source: https://github.com/pylons/waitress/blob/main/docs/reverse-proxy.md

Configure Waitress to use the standardized 'Forwarded' header (RFC7239) instead of individual X-Forwarded-* headers. Note that the proxy's IP must be specified in `trusted_proxy`.

```text
trusted_proxy_headers = "forwarded"
```