Deploying uMap with Dokku⚓︎
You must have a Dokku host up and running. This can be either self hosted, or from a provider.
To set up Dokku on your own server, see https://dokku.com/docs/getting-started/installation/
Dokku has several deployment methods, in this guide we'll use the Docker based one, using our maintained Dockerfile.
Installation⚓︎
Prepare the host⚓︎
We need postgres and redis plugins:
sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git --name postgres
sudo dokku plugin:install https://github.com/dokku/dokku-redis.git --name redis
Note: if you do not use the real time collaboration feature, you can skip the redis part.
Create the umap app (or name it as you prefer), and postgis and redis services:
dokku apps:create umap
dokku postgres:create umap --image "postgis/postgis" --image-version "18-3.6-alpine"
dokku postgres:link umap umap
dokku redis:create umap
dokku redis:link umap umap
Create a folder for user data (mainly layers), static files and the ajax proxy cache:
sudo mkdir /var/lib/dokku/data/storage/umap-data
dokku storage:mount umap /var/lib/dokku/data/storage/umap-data:/srv/umap/uploads
sudo mkdir /var/lib/dokku/data/storage/umap-static
dokku storage:mount umap /var/lib/dokku/data/storage/umap-static:/srv/umap/static
sudo mkdir /var/lib/dokku/data/storage/umap-proxy-cache
dokku storage:mount umap /var/lib/dokku/data/storage/umap-proxy-cache:/srv/umap/proxy-cache
The proxy cache is never purged automatically, so schedule its cleanup, for example in the host crontab:
0 3 * * * dokku run umap umap clear_proxy_cache
See AJAX_PROXY_CACHE_DIR.
Expose the app to the Internet and add a SSL certificate:
dokku domains:set-global dokku.yourdoma.in
dokku config:set umap CSRF_TRUSTED_ORIGINS=https://umap.dokku.yourdoma.in
dokku ports:set umap http:80:8000
sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git
dokku letsencrypt:enable umap
dokku letsencrypt:cron-job --add
Note: we are using Letsencrypt here, see Dokku's doc for a custom certificate.
Configure via env vars:
dokku config:set --no-restart umap SECRET_KEY=something-random-and-unique
dokku config:set --no-restart umap AJAX_PROXY_CACHE_DIR=/srv/umap/proxy-cache
dokku config:set --no-restart umap SOCIAL_AUTH_REDIRECT_IS_HTTPS=1
Nginx configuration⚓︎
Nginx configuration for uMap is a bit tricky, and we don't want to replace the nginx conf managed by Dokku, so it requires some manual changes.
Some changes need to be added to the http section of the nginx conf.
Create a file at /etc/nginx/conf.d/umap-http.conf with this content:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
Other need to be integrated in the server section.
So, create a file at /home/dokku/umap/nginx.conf.d/umap.conf, pointing to
the volumes created above:
sudo -u dokku mkdir -p /home/dokku/umap/nginx.conf.d
sudo -u dokku tee /home/dokku/umap/nginx.conf.d/umap.conf <<'EOF'
location /static/ {
alias /var/lib/dokku/data/storage/umap-static/;
gzip on;
gzip_vary on;
gzip_proxied any;
gzip_types text/plain application/javascript application/x-javascript text/javascript text/xml text/css;
expires 365d;
access_log /dev/null;
}
location /uploads/ {
alias /var/lib/dokku/data/storage/umap-data/;
expires 30d;
}
location /favicon.ico {
alias /var/lib/dokku/data/storage/umap-static/favicon.ico;
}
location /internal/ {
internal;
gzip_vary on;
gzip_static on;
add_header X-DataLayer-Version $upstream_http_x_datalayer_version;
alias /var/lib/dokku/data/storage/umap-data/;
}
EOF
sudo nginx -t && sudo systemctl reload nginx
To increase the upload max size (1M by default):
dokku nginx:set umap client-max-body-size 50m
dokku proxy:build-config umap
OAuth configuration⚓︎
As an example, we'll use OpenStreetMap OAuth, but it's possible to use whatever service supported by python-social-auth.
You need to create an OAuth client here:
https://www.openstreetmap.org/oauth2/applications
The redirect URL should look like:
https://umap.dokku.yourdoma.in/complete/openstreetmap-oauth2/
You must select Read user preferences and Sign in using OpenStreetMap permissions.
And get the client key and secret and set them in Dokku like this:
dokku config:set --no-restart umap SOCIAL_AUTH_OPENSTREETMAP_OAUTH2_KEY=somekey
dokku config:set umap SOCIAL_AUTH_OPENSTREETMAP_OAUTH2_SECRET=somesecret
More settings⚓︎
If you want real time collaboration:
dokku config:set umap REALTIME_ENABLED=1
If you want to control whether anonymous users can create maps:
dokku config:set umap UMAP_ALLOW_ANONYMOUS=0/1
See settings.
On your local machine⚓︎
To deploy, you need to clone umap locally, and push to Dokku, just like you'd push to github or the like.
On uMap git repository, add a remote (here name dokku, but it's up to you)
and push there the master branch (or whatever branch you want):
git remote add dokku dokku@yourdokku.com:yourproject
git push dokku master
Troubleshooting⚓︎
See the logs, on the host:
dokku logs umap
Start a shell session on the umap Docker container:
dokku enter umap