fix(docs): update local settings and ASGI docs

docs/config/settings.md

@@ -154,6 +154,14 @@ The final URL of you instance, including the protocol:
 `SITE_URL=http://umap.org`
 
 
+#### CSRF_TRUSTED_ORIGINS
+
+List of HTTP origins (scheme and host, for example `http://umap.org`)
+to trust for POST requests.  This is necessary if you wish to allow
+local (non-OAuth) logins, in which case you should add the values of
+`SITE_URL` and `SHORT_SITE_URL`.
+
+
 #### SOCIAL_AUTH_OPENSTREETMAP_OAUTH2_KEY, SOCIAL_AUTH_OPENSTREETMAP_OAUTH2_SECRET
 
 If you use OpenStreetMap as OAuth 2 provider, you can use those settings.

docs/deploy/asgi.md

@@ -18,11 +18,17 @@ location / {
     proxy_set_header Connection $connection_upgrade;
     proxy_redirect off;
     proxy_buffering off;
-    proxy_pass http://umap/;
+    proxy_pass http://unix:/srv/umap/umap.sock:/;
 }
 ```
 
-Also add this mapping for the `$connection_upgrade` variable:
+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 {
@@ -31,6 +37,9 @@ map $http_upgrade $connection_upgrade {
 }
 ```
 
+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:
@@ -66,7 +75,7 @@ EnvironmentFile=/srv/umap/env
 
 ExecStart=/srv/umap/venv/bin/uvicorn \
     --proxy-headers \
-    --uds /srv/umap/uvicorn.sock \
+    --uds /srv/umap/umap.sock \
     --no-access-log \
     umap.asgi:application
 ExecReload=/bin/kill -HUP ${MAINPID}
@@ -90,3 +99,7 @@ for example to define the number of workers:
 ```env title="/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.

docs/install.md

@@ -46,6 +46,17 @@ createdb umap -O umap -U postgres
 psql umap -c "CREATE EXTENSION postgis" -Upostgres
 ```
 
+On Debian, you will need run these commands explicitly as the `postgres` user, for example:
+
+```bash
+sudo -u postgres createuser umap
+sudo -u postgres createdb umap -O umap
+sudo -u postgres psql umap -c "CREATE EXTENSION postgis"
+```
+
+Also, since PostgreSQL uses Unix user accounts for authentication, you
+must create a system user called `umap` which will run uMap.
+
 ## Getting started
 
 Create a geo aware database. See the [GeoDjango docs](https://docs.djangoproject.com/en/dev/ref/contrib/gis/install/) for backend installation.
@@ -135,7 +146,8 @@ TWITTER_CONSUMER_KEY = "xxx"
 TWITTER_CONSUMER_SECRET = "yyy"
 ```
 
-Example of callback URL to use for setting up OAuth apps
+Example of callback URL to use for setting up OAuth apps (where
+`umap.foo.bar` should be replaced with your site URL):
 
 http://umap.foo.bar/complete/github/
 

umap/settings/local.py.sample

@@ -12,7 +12,7 @@ your code repository.
 from umap.settings.base import *  # pylint: disable=W0614,W0401
 
 SECRET_KEY = "!!change me!!"
-INTERNAL_IPS = ("127.0.0.1",)
+INTERNAL_IPS = ["127.0.0.1"]
 ALLOWED_HOSTS = [
     "*",
 ]
@@ -39,7 +39,7 @@ AUTHENTICATION_BACKENDS = (
     "social_core.backends.github.GithubOAuth2",
     "social_core.backends.bitbucket.BitbucketOAuth",
     "social_core.backends.twitter.TwitterOAuth",
-    "social_core.backends.openstreetmap.OpenStreetMapOAuth",
+    "social_core.backends.openstreetmap_oauth2.OpenStreetMapOAuth2",
     "django.contrib.auth.backends.ModelBackend",
 )
 SOCIAL_AUTH_GITHUB_KEY = "xxx"
@@ -80,6 +80,8 @@ UMAP_MAPS_PER_PAGE_OWNER = 10
 
 SITE_URL = "http://localhost:8019"
 SHORT_SITE_URL = "http://s.hort"
+# Add SITE_URL and SHORT_SITE_URL to this list to allow local (non-OAuth) logins
+CSRF_TRUSTED_ORIGINS = []
 
 # CACHES = {
 #     'default': {