render.rst (5100B)
1 Deploy to Render 2 ================ 3 4 This guide describes how to deploy a websockets server to Render_. 5 6 .. _Render: https://render.com/ 7 8 .. admonition:: The free plan of Render is sufficient for trying this guide. 9 :class: tip 10 11 However, on a `free plan`__, connections are dropped after five minutes, 12 which is quite short for WebSocket application. 13 14 __ https://render.com/docs/free 15 16 We're going to deploy a very simple app. The process would be identical for a 17 more realistic app. 18 19 Create repository 20 ----------------- 21 22 Deploying to Render requires a git repository. Let's initialize one: 23 24 .. code-block:: console 25 26 $ mkdir websockets-echo 27 $ cd websockets-echo 28 $ git init -b main 29 Initialized empty Git repository in websockets-echo/.git/ 30 $ git commit --allow-empty -m "Initial commit." 31 [main (root-commit) 816c3b1] Initial commit. 32 33 Render requires the git repository to be hosted at GitHub or GitLab. 34 35 Sign up or log in to GitHub. Create a new repository named ``websockets-echo``. 36 Don't enable any of the initialization options offered by GitHub. Then, follow 37 instructions for pushing an existing repository from the command line. 38 39 After pushing, refresh your repository's homepage on GitHub. You should see an 40 empty repository with an empty initial commit. 41 42 Create application 43 ------------------ 44 45 Here's the implementation of the app, an echo server. Save it in a file called 46 ``app.py``: 47 48 .. literalinclude:: ../../example/deployment/render/app.py 49 :language: python 50 51 This app implements requirements for `zero downtime deploys`_: 52 53 * it provides a health check at ``/healthz``; 54 * it closes connections and exits cleanly when it receives a ``SIGTERM`` signal. 55 56 .. _zero downtime deploys: https://render.com/docs/deploys#zero-downtime-deploys 57 58 Create a ``requirements.txt`` file containing this line to declare a dependency 59 on websockets: 60 61 .. literalinclude:: ../../example/deployment/render/requirements.txt 62 :language: text 63 64 Confirm that you created the correct files and commit them to git: 65 66 .. code-block:: console 67 68 $ ls 69 app.py requirements.txt 70 $ git add . 71 $ git commit -m "Initial implementation." 72 [main f26bf7f] Initial implementation. 73 2 files changed, 37 insertions(+) 74 create mode 100644 app.py 75 create mode 100644 requirements.txt 76 77 Push the changes to GitHub: 78 79 .. code-block:: console 80 81 $ git push 82 ... 83 To github.com:<username>/websockets-echo.git 84 816c3b1..f26bf7f main -> main 85 86 The app is ready. Let's deploy it! 87 88 Deploy application 89 ------------------ 90 91 Sign up or log in to Render. 92 93 Create a new web service. Connect the git repository that you just created. 94 95 Then, finalize the configuration of your app as follows: 96 97 * **Name**: websockets-echo 98 * **Start Command**: ``python app.py`` 99 100 If you're just experimenting, select the free plan. Create the web service. 101 102 To configure the health check, go to Settings, scroll down to Health & Alerts, 103 and set: 104 105 * **Health Check Path**: /healthz 106 107 This triggers a new deployment. 108 109 Validate deployment 110 ------------------- 111 112 Let's confirm that your application is running as expected. 113 114 Since it's a WebSocket server, you need a WebSocket client, such as the 115 interactive client that comes with websockets. 116 117 If you're currently building a websockets server, perhaps you're already in a 118 virtualenv where websockets is installed. If not, you can install it in a new 119 virtualenv as follows: 120 121 .. code-block:: console 122 123 $ python -m venv websockets-client 124 $ . websockets-client/bin/activate 125 $ pip install websockets 126 127 Connect the interactive client — you must replace ``websockets-echo`` with the 128 name of your Render app in this command: 129 130 .. code-block:: console 131 132 $ python -m websockets wss://websockets-echo.onrender.com/ 133 Connected to wss://websockets-echo.onrender.com/. 134 > 135 136 Great! Your app is running! 137 138 Once you're connected, you can send any message and the server will echo it, 139 or press Ctrl-D to terminate the connection: 140 141 .. code-block:: console 142 143 > Hello! 144 < Hello! 145 Connection closed: 1000 (OK). 146 147 You can also confirm that your application shuts down gracefully when you deploy 148 a new version. Due to limitations of Render's free plan, you must upgrade to a 149 paid plan before you perform this test. 150 151 Connect an interactive client again — remember to replace ``websockets-echo`` 152 with your app: 153 154 .. code-block:: console 155 156 $ python -m websockets wss://websockets-echo.onrender.com/ 157 Connected to wss://websockets-echo.onrender.com/. 158 > 159 160 Trigger a new deployment with Manual Deploy > Deploy latest commit. When the 161 deployment completes, the connection is closed with code 1001 (going away). 162 163 .. code-block:: console 164 165 $ python -m websockets wss://websockets-echo.onrender.com/ 166 Connected to wss://websockets-echo.onrender.com/. 167 Connection closed: 1001 (going away). 168 169 If graceful shutdown wasn't working, the server wouldn't perform a closing 170 handshake and the connection would be closed with code 1006 (abnormal closure). 171 172 Remember to downgrade to a free plan if you upgraded just for testing this feature.