From 2084401b6c655efabc5867a17fdd2f85a6501af6 Mon Sep 17 00:00:00 2001
From: Yohan Boniface <yohanboniface@free.fr>
Date: Thu, 29 Jun 2023 10:25:19 +0200
Subject: [PATCH 1/7] Add basic doc about settings

---
 docs/docker.md   |  11 ++++
 docs/settings.md | 164 +++++++++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml       |   1 +
 3 files changed, 176 insertions(+)
 create mode 100644 docs/settings.md

diff --git a/docs/docker.md b/docs/docker.md
index baceccb7..03c4d89a 100644
--- a/docs/docker.md
+++ b/docs/docker.md
@@ -31,3 +31,14 @@ volumes:
   data:
   db:
 ```
+
+### Create superuser
+
+With docker-compose, run `docker-compose run app /venv/bin/umap createsuperuser`
+
+
+### Custom settings
+
+Some basic settings are available through env vars (see https://github.com/umap-project/umap/blob/master/umap/settings/base.py),
+but if you need more custom ones (like custom OAuth configuration), the easiest
+way is to push a settings file to `/etc/umap/umap.conf`.
diff --git a/docs/settings.md b/docs/settings.md
new file mode 100644
index 00000000..8e73857e
--- /dev/null
+++ b/docs/settings.md
@@ -0,0 +1,164 @@
+# Configuration
+
+uMap runs with Django, so any Django setting should work, if you know what you
+are doing.
+
+The Django settings reference is here: https://docs.djangoproject.com/en/4.2/ref/settings/
+
+Here are a few relevent settings for uMap.
+
+
+#### ALLOWED_HOSTS
+
+The hosts that uMap expects.
+`ALLOWED_HOSTS = ['umap.mydomain.org']`
+
+Can be set through env var too: `ALLOWED_HOSTS=umap.mydomain.org`
+
+#### DEBUG
+
+Set it to True for easier debugging in case of error.
+
+#### EMAIL_BACKEND
+
+Must be configured if you want uMap to send emails to anonymous users.
+
+See [Emails](install.md#emails) for more details.
+
+#### ENABLE_ACCOUNT_LOGIN
+
+Do you want users to be able to create an account directly on your uMap instance
+(instead of only using OAuth).
+
+Can be set through env var: `ENABLE_ACCOUNT_LOGIN=1`
+
+#### FROM_EMAIL
+
+See `EMAIL_BACKEND`.
+
+#### LANGUAGE_CODE
+
+Set it to the default language you want. `LANGUAGE_CODE = "it"`
+
+#### LEAFLET_LONGITUDE, LEAFLET_LATITUDE, LEAFLET_ZOOM
+
+Default longitude, latitude and zoom for the map
+
+#### MEDIA_ROOT
+
+Where uMap should datalayers and icons, must be consistent with your
+Nginx configuration.
+
+#### SECRET_KEY
+
+Must be defined to something unique and secret.
+
+#### SITE_URL
+
+The final URL of you instance, including the protocol:
+
+`SITE_URL="http://umap.org"`
+
+
+#### SHORT_SITE_URL
+
+If you have a short domain for sharing links.
+
+Eg.: `SHORT_SITE_URL=https://u.umap.org`
+
+
+#### SITE_NAME
+
+The name of the site, to be used in header and HTML title.
+
+
+#### STATIC_ROOT
+
+Where uMap should store static files (CSS, JS…), must be consistent with your
+Nginx configuration.
+
+#### USE_I18N
+
+Default is True. Set it to False if you don't want uMap to localize the app.
+
+#### USER_AUTOCOMPLETE_FIELDS
+
+Which fields to search when autocompleting users (in permissions).
+Eg.: `USER_AUTOCOMPLETE_FIELDS = ["^username", "email"]`
+
+
+#### USER_DISPLAY_NAME
+
+Advanced setting for controling which user fields will be used for displaying
+they name on the application, depending on which fields you collect with your
+OAuth configuration.
+For example: `USER_DISPLAY_NAME = "{username}"`
+
+#### USER_URL_FIELD
+
+Which field to be used in URL for user. Must be a unique field.
+
+Eg.: `USER_URL_FIELD = "pk"`
+
+#### UMAP_ALLOW_ANONYMOUS
+
+Should uMap allows user without an account to create maps.
+
+Can be set through env var: `UMAP_ALLOW_ANONYMOUS=1`
+
+
+#### UMAP_EXTRA_URLS
+
+By default:
+```
+UMAP_EXTRA_URLS = {
+    'routing': 'http://www.openstreetmap.org/directions?engine=osrm_car&route={lat},{lng}&locale={locale}#map={zoom}/{lat}/{lng}',
+    'ajax_proxy': '/ajax-proxy/?url={url}&ttl={ttl}',
+    'search': 'https://photon.komoot.io/api/?',
+}
+```
+
+#### UMAP_KEEP_VERSIONS
+
+How many datalayer versions to keep. 10 by default.
+
+#### UMAP_DEMO_SITE
+
+Set to True if you want to display a message saying that your instance is not
+ready for production use (no backup, etc.)
+
+#### UMAP_FEEDBACK_LINK
+
+Link to show on the header under the "Feedback and help" label.
+
+#### UMAP_MAPS_PER_PAGE
+
+How many maps to show in maps list, like search or home page.
+
+#### UMAP_MAPS_PER_SEARCH
+
+How many total maps to return in the search.
+
+#### UMAP_MAPS_PER_PAGE_OWNER
+
+How many maps to show in the user "my maps" page.
+
+#### UMAP_SEARCH_CONFIGURATION
+
+Use it if you take control over the search configuration.
+
+See [search](install.md#search) for details.
+
+#### UMAP_READONLY
+
+Is your instance readonly ? Useful for server maintenance.
+
+#### UMAP_GZIP
+
+Should uMap gzip datalayers geojson.
+
+#### SOCIAL_AUTH_OPENSTREETMAP_KEY, SOCIAL_AUTH_OPENSTREETMAP_SECRET
+
+If you use OpenStreetMap as OAuth provider, use those settings.
+
+Otherwise, use any valid [python-social-auth configuration](https://python-social-auth.readthedocs.io/en/latest/configuration/django.html).
diff --git a/mkdocs.yml b/mkdocs.yml
index c09cc09d..36c2eab1 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -2,6 +2,7 @@ site_name: uMap
 nav:
 - Home: index.md
 - Installation: install.md
+- Configuration: settings.md
 - Administration: administration.md
 - Contributing: contributing.md
 - how-tos:

From 00796a42f137914d384d53cb17b3fcc9cb1d77ac Mon Sep 17 00:00:00 2001
From: Yohan Boniface <yb@enix.org>
Date: Thu, 29 Jun 2023 15:26:34 +0200
Subject: [PATCH 2/7] Update docs/docker.md

Co-authored-by: David Larlet <3556+davidbgk@users.noreply.github.com>
---
 docs/docker.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/docker.md b/docs/docker.md
index 03c4d89a..62ec45ca 100644
--- a/docs/docker.md
+++ b/docs/docker.md
@@ -41,4 +41,4 @@ With docker-compose, run `docker-compose run app /venv/bin/umap createsuperuser`
 
 Some basic settings are available through env vars (see https://github.com/umap-project/umap/blob/master/umap/settings/base.py),
 but if you need more custom ones (like custom OAuth configuration), the easiest
-way is to push a settings file to `/etc/umap/umap.conf`.
+way is to push a [settings file](settings.md) to `/etc/umap/umap.conf`.

From a281ea9cb257d832bd334be1097f7343e07a8c44 Mon Sep 17 00:00:00 2001
From: Yohan Boniface <yb@enix.org>
Date: Thu, 29 Jun 2023 15:26:54 +0200
Subject: [PATCH 3/7] Update docs/settings.md

Co-authored-by: David Larlet <3556+davidbgk@users.noreply.github.com>
---
 docs/settings.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/settings.md b/docs/settings.md
index 8e73857e..a3d909f6 100644
--- a/docs/settings.md
+++ b/docs/settings.md
@@ -46,7 +46,7 @@ Default longitude, latitude and zoom for the map
 
 #### MEDIA_ROOT
 
-Where uMap should datalayers and icons, must be consistent with your
+Where uMap should store your datalayers and icons, must be consistent with your
 Nginx configuration.
 
 #### SECRET_KEY

From b5681f456671967eed1f305fc30a1918dee73479 Mon Sep 17 00:00:00 2001
From: Yohan Boniface <yb@enix.org>
Date: Thu, 29 Jun 2023 15:28:31 +0200
Subject: [PATCH 4/7] Update docs/settings.md

Co-authored-by: David Larlet <3556+davidbgk@users.noreply.github.com>
---
 docs/settings.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/settings.md b/docs/settings.md
index a3d909f6..f3e1abae 100644
--- a/docs/settings.md
+++ b/docs/settings.md
@@ -90,7 +90,7 @@ Eg.: `USER_AUTOCOMPLETE_FIELDS = ["^username", "email"]`
 #### USER_DISPLAY_NAME
 
 Advanced setting for controling which user fields will be used for displaying
-they name on the application, depending on which fields you collect with your
+their name on the application, depending on which fields you collect with your
 OAuth configuration.
 For example: `USER_DISPLAY_NAME = "{username}"`
 

From 24de5730531895f1aa9b85415631aa297637b83f Mon Sep 17 00:00:00 2001
From: Yohan Boniface <yb@enix.org>
Date: Thu, 29 Jun 2023 15:28:48 +0200
Subject: [PATCH 5/7] Update docs/settings.md

Co-authored-by: David Larlet <3556+davidbgk@users.noreply.github.com>
---
 docs/settings.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/settings.md b/docs/settings.md
index f3e1abae..298f45b7 100644
--- a/docs/settings.md
+++ b/docs/settings.md
@@ -151,7 +151,7 @@ See [search](install.md#search) for details.
 
 #### UMAP_READONLY
 
-Is your instance readonly ? Useful for server maintenance.
+Is your instance readonly? Useful for server maintenance.
 
 #### UMAP_GZIP
 

From 44af4b769be61043c7cc210813908a004d2910e8 Mon Sep 17 00:00:00 2001
From: Yohan Boniface <yohanboniface@free.fr>
Date: Thu, 29 Jun 2023 15:33:20 +0200
Subject: [PATCH 6/7] Proofreading settings.md

---
 docs/settings.md | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/docs/settings.md b/docs/settings.md
index 298f45b7..5679e8c8 100644
--- a/docs/settings.md
+++ b/docs/settings.md
@@ -7,13 +7,21 @@ The Django settings reference is here: https://docs.djangoproject.com/en/4.2/ref
 
 Here are a few relevent settings for uMap.
 
+## Usage
+
+Those settings should either:
+
+- be in `/etc/umap/umap.conf`, which uMap will try to load by default
+- be in a random place on your server, which is then reference with the
+  `UMAP_SETTINGS` env var
+- be declared as env vars directly, for simple ones (string/boolean/list)
 
 #### ALLOWED_HOSTS
 
 The hosts that uMap expects.
 `ALLOWED_HOSTS = ['umap.mydomain.org']`
 
-Can be set through env var too: `ALLOWED_HOSTS=umap.mydomain.org`
+Can be set through env var too: `ALLOWED_HOSTS=umap.mydomain.org,u.mydomain.org`
 
 #### DEBUG
 
@@ -57,7 +65,7 @@ Must be defined to something unique and secret.
 
 The final URL of you instance, including the protocol:
 
-`SITE_URL="http://umap.org"`
+`SITE_URL=http://umap.org`
 
 
 #### SHORT_SITE_URL
@@ -102,7 +110,7 @@ Eg.: `USER_URL_FIELD = "pk"`
 
 #### UMAP_ALLOW_ANONYMOUS
 
-Should uMap allows user without an account to create maps.
+Should uMap allows user without an account to create maps (default is False).
 
 Can be set through env var: `UMAP_ALLOW_ANONYMOUS=1`
 

From 2618b081f76c75e01732d1535e10b56609270d4a Mon Sep 17 00:00:00 2001
From: Yohan Boniface <yohanboniface@free.fr>
Date: Thu, 29 Jun 2023 15:37:40 +0200
Subject: [PATCH 7/7] Add links to Django doc for standard settings

---
 docs/settings.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/settings.md b/docs/settings.md
index 5679e8c8..d8803d7e 100644
--- a/docs/settings.md
+++ b/docs/settings.md
@@ -57,6 +57,8 @@ Default longitude, latitude and zoom for the map
 Where uMap should store your datalayers and icons, must be consistent with your
 Nginx configuration.
 
+See [Django documentation for MEDIA_ROOT](https://docs.djangoproject.com/en/4.2/ref/settings/#media-root)
+
 #### SECRET_KEY
 
 Must be defined to something unique and secret.
@@ -85,6 +87,8 @@ The name of the site, to be used in header and HTML title.
 Where uMap should store static files (CSS, JS…), must be consistent with your
 Nginx configuration.
 
+See [Django documentation for STATIC_ROOT](https://docs.djangoproject.com/en/4.2/ref/settings/#static-root)
+
 #### USE_I18N
 
 Default is True. Set it to False if you don't want uMap to localize the app.