jeff/umap
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

[docs] Rework the documentation

Browse source
This commit is contained in:
Alexis Métaireau 2023-12-05 16:18:10 +01:00
parent 8804a953ee
commit c058db8ae2
14 changed files with 272 additions and 596 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
docs/architecture/frontend.md
View file

@ -1,6 +1,10 @@
# The frontend # The frontend
uMap is using Leaflet on the frontend. It's actually extending it: each uMap object extends the ones from Leaflet. !!! info "These are notes"
Consider this page as notes taken while exploring uMap. It's not covering everything but hopefully will help you get a basic understanding of how things work.
uMap uses Leaflet on the frontend. A lot of uMap objects extends the ones from Leaflet with additional abilities.
```mermaid ```mermaid
erDiagram erDiagram

11
docs/architecture/overview.md Normal file
View file

@ -0,0 +1,11 @@
# Overview of uMap
uMap is a server and a client. The server is build with the Django framework, and the client uses (vanilla) JavaScript, on top of Leaflet.
Basically, here is how it works:
- Most of the data is stored as [geoJSON files](https://datatracker.ietf.org/doc/html/rfc7946), on the server.
- Some other parts of the data is stored in the database (users, permissions, etc)
- PostGIS is used for some of its geo features, but for the most part, the computation is done on the frontend with Leaflet.
The server is meant to be a simple layer to do the storage and serve the JavaScript.

4
docs/assets/logo.svg Normal file
View file

@ -0,0 +1,4 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" width="128" height="128">
<path d="M36.5 6.2A64 64 0 0 0 64 128C14.5 81.8 3.1 24.8 36.5 6.2zM64 128A64 64 0 0 0 91.5 6.2c33.4 18.6 22 75.6-27.5 121.8z" fill="#fff"/>
<path d="M87.7 33.8a23.7 23.7 0 1 1-47.4 0 23.7 23.7 0 0 1 47.4 0z" fill="#fff"/>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 321 B

4
docs/custom.md → docs/config/customize.md
View file

@ -1,6 +1,6 @@
# Customize your uMap installation # Customize your uMap installation
When running your own uMap, you may want to changed its appearance, for example When running your own uMap, you may want to change its appearance, for example
you want your own logo on the home page, or you want to apply some design, or you want your own logo on the home page, or you want to apply some design, or
you want to add some tracking (but anonymous!) script… you want to add some tracking (but anonymous!) script…
@ -9,7 +9,7 @@ that.
So basically you'll have your own templates and/or statics directories where So basically you'll have your own templates and/or statics directories where
you will put the templates or statics you want to control (and only those). you will put the templates or statics you want to control (and only those).
Inside thore directory, you need to respect the exact relative path of the Inside those directory, you need to respect the exact relative path of the
templates or statics you are adding, relatively to the templates or statics you are adding, relatively to the
[templates](https://github.com/umap-project/umap/tree/master/umap/templates) [templates](https://github.com/umap-project/umap/tree/master/umap/templates)
and and

18
docs/administration.md → docs/config/icons.md
View file

@ -1,10 +1,4 @@
# Administration # Icons
You can access uMap administration page by navigating to `https://your.server.org/admin`
You will have to connect with the admin account created during installation. Default admin username is "umap".
## Icons
Icons (aka pictograms in uMap sources) can be used in your map markers. Icons (aka pictograms in uMap sources) can be used in your map markers.
@ -22,11 +16,11 @@ Example of icons libraries you may want to use:
- [SJJB Icons](http://www.sjjb.co.uk/mapicons/contactsheet) - [SJJB Icons](http://www.sjjb.co.uk/mapicons/contactsheet)
- [Remix](https://remixicon.com/) - [Remix](https://remixicon.com/)
### Import icons manually ## Import icons manually
You can import icons manually by going to your uMap admin page: `https://your.server.org/admin` You can import icons manually by going to your uMap admin page: `https://your.server.org/admin`
### Import icons automatically ## Import icons automatically
To import icons on your uMap server, you will need to use the command `umap import_pictograms`. To import icons on your uMap server, you will need to use the command `umap import_pictograms`.
@ -34,9 +28,11 @@ Note: you can get help with `umap import_pictograms -h`
Basic usage: Basic usage:
umap import_pictograms --attribution "Maki Icons by Mapbox" path/to/icons/directory/ ```bash
umap import_pictograms --attribution "Maki Icons by Mapbox" path/to/icons/directory/
```
### Categories ## Categories
uMap can render icons grouped into categories. When using the import script, any uMap can render icons grouped into categories. When using the import script, any
subfolder will be used as category. subfolder will be used as category.

69
docs/settings.md → docs/config/settings.md
View file

@ -16,6 +16,7 @@ Those settings should either:
`UMAP_SETTINGS` env var `UMAP_SETTINGS` env var
- be declared as env vars directly, for simple ones (string/boolean/list) - be declared as env vars directly, for simple ones (string/boolean/list)
#### ALLOWED_HOSTS #### ALLOWED_HOSTS
The hosts that uMap expects. The hosts that uMap expects.
@ -23,15 +24,46 @@ The hosts that uMap expects.
Can be set through env var too: `ALLOWED_HOSTS=umap.mydomain.org,u.mydomain.org` Can be set through env var too: `ALLOWED_HOSTS=umap.mydomain.org,u.mydomain.org`
#### COMPRESS_ENABLED
#### COMPRESS_STORAGE
To activate the compression of the static files, you can set this flag to `True`.
You can then run the following command to compress the assets:
```bash
umap compress
```
Optionally add `COMPRESS_STORAGE = "compressor.storage.GzipCompressorFileStorage"`
and add `gzip_static on` directive to Nginx `/static` location, so Nginx will
serve pregenerated files instead of compressing them on the fly.
#### DEBUG #### DEBUG
Set it to True for easier debugging in case of error. Set it to `True`` for easier debugging in case of error.
#### EMAIL_BACKEND #### EMAIL_BACKEND
Must be configured if you want uMap to send emails to anonymous users. Must be configured if you want uMap to send emails to anonymous users.
See [Emails](install.md#emails) for more details. UMap can send the anonymous edit link by email. For this to work, you need to
add email specific settings. See [Django](https://docs.djangoproject.com/en/4.2/topics/email/#smtp-backend)
documentation.
In general, you'll need to add something like this in your local settings:
```python title="local_settings.py"
FROM_EMAIL = "youradmin@email.org"
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "smtp.provider.org"
EMAIL_PORT = 456
EMAIL_HOST_USER = "username"
EMAIL_HOST_PASSWORD = "xxxx"
EMAIL_USE_TLS = True
# or
EMAIL_USE_SSL = True
```
#### ENABLE_ACCOUNT_LOGIN #### ENABLE_ACCOUNT_LOGIN
@ -48,6 +80,7 @@ See `EMAIL_BACKEND`.
Set it to the default language you want. `LANGUAGE_CODE = "it"` Set it to the default language you want. `LANGUAGE_CODE = "it"`
#### Default map center
#### LEAFLET_LONGITUDE, LEAFLET_LATITUDE, LEAFLET_ZOOM #### LEAFLET_LONGITUDE, LEAFLET_LATITUDE, LEAFLET_ZOOM
Default longitude, latitude and zoom for the map Default longitude, latitude and zoom for the map
@ -128,14 +161,14 @@ To be used when you want to override some HTML templates:
UMAP_CUSTOM_TEMPLATES = "/path/to/custom/templates" UMAP_CUSTOM_TEMPLATES = "/path/to/custom/templates"
See [customization](custom.md) for details. See [customization](customize.md) for details.
#### UMAP_CUSTOM_STATICS #### UMAP_CUSTOM_STATICS
To be used when you want to override some CSS or images: To be used when you want to override some CSS or images:
UMAP_CUSTOM_STATICS = "/path/to/custom/static" UMAP_CUSTOM_STATICS = "/path/to/custom/static"
See [customization](custom.md) for details. See [customization](customize.md) for details.
#### UMAP_EXTRA_URLS #### UMAP_EXTRA_URLS
@ -198,7 +231,27 @@ How many maps to show in the user "my maps" page.
Use it if you take control over the search configuration. Use it if you take control over the search configuration.
See [search](install.md#search) for details. UMap uses PostgreSQL tsvector for searching. In case your database is big, you
may want to add an index. For that, here are the SQL commands to run:
```SQL
# Create a basic search configuration
CREATE TEXT SEARCH CONFIGURATION umapdict (COPY=simple);
# If you also want to deal with accents and case, add this before creating the index
CREATE EXTENSION unaccent;
CREATE EXTENSION btree_gin;
ALTER TEXT SEARCH CONFIGURATION umapdict ALTER MAPPING FOR hword, hword_part, word WITH unaccent, simple;
# Now create the index
CREATE INDEX IF NOT EXISTS search_idx ON umap_map USING GIN(to_tsvector('umapdict', COALESCE(name, ''::character varying)::text), share_status);
```
Then set:
```python title="settings.py"
UMAP_SEARCH_CONFIGURATION = "umapdict"
```
#### UMAP_READONLY #### UMAP_READONLY
@ -208,6 +261,12 @@ Is your instance readonly? Useful for server maintenance.
Should uMap gzip datalayers geojson. Should uMap gzip datalayers geojson.
#### UMAP_XSENDFILE_HEADER
Can be set to `X-Accel-Redirect` to enable the [NGINX X-Accel](https://www.nginx.com/resources/wiki/start/topics/examples/xsendfile/) feature.
See the NGINX documentation in addition.
#### SOCIAL_AUTH_OPENSTREETMAP_KEY, SOCIAL_AUTH_OPENSTREETMAP_SECRET #### SOCIAL_AUTH_OPENSTREETMAP_KEY, SOCIAL_AUTH_OPENSTREETMAP_SECRET
If you use OpenStreetMap as OAuth provider, use those settings. If you use OpenStreetMap as OAuth provider, use those settings.

30
docs/contributing.md
View file

@ -21,11 +21,35 @@ If you've encountered a bug, don't hesitate to tell us about it. The best way to
Following the [installation instructions](install.md) should get you started to hack on the code. Following the [installation instructions](install.md) should get you started to hack on the code.
## Merging rules ### Installing dev dependencies
Pull requests To be sure to install all the dev dependencies, and have everything working locally.
## Update translations ```bash
make develop
```
### Hack!
You can now do your changes in a specific branch, and when you're ready you can open a pull-request for us to review.
### Run tests
Multiple tests suites are in use in the project.
| Test suite | Location | Command |
| ---------- | -------- | ------- |
| Python unit tests | `umap/tests/integration` | `pytest . --ignore umap/tests/integration` |
| Javascript unit tests | `umap/static/test` | `make testjs`|
| Integration tests | `umap/tests/integration` | `pytest umap/tests/integration` |
All the tests are run when you're creating a pull request, to avoid regressions.
### Merging rules
Pull requests need to be accepted by one maintainer of the project. Please be patient, we try to do our best, but it sometimes takes time.
## Update the translations
Install needed tools: Install needed tools:

82
docs/deploy/docker.md
View file

@ -1,12 +1,6 @@
# Docker # Docker
## Docker Hub An official uMap docker image is [available on the docker hub](https://hub.docker.com/r/umap/umap). But, if you prefer to run it with docker compose, here is the configuration file:
An official [uMap docker image](https://hub.docker.com/r/umap/umap) is available on the docker hub.
## Docker compose
If you prefer to run it with docker compose, here is the configuration file:
```yaml title="docker-compose.yml" ```yaml title="docker-compose.yml"
version: '3' version: '3'
@ -41,78 +35,4 @@ services:
volumes: volumes:
umap_userdata: umap_userdata:
umap_db: umap_db:
``` ```
Next, create a basic settings file, named `umap.conf` in the same directory.
You can use this example below and it will run, but you may want to look at the project sample config, using `wget https://raw.githubusercontent.com/umap-project/umap/master/umap/settings/local.py.sample -O /etc/umap/umap.conf` and modify as needed.
Make sure the settings in the docker-compose don't conflict with the sample config and vice-versa. In particular, remove the DATABASES section from the config file if using the docker-compose file, or it will override the DATABASE_URL setting and things won't work.
```python title="umap.conf"
"""
Example settings for docker quickstart: lots of stuff has been removed for simplicity.
You can get the whole list of settings at:
https://umap-project.readthedocs.io/en/master/settings/
Here are the settings YOU HAVE TO CHANGE before launching:
- SECRET_KEY
"""
from umap.settings.base import * # pylint: disable=W0614,W0401
SECRET_KEY = '!!secretsecret!!'
INTERNAL_IPS = ('127.0.0.1', )
ALLOWED_HOSTS = ['*', ]
DEBUG = True
COMPRESS_ENABLED = True
COMPRESS_OFFLINE = True
LANGUAGE_CODE = 'en'
# Set to False if login into django account should not be possible. You can
# administer accounts in the admin interface.
ENABLE_ACCOUNT_LOGIN = True
AUTHENTICATION_BACKENDS = (
'django.contrib.auth.backends.ModelBackend',
)
# Enables a banner letting users know this site is not for production use
UMAP_DEMO_SITE = True
# Whether to allow non authenticated people to create maps.
UMAP_ALLOW_ANONYMOUS = True
```
Some basic settings are available through env vars (see https://github.com/umap-project/umap/blob/master/umap/settings/base.py) and can be defined right in the docker-compose file,
but if you need more custom ones (like custom OAuth configuration), the easiest
way is to put them in a [settings file](settings.md) and mount it to `/etc/umap/umap.conf`.
### Getting started with docker compose
With docker installed on your machine, start the server with
```bash
docker compose up
```
... and let it run some initial setup until the output quiesces with a message about spawning uWSGI workers. Because there is a race between the time the app tries to connect to the DB and when the DB is actually ready, you might see a few exceptions/errors about 'psycopg' being unable to connect. This should sort itself out as the app retries.
Now you need to create your site superuser. Stop the server (Ctrl-C) and then type:
```bash
docker-compose run app /venv/bin/umap createsuperuser
```
Once that's done, you can relaunch your server with `docker compose up`
You should now be able to browse to your uMap instance from a browser on your local system, by pointing your browser to `https://localhost:8001/` (equivalent to `${SITE_URL}` in the docker-compose file, above).
### Administration
To administer the site (add users, change map tiles, other customizations) log in as the root user you just created, then go to `${SITE_URL}/admin`.

121
docs/deploy/nginx.md Normal file
View file

@ -0,0 +1,121 @@
# 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.
```nginx title="nginx.conf"
upstream umap {
server unix:///srv/umap/uwsgi.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;
}
}
```
## 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/uwsgi.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
```nginx title="nginx.conf"
location /static {
autoindex off;
access_log off;
log_not_found off;
sendfile on;
gzip on;
gzip_vary on;
alias /path/to/umap/var/static/;
}
location /uploads {
autoindex off;
sendfile on;
gzip on;
gzip_vary on;
alias /path/to/umap/var/data/;
# Exclude direct acces to geojson, as permissions must be
# checked py django.
location /uploads/datalayer/ { return 404; }
}
```
## X-Accel-Redirect
With this configuration, NGINX will directly serve the geoJSON layers, but uMap will check the permissions.
```title="umap.conf"
UMAP_XSENDFILE_HEADER = 'X-Accel-Redirect'
```
```title="nginx.conf"
location /internal/ {
internal;
gzip_vary on;
gzip_static on;
alias /path/to/umap/var/data/;
}
```

412
docs/deploy/ubuntu.md
View file

@ -1,412 +0,0 @@
# Tutorial
This tutorial will cover an installation from scratch of a uMap instance in an Ubuntu server.
You need sudo grants on this server, and it must be connected to Internet.
## Install system dependencies
``` bash
sudo apt update
sudo apt install python3 python3-dev python3-venv virtualenv wget nginx uwsgi uwsgi-plugin-python3 postgresql gcc postgis libpq-dev
```
!! note
Nginx and uwsgi are not required for local development environment.
## Create deployment directories:
```bash
sudo mkdir -p /etc/umap
```
*You can change this path, but then remember to adapt the other steps accordingly.*
## Create a Unix user
sudo useradd -N umap -m -d /srv/umap/
*Here we use the name `umap`, but this name is up to you. Remember to change it
on the various commands and configuration files if you go with your own.*
## Give umap user access to the config folder
sudo chown umap:users /etc/umap
sudo chown umap:users /srv/umap
## Create a postgresql user
sudo -u postgres -D ~postgres createuser umap
## Create a postgresql database
sudo -u postgres -D ~postgres createdb umap -O umap
## Activate PostGIS extension
sudo -u postgres -D ~postgres psql umap -c "CREATE EXTENSION postgis"
## Login as umap Unix user
sudo -u umap -i
From now on, unless we say differently, the commands are run as `umap` user.
## Create a virtualenv and activate it
virtualenv /srv/umap/venv --python=/usr/bin/python3.10
. /srv/umap/venv/bin/activate
*Note: this activation is not persistent, so if you open a new terminal window,
you will need to run again this last line.*
## Install umap
pip install umap-project
## Create a local configuration file
wget https://raw.githubusercontent.com/umap-project/umap/master/umap/settings/local.py.sample -O /etc/umap/umap.conf
## Customize umap.conf
nano /etc/umap/umap.conf
* update the [SECRET_KEY](settings.md#secret_key)
* update the ADMINS list
## Create the tables
umap migrate
## Collect the statics
umap collectstatic
## Create a superuser
umap createsuperuser
## Start the demo server
umap runserver 0.0.0.0:8000
You can now go to [http://localhost:8000/](http://localhost:8000/) and try to create a map for testing.
When you're done with testing, quit the demo server (type Ctrl+C).
## Configure the HTTP API
Now let's configure a proper HTTP server.
### uWSGI
Create a file named `/srv/umap/uwsgi_params`, with this content
(without making any change on it):
```
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;
```
Then create a configuration file for uWSGI:
nano /srv/umap/uwsgi.ini
And paste this content. Double check paths and user name in case you
have customized some of them during this tutorial. If you followed all the bits of the
tutorial without making any change, you can use it as is:
```
[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/uwsgi.sock
# ... with appropriate permissions - may be needed
chmod-socket = 666
stats = /srv/umap/stats.sock
# clear environment on exit
vacuum = true
plugins = python3
```
### Nginx
Create a new file:
nano /srv/umap/nginx.conf
with this content:
```
# the upstream component nginx needs to connect to
upstream umap {
server unix:///srv/umap/uwsgi.sock;
}
# configuration of the server
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;
}
}
```
Remember to adapt the domain name.
### Activate and restart the services
Now quit the `umap` session, simply by typing Ctrl+D.
You should now be logged in as your normal user, which is sudoer.
- Activate the Nginx configuration file:
sudo ln -s /srv/umap/nginx.conf /etc/nginx/sites-enabled/umap
- Activate the uWSGI configuration file:
sudo ln -s /srv/umap/uwsgi.ini /etc/uwsgi/apps-enabled/umap.ini
- Restart both services:
sudo systemctl restart uwsgi nginx
Now you should access your server through your url and create maps:
http://yourdomain.org/
Congratulations!
- - -
## Troubleshooting
- Nginx logs are in /var/log/nginx/:
sudo tail -f /var/log/nginx/error.log
sudo tail -f /var/log/nginx/access.log
- uWSGI logs are in /var/log/uwsgi:
sudo tail -f /var/log/uwsgi/umap.log
## Before going live
### Add a real SECRET_KEY
In your local.py file, add a real secret and unique `SECRET_KEY`, and do
not share it.
### Remove DEMO flag
In your local.py:
UMAP_DEMO_SITE = False
DEBUG = False
### Configure Nginx to serve statics and uploaded files:
In your nginx config:
location /static {
autoindex off;
access_log off;
log_not_found off;
sendfile on;
gzip on;
gzip_vary on;
alias /path/to/umap/var/static/;
}
location /uploads {
autoindex off;
sendfile on;
gzip on;
gzip_vary on;
alias /path/to/umap/var/data/;
# Exclude direct acces to geojson, as permissions must be
# checked py django.
location /uploads/datalayer/ { return 404; }
}
### Configure social auth
Now you can login with your superuser, but you may allow users to user social
authentication.
### Configure default map center
In your local.py change those settings:
LEAFLET_LONGITUDE = 2
LEAFLET_LATITUDE = 51
LEAFLET_ZOOM = 6
### Activate statics compression
In your local.py, set `COMPRESS_ENABLED = True`, and then run the following command
umap compress
Optionally add `COMPRESS_STORAGE = "compressor.storage.GzipCompressorFileStorage"`
and add `gzip_static on` directive to Nginx `/static` location, so Nginx will
serve pregenerated files instead of compressing them on the fly.
### Configure the site URL and short URL
In your local.py:
SITE_URL = "http://localhost:8019"
SHORT_SITE_URL = "http://s.hort"
Also adapt `ALLOWED_HOSTS` accordingly.
### Configure X-Accel-Redirect
In order to let Nginx serve the layer geojsons but uMap still check the permissions,
you can add this settings:
UMAP_XSENDFILE_HEADER = 'X-Accel-Redirect'
And then add this new location in your nginx config (before the `/` location):
location /internal/ {
internal;
gzip_vary on;
gzip_static on;
alias /path/to/umap/var/data/;
}
### Configure ajax proxy cache
uMap allows to use remote URL as data sources, but those URLs are not always
CORS open, so this is why there is this "ajax-proxy" feature, where the URL is
passed to the backend.
Additionally, there is a caching feature, which duration is configurable through
frontend settings. Valid values are: disabled, 5 min, 1 hour, 1 day.
This configuration provides a mix option, where python deals with validating the
URL and parsing the TTL parameter, and then it passes the hand to nginx which
will serve the remote content.
So, roughly:
- the client calls `/ajax-proxy/?url=xxx&ttl=300`
- python will validate the URL (not internal calls…)
- if `UMAP_XSENDFILE_HEADER` is set, then the python returns an empty response
with the path `/proxy/http://url` plus it will set the cache TTL through the
header `X-Accel-Expires`
- this `/proxy/` location is then handled by nginx
In Nginx:
- add the proxy cache
proxy_cache_path /tmp/nginx_ajax_proxy_cache levels=1:2 keys_zone=ajax_proxy:10m inactive=60m;
proxy_cache_key "$uri$is_args$args";
- add those locations (before the `/` location):
location ~ ^/proxy/(.*) {
internal;
add_header X-Proxy-Cache $upstream_cache_status always;
proxy_cache ajax_proxy;
proxy_cache_valid 1m; # Default. Umap will override using X-Accel-Expires
set $target_url $1;
# URL is encoded, so we need a few hack to clean it back.
if ( $target_url ~ (.+)%3A%2F%2F(.+) ){ # fix :// between scheme and destination
set $target_url $1://$2;
}
if ( $target_url ~ (.+?)%3A(.*) ){ # fix : between destination and port
set $target_url $1:$2;
}
if ( $target_url ~ (.+?)%2F(.*) ){ # fix / after port, the rest will be decoded by proxy_pass
set $target_url $1/$2;
}
resolver 8.8.8.8;
add_header X-Proxy-Target $target_url; # For debugging
proxy_pass_request_headers off;
proxy_set_header Content-Type $http_content_type;
proxy_set_header Content-Encoding $http_content_encoding;
proxy_set_header Content-Length $http_content_length;
proxy_read_timeout 10s;
proxy_connect_timeout 5s;
proxy_pass $target_url;
proxy_intercept_errors on;
error_page 301 302 307 = @handle_proxy_redirect;
}
location @handle_proxy_redirect {
resolver 8.8.8.8;
set $saved_redirect_location '$upstream_http_location';
proxy_pass $saved_redirect_location;
}
## Add more tilelayers, pictograms…
Go to the admin: [http://localhost:8020/admin/](http://localhost:8020/admin/),
and create the objects you want.

12
docs/index.md
View file

@ -2,16 +2,12 @@
!!! info "Developer docs" !!! info "Developer docs"
This documentation is intended for people aiming to install and configure uMap. This documentation is intended for developers or system administrators.
If you are looking for user documentation, have a look at [the OSM wiki page](http://wiki.openstreetmap.org/wiki/UMap#Tutorials). If you are looking for user documentation, have a look at [the OSM wiki page](http://wiki.openstreetmap.org/wiki/UMap#Tutorials).
uMap lets you create maps with OpenStreetMap layers in a minute, and embed them in your site. uMap lets you create maps with OpenStreetMap layers in a minute, and embed them in your site.
If you want to get started, follow the [installation](install.md) guide. - 🤗 Get started and [follow the installation guide](install.md).
- 🤩 Want to contribute? [Read the contributing guidelines](contributing.md).
You might want to: - 🤔 Curious about umap internals? [Check the architecture overview](architecture/overview.md).
- See [the developer docs](developer.md)
- Read [the contributing guidelines](contributing.md)
- Read through the [deployment tips](deploy/tips.md)

63
docs/install.md
View file

@ -1,13 +1,5 @@
# Installation # Installation
!!! info "Specific guides"
This page covers how to get started with uMap. If you plan on deploying the service on a server for other people to consume, you can follow different tutorials:
- [Deploying uMap on Ubuntu](deploy/ubuntu.md) (from scratch)
- [Deploying uMap using Docker](deploy/docker.md)
- Recent Windows distribution provide [WSL 2](https://learn.microsoft.com/en-us/windows/wsl/install), which makes it possible to run a Linux distribution of your choice.
## System dependencies ## System dependencies
uMap is built with the [Python](https://python.org) language, and the [Django](https://djangoproject.com) framework. It needs a [PostgreSQL](https://www.postgresql.org/) database, with the [Postgis](https://postgis.net/) extension enabled. uMap is built with the [Python](https://python.org) language, and the [Django](https://djangoproject.com) framework. It needs a [PostgreSQL](https://www.postgresql.org/) database, with the [Postgis](https://postgis.net/) extension enabled.
@ -85,7 +77,7 @@ export UMAP_SETTINGS=`pwd`/local_settings.py
Add database connection information in `local_settings.py`, for example Add database connection information in `local_settings.py`, for example
```python ```python title="local_settings.py"
DATABASES = { DATABASES = {
'default': { 'default': {
'ENGINE': 'django.contrib.gis.db.backends.postgis', 'ENGINE': 'django.contrib.gis.db.backends.postgis',
@ -98,7 +90,7 @@ Depending on your installation, you might need to change the user that connects
It should look like this: It should look like this:
```python ```python title="local_settings.py"
DATABASES = { DATABASES = {
"default": { "default": {
"ENGINE": "django.contrib.gis.db.backends.postgis", "ENGINE": "django.contrib.gis.db.backends.postgis",
@ -110,7 +102,7 @@ DATABASES = {
Add a `SECRET_KEY` in `local_settings.py` with a long random secret key Add a `SECRET_KEY` in `local_settings.py` with a long random secret key
```python ```title="local_settings.py"
SECRET_KEY = "a long and random secret key that must not be shared" SECRET_KEY = "a long and random secret key that must not be shared"
``` ```
@ -122,7 +114,7 @@ openssl rand -base64 32
uMap uses [python-social-auth](http://python-social-auth.readthedocs.org/) for user authentication. So you will need to configure it according to your needs. For example uMap uses [python-social-auth](http://python-social-auth.readthedocs.org/) for user authentication. So you will need to configure it according to your needs. For example
```python ```title="local_settings.py"
AUTHENTICATION_BACKENDS = ( AUTHENTICATION_BACKENDS = (
'social_auth.backends.contrib.github.GithubBackend', 'social_auth.backends.contrib.github.GithubBackend',
'social_auth.backends.contrib.bitbucket.BitbucketBackend', 'social_auth.backends.contrib.bitbucket.BitbucketBackend',
@ -162,49 +154,10 @@ umap createsuperuser
umap runserver 0.0.0.0:8000 umap runserver 0.0.0.0:8000
``` ```
## Configuring PostgreSQL search
UMap uses PostgreSQL tsvector for searching. In case your database is big, you
may want to add an index. For that, here are the SQL commands to run:
```SQL
# Create a basic search configuration
CREATE TEXT SEARCH CONFIGURATION umapdict (COPY=simple);
# If you also want to deal with accents and case, add this before creating the index
CREATE EXTENSION unaccent;
CREATE EXTENSION btree_gin;
ALTER TEXT SEARCH CONFIGURATION umapdict ALTER MAPPING FOR hword, hword_part, word WITH unaccent, simple;
# Now create the index
CREATE INDEX IF NOT EXISTS search_idx ON umap_map USING GIN(to_tsvector('umapdict', COALESCE(name, ''::character varying)::text), share_status);
```
And change your settings:
```python
UMAP_SEARCH_CONFIGURATION = "umapdict"
```
## Configuring emails ## Configuring emails
UMap can send the anonymous edit link by email. For this to work, you need to UMap can send the anonymous edit link by email. For this to work, you need to
add email specific settings. See [Django](https://docs.djangoproject.com/en/4.2/topics/email/#smtp-backend) add email specific settings. See [the related settings](config/settings.md#email_backend) for more info.
documentation.
In general, you'll need to add something like this in your local settings:
```python
FROM_EMAIL = "youradmin@email.org"
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "smtp.provider.org"
EMAIL_PORT = 456
EMAIL_HOST_USER = "username"
EMAIL_HOST_PASSWORD = "xxxx"
EMAIL_USE_TLS = True
# or
EMAIL_USE_SSL = True
```
## Upgrading your installation ## Upgrading your installation
@ -216,9 +169,3 @@ umap migrate
umap collectstatic umap collectstatic
umap compress umap compress
``` ```
Then you need to restart your python server, for example:
```bash
sudo systemctl restart uwsgi # or gunicorn, or…
```

3
docs/stylesheets/extra.css
View file

@ -1,3 +1,6 @@
:root { :root {
--md-primary-fg-color: #323e56; --md-primary-fg-color: #323e56;
} }
.md-typeset a {
color: #7990be !important;
}

25
mkdocs.yml
View file

@ -1,24 +1,26 @@
site_name: uMap site_name: uMap docs
site_description: uMap lets you create maps with OpenStreetMap layers in a minute and embed them in your site site_description: uMap lets you create maps with OpenStreetMap layers in a minute and embed them in your site
repo_name: umap-project/umap repo_name: umap-project/umap
repo_url: https://github.com/umap-project/umap repo_url: https://github.com/umap-project/umap
nav: nav:
- Home: index.md - How-tos:
- Installation: install.md - Getting started: install.md
- Contribute: contributing.md
- Architecture: - Architecture:
- Frontend (JS): architecture/frontend.md - Overview: architecture/overview.md
- Frontend: architecture/frontend.md
- Configuration:
- Settings: config/settings.md
- Customize: config/customize.md
- Icon packs: config/icons.md
- Deployment: - Deployment:
- Ubuntu Server Howto: deploy/ubuntu.md
- Docker: deploy/docker.md - Docker: deploy/docker.md
- Windows: deploy/windows.md - Nginx: deploy/nginx.md
- Configuration: settings.md
- Administration: administration.md
- Contributing: contributing.md
- how-tos:
- Customize your uMap style: custom.md
- Changelog: changelog.md - Changelog: changelog.md
theme: theme:
name: material name: material
logo: assets/logo.svg
homepage: https://umap-project.org
palette: palette:
- scheme: 'default' - scheme: 'default'
media: '(prefers-color-scheme: light)' media: '(prefers-color-scheme: light)'
@ -34,6 +36,7 @@ theme:
name: 'Switch to light mode' name: 'Switch to light mode'
features: features:
- navigation.sections - navigation.sections
- navigation.footer
extra_css: extra_css:
- stylesheets/extra.css - stylesheets/extra.css
markdown_extensions: markdown_extensions: