Deploy with Supervisor - websockets 12.0 documentation
Description: This guide proposes a simple way to deploy a websockets server directly on a Linux or BSD operating system. We’ll configure Supervisor to run several server processes and to restart them if needed....

Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# Deploy with Supervisor

This guide proposes a simple way to deploy a websockets server directly on a Linux or BSD operating system.

We’ll configure Supervisor to run several server processes and to restart them if needed.

We’ll bind all servers to the same port. The OS will take care of balancing connections.

Create and activate a virtualenv:

    $ python -m venv supervisor-websockets
    $ . supervisor-websockets/bin/activate

Install websockets and Supervisor:

    $ pip install websockets
    $ pip install supervisor

Save this app to a file called `app.py`:

    #!/usr/bin/env python

    import asyncio
    import signal

    import websockets

    async def echo(websocket):
        async for message in websocket:
            await websocket.send(message)

    async def main():
        # Set the stop condition when receiving SIGTERM.
        loop = asyncio.get_running_loop()
        stop = loop.create_future()
        loop.add_signal_handler(signal.SIGTERM, stop.set_result, None)

        async with websockets.serve(
            echo,
            host="",
            port=8080,
            reuse_port=True,
        ):
            await stop

    if __name__ == "__main__":
        asyncio.run(main())

This is an echo server with two features added for the purpose of this guide:

- It shuts down gracefully when receiving a `SIGTERM` signal;

- It enables the `reuse_port` option of `create_server()`, which in turns sets `SO_REUSEPORT` on the accept socket.

Save this Supervisor configuration to `supervisord.conf`:

    [supervisord]

    [program:websockets-test]
    command = python app.py
    process_name = %(program_name)s_%(process_num)02d
    numprocs = 4
    autorestart = true

This is the minimal configuration required to keep four instances of the app running, restarting them if they exit.

Now start Supervisor in the foreground:

    $ supervisord -c supervisord.conf -n
    INFO Increased RLIMIT_NOFILE limit to 1024
    INFO supervisord started with pid 43596
    INFO spawned: 'websockets-test_00' with pid 43597
    INFO spawned: 'websockets-test_01' with pid 43598
    INFO spawned: 'websockets-test_02' with pid 43599
    INFO spawned: 'websockets-test_03' with pid 43600
    INFO success: websockets-test_00 entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)
    INFO success: websockets-test_01 entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)
    INFO success: websockets-test_02 entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)
    INFO success: websockets-test_03 entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)

In another shell, after activating the virtualenv, we can connect to the app — press Ctrl-D to exit:

    $ python -m websockets ws://localhost:8080/
    Connected to ws://localhost:8080/.
    > Hello!
    < Hello!
    Connection closed: 1000 (OK).

Look at the pid of an instance of the app in the logs and terminate it:

    $ kill -TERM 43597

The logs show that Supervisor restarted this instance:

    INFO exited: websockets-test_00 (exit status 0; expected)
    INFO spawned: 'websockets-test_00' with pid 43629
    INFO success: websockets-test_00 entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)

Now let’s check what happens when we shut down Supervisor, but first let’s establish a connection and leave it open:

    $ python -m websockets ws://localhost:8080/
    Connected to ws://localhost:8080/.
    >

Look at the pid of supervisord itself in the logs and terminate it:

    $ kill -TERM 43596

The logs show that Supervisor terminated all instances of the app before exiting:

    WARN received SIGTERM indicating exit request
    INFO waiting for websockets-test_00, websockets-test_01, websockets-test_02, websockets-test_03 to die
    INFO stopped: websockets-test_02 (exit status 0)
    INFO stopped: websockets-test_03 (exit status 0)
    INFO stopped: websockets-test_01 (exit status 0)
    INFO stopped: websockets-test_00 (exit status 0)

And you can see that the connection to the app was closed gracefully:

    $ python -m websockets ws://localhost:8080/
    Connected to ws://localhost:8080/.
    Connection closed: 1001 (going away).

In this example, we’ve been sharing the same virtualenv for supervisor and websockets.

In a real deployment, you would likely:

- Install Supervisor with the package manager of the OS.

- Create a virtualenv dedicated to your application.

- Add `environment=PATH="path/to/your/virtualenv/bin"` in the Supervisor configuration. Then `python app.py` runs in that virtualenv.