nginx.rst (2681B)
1 Deploy behind nginx 2 =================== 3 4 This guide demonstrates a way to load balance connections across multiple 5 websockets server processes running on the same machine with nginx_. 6 7 We'll run server processes with Supervisor as described in :doc:`this guide 8 <supervisor>`. 9 10 .. _nginx: https://nginx.org/ 11 12 Run server processes 13 -------------------- 14 15 Save this app to ``app.py``: 16 17 .. literalinclude:: ../../example/deployment/nginx/app.py 18 :emphasize-lines: 21,23 19 20 We'd like to nginx to connect to websockets servers via Unix sockets in order 21 to avoid the overhead of TCP for communicating between processes running in 22 the same OS. 23 24 We start the app with :func:`~websockets.server.unix_serve`. Each server 25 process listens on a different socket thanks to an environment variable set 26 by Supervisor to a different value. 27 28 Save this configuration to ``supervisord.conf``: 29 30 .. literalinclude:: ../../example/deployment/nginx/supervisord.conf 31 32 This configuration runs four instances of the app. 33 34 Install Supervisor and run it: 35 36 .. code-block:: console 37 38 $ supervisord -c supervisord.conf -n 39 40 Configure and run nginx 41 ----------------------- 42 43 Here's a simple nginx configuration to load balance connections across four 44 processes: 45 46 .. literalinclude:: ../../example/deployment/nginx/nginx.conf 47 48 We set ``daemon off`` so we can run nginx in the foreground for testing. 49 50 Then we combine the `WebSocket proxying`_ and `load balancing`_ guides: 51 52 * The WebSocket protocol requires HTTP/1.1. We must set the HTTP protocol 53 version to 1.1, else nginx defaults to HTTP/1.0 for proxying. 54 55 * The WebSocket handshake involves the ``Connection`` and ``Upgrade`` HTTP 56 headers. We must pass them to the upstream explicitly, else nginx drops 57 them because they're hop-by-hop headers. 58 59 We deviate from the `WebSocket proxying`_ guide because its example adds a 60 ``Connection: Upgrade`` header to every upstream request, even if the 61 original request didn't contain that header. 62 63 * In the upstream configuration, we set the load balancing method to 64 ``least_conn`` in order to balance the number of active connections across 65 servers. This is best for long running connections. 66 67 .. _WebSocket proxying: http://nginx.org/en/docs/http/websocket.html 68 .. _load balancing: http://nginx.org/en/docs/http/load_balancing.html 69 70 Save the configuration to ``nginx.conf``, install nginx, and run it: 71 72 .. code-block:: console 73 74 $ nginx -c nginx.conf -p . 75 76 You can confirm that nginx proxies connections properly: 77 78 .. code-block:: console 79 80 $ PYTHONPATH=src python -m websockets ws://localhost:8080/ 81 Connected to ws://localhost:8080/. 82 > Hello! 83 < Hello! 84 Connection closed: 1000 (OK).