chore: add very minimal documentation for deploying uMap with ASGI (#2480)

This is just about ASGI, not the websockets and the sync itself.

We may merge it, or just keep it and amend it until we have the sync
official.

docs/deploy/asgi.md

@@ -0,0 +1,83 @@
+# ASGI
+
+While uMap has been historically deployed using the WSGI specification,
+there is now an **experimental** ASGI endpoint. This will be the way to
+deploy uMap to use the live collaborative editing feature, which needs
+websockets.
+
+## Nginx
+
+When using ASGI, the [nginx](nginx.md), the `/` entrypoint should be:
+
+```
+location / {
+    proxy_set_header Host $http_host;
+    proxy_set_header X-Forwarded-For $remote_addr;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection $connection_upgrade;
+    proxy_redirect off;
+    proxy_buffering off;
+    proxy_pass http://umap/;
+}
+```
+
+## Uvicorn
+
+Uvicorn must be installed in the umap virtualenv:
+
+    /path/to/umap/venv/bin/pip install uvicorn
+
+And could then be run like this:
+
+    /path/to/umap/venv/bin/uvicorn \
+    --proxy-headers \
+    --uds /srv/umap/umap.sock \
+    --no-access-log \
+    umap.asgi:application
+
+## Systemd
+
+Here is an example service to manage uvicorn with systemd:
+
+```
+[Unit]
+Description=umap
+After=network.target
+Requires=postgresql.service
+
+[Service]
+Type=simple
+User=umap
+
+WorkingDirectory=/srv/umap/
+PrivateTmp=true
+
+EnvironmentFile=/srv/umap/env
+
+ExecStart=/srv/umap/venv/bin/uvicorn \
+    --proxy-headers \
+    --uds /srv/umap/uvicorn.sock \
+    --no-access-log \
+    umap.asgi:application
+ExecReload=/bin/kill -HUP ${MAINPID}
+RestartSec=1
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Then to install it and enable it, copy it to `/etc/systemd/system/umap.service`
+and run:
+
+    sudo systemctl enable umap.service
+
+## Env
+
+Uvicorn can be [configured](https://www.uvicorn.org/deployment/) from env vars,
+for example to define the number of workers:
+
+```env title="/srv/umap/env"
+UVICORN_WORKERS=4
+```

docs/deploy/nginx.md

@@ -4,7 +4,7 @@ Here are some configuration files to use umap with nginx and [uWSGI](https://uws
 
 ```nginx title="nginx.conf"
 upstream umap {
-    server unix:///srv/umap/uwsgi.sock;
+    server unix:///srv/umap/umap.sock;
 }
 
 server {
@@ -69,7 +69,7 @@ master = true
 # maximum number of worker processes
 processes = 4
 # the socket (use the full path to be safe)
-socket = /srv/umap/uwsgi.sock
+socket = /srv/umap/umap.sock
 # ... with appropriate permissions - may be needed
 chmod-socket = 666
 stats = /srv/umap/stats.sock

mkdocs.yml

@@ -21,6 +21,7 @@ nav:
       - Docker: deploy/docker.md
       - Helm: deploy/helm.md
       - Nginx: deploy/nginx.md
+      - ASGI: deploy/asgi.md
   - Changelog: changelog.md
 theme:
   name: material