Skip to content

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, 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://unix:/srv/umap/umap.sock:/;
}

The proxy_pass is a Unix domain socket here but may also be an IP address and port. See https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass for more information.

Also add this mapping for the $connection_upgrade variable, outside the server section, to enable WebSockets support:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

See https://nginx.org/en/docs/http/websocket.html for more information about configuring WebSockets in nginx.

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/umap.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 from env vars, for example to define the number of workers:

/srv/umap/env
UVICORN_WORKERS=4

Don't forget to set the UMAP_SETTINGS environment variable to point to your local_settings.py, which you can also do in the the file named in EnvironmentFile or with Environment directives.