diff --git a/docs/config/settings.md b/docs/config/settings.md index b31cf3d3..cf180fa5 100644 --- a/docs/config/settings.md +++ b/docs/config/settings.md @@ -95,6 +95,12 @@ A switch will be available for them in the "advanced properties" of the map. See [the documentation about ASGI deployment](../deploy/asgi.md) for more information. +#### REDIS_URL + +Connection URL to the Redis server. Only need for the real-time editing. + +Default: `redis://localhost:6379` + #### SECRET_KEY Must be defined to something unique and secret. diff --git a/docs/deploy/nginx.md b/docs/deploy/nginx.md index c2ec45e4..15335eba 100644 --- a/docs/deploy/nginx.md +++ b/docs/deploy/nginx.md @@ -1,84 +1,10 @@ # Configuring Nginx -Here are some configuration files to use umap with nginx and [uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/), a server for python, which will handle your processes for you. +See [WSGI](wsgi.md) or [ASGI](asgi.md) for a basic setup. -```nginx title="nginx.conf" -upstream umap { - server unix:///srv/umap/umap.sock; -} +Then consider adding this configuration -server { - # the port your site will be served on - listen 80; - listen [::]:80; - listen 443 ssl; - listen [::]:443 ssl; - # the domain name it will serve for - server_name your-domain.org; - charset utf-8; - - # max upload size - client_max_body_size 5M; # adjust to taste - - # Finally, send all non-media requests to the Django server. - location / { - uwsgi_pass umap; - include /srv/umap/uwsgi_params; - } -} -``` - -## uWSGI - - -```nginx title="uwsgi_params" -uwsgi_param QUERY_STRING $query_string; -uwsgi_param REQUEST_METHOD $request_method; -uwsgi_param CONTENT_TYPE $content_type; -uwsgi_param CONTENT_LENGTH $content_length; - -uwsgi_param REQUEST_URI $request_uri; -uwsgi_param PATH_INFO $document_uri; -uwsgi_param DOCUMENT_ROOT $document_root; -uwsgi_param SERVER_PROTOCOL $server_protocol; -uwsgi_param REQUEST_SCHEME $scheme; -uwsgi_param HTTPS $https if_not_empty; - -uwsgi_param REMOTE_ADDR $remote_addr; -uwsgi_param REMOTE_PORT $remote_port; -uwsgi_param SERVER_PORT $server_port; -uwsgi_param SERVER_NAME $server_name; -``` - - -```ini title="uwsgi.ini" -[uwsgi] -uid = umap -gid = users -# Python related settings -# the base directory (full path) -chdir = /srv/umap/ -# umap's wsgi module -module = umap.wsgi -# the virtualenv (full path) -home = /srv/umap/venv - -# process-related settings -# master -master = true -# maximum number of worker processes -processes = 4 -# the socket (use the full path to be safe) -socket = /srv/umap/umap.sock -# ... with appropriate permissions - may be needed -chmod-socket = 666 -stats = /srv/umap/stats.sock -# clear environment on exit -vacuum = true -plugins = python3 -``` - -## Static files +## Static files and geojson ```nginx title="nginx.conf" location /static { diff --git a/docs/deploy/overview.md b/docs/deploy/overview.md new file mode 100644 index 00000000..51091bef --- /dev/null +++ b/docs/deploy/overview.md @@ -0,0 +1,37 @@ +# Deploying uMap + +uMap is a python package, running [Django](https://docs.djangoproject.com/en/5.2/howto/deployment/), +so anyone experimented with this stack will find it familiar, but there are some speficic details +to know about. + +## Data +One important design point of uMap is that while metadata are stored in a PostgreSQL database, the +data itself is stored in the file system, as geojson files. This design choice has been made +to make uMap scale better, as there are much more reads than writes, and when some +map is shared a lot (like on a national media) we want to be able to serve it without needing an +overcomplex and costly stack. + +So when a request for data is made (that is on a *DataLayer*), the flow is that uMap will read +the request headers to check for permissions, and then it will forward the request to Nginx, +that will properly serve the data (a geojson file), without consuming a python worker, and with +much more efficiency than python. + +In DEBUG mode, uMap will serve the geojson itself, but this is not recommended in production, +unless you have a very small audience. + +Data can also be stored in a [S3 like storage](../config/storage/#using-s3). + +## Assets (JS, CSS…) +As any web app, uMap also needs static files to be served. In DEBUG mode, Django will do this +kindly, but not in production. See [Nginx configuration](nginx.md) for this. + +Assets can also be stored in a [S3 like storage](../config/storage/#using-s3). + +## python app (metadata, permissions…) + +uMap needs a python server, which can either be of [WSGI](wsgi.md) or [ASGI](asgi.md) (this later +is needed in order to use the collaborative live editing). + +## Redis + +Still when using the collaborative live editing, uMap needs a [Redis](../config/settings.md#redis_url) server, to act as pubsub. diff --git a/docs/deploy/wsgi.md b/docs/deploy/wsgi.md new file mode 100644 index 00000000..1c632645 --- /dev/null +++ b/docs/deploy/wsgi.md @@ -0,0 +1,87 @@ +# WSGI + +WSGI is the historical standard to serve python in general, and uMap in this case. +From recently, uMap also supports [ASGI](asgi.md), which is required to use the +collaborative editing feature. + +## uWSGI + +In Nginx host, use: + +```nginx title="nginx.conf" +upstream umap { + server unix:///srv/umap/umap.sock; +} + +server { + # the port your site will be served on + listen 80; + listen [::]:80; + listen 443 ssl; + listen [::]:443 ssl; + # the domain name it will serve for + server_name your-domain.org; + charset utf-8; + + # max upload size + client_max_body_size 5M; # adjust to taste + + # Finally, send all non-media requests to the Django server. + location / { + uwsgi_pass umap; + include /srv/umap/uwsgi_params; + } +} +``` + + + +```nginx title="uwsgi_params" +uwsgi_param QUERY_STRING $query_string; +uwsgi_param REQUEST_METHOD $request_method; +uwsgi_param CONTENT_TYPE $content_type; +uwsgi_param CONTENT_LENGTH $content_length; + +uwsgi_param REQUEST_URI $request_uri; +uwsgi_param PATH_INFO $document_uri; +uwsgi_param DOCUMENT_ROOT $document_root; +uwsgi_param SERVER_PROTOCOL $server_protocol; +uwsgi_param REQUEST_SCHEME $scheme; +uwsgi_param HTTPS $https if_not_empty; + +uwsgi_param REMOTE_ADDR $remote_addr; +uwsgi_param REMOTE_PORT $remote_port; +uwsgi_param SERVER_PORT $server_port; +uwsgi_param SERVER_NAME $server_name; +``` + + +```ini title="uwsgi.ini" +[uwsgi] +uid = umap +gid = users +# Python related settings +# the base directory (full path) +chdir = /srv/umap/ +# umap's wsgi module +module = umap.wsgi +# the virtualenv (full path) +home = /srv/umap/venv + +# process-related settings +# master +master = true +# maximum number of worker processes +processes = 4 +# the socket (use the full path to be safe) +socket = /srv/umap/umap.sock +# ... with appropriate permissions - may be needed +chmod-socket = 666 +stats = /srv/umap/stats.sock +# clear environment on exit +vacuum = true +plugins = python3 +``` + + +See also [Django documentation](https://docs.djangoproject.com/en/5.2/howto/deployment/wsgi/). diff --git a/mkdocs.yml b/mkdocs.yml index c8559383..93ad2a8a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -18,10 +18,12 @@ nav: - Storage: config/storage.md - Icon packs: config/icons.md - Deployment: + - Overview: deploy/overview.md - Docker: deploy/docker.md - Helm: deploy/helm.md - Nginx: deploy/nginx.md - ASGI: deploy/asgi.md + - WSGI: deploy/wsgi.md - Changelog: changelog.md theme: name: material