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] 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: