chore: add a deploy overview doc page

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.

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 {

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.

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/).

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