Installation⚓︎
System dependencies⚓︎
uMap is built with the Python language, and the Django framework. It needs a PostgreSQL database, with the Postgis extension enabled.
Here are the commands to install the required system dependencies.
sudo apt update
sudo apt install python3 python3-dev python3-venv virtualenv postgresql gcc postgis libpq-dev
yay postgis extra/postgresql-libs
brew install postgis
sudo dnf install postgis libpq-devel make gcc python3-devel
PostgreSQL⚓︎
Depending on your system, you might need to create a postgres user, the database, and initialize postgres. Here's how:
createuser umap -U postgres
createdb umap -O umap -U postgres
psql umap -c "CREATE EXTENSION postgis" -Upostgres
Getting started⚓︎
Create a geo aware database. See the GeoDjango docs for backend installation.
Creating a virtual environment⚓︎
It is recommended to install python projects in a virtual environment to avoid mixing the project installation with your system dependencies. But it's not a requirement and it is up to you 🫣
python -m venv venv
source venv/bin/activate
Installing the dependencies⚓︎
You can get all the project dependencies installed with the following command:
pip install umap-project
Configuration⚓︎
Create a default local_settings.py
file, that you will modify with your setting.
wget https://raw.githubusercontent.com/umap-project/umap/master/umap/settings/local.py.sample -O local_settings.py
Reference it as env var:
export UMAP_SETTINGS=`pwd`/local_settings.py
Add database connection information in local_settings.py
, for example
DATABASES = {
'default': {
'ENGINE': 'django.contrib.gis.db.backends.postgis',
'NAME': 'umap',
}
}
Depending on your installation, you might need to change the user that connects the database.
It should look like this:
DATABASES = {
"default": {
"ENGINE": "django.contrib.gis.db.backends.postgis",
"NAME": "umap",
"USER": "postgres",
}
}
Add a SECRET_KEY
in local_settings.py
with a long random secret key
SECRET_KEY = "a long and random secret key that must not be shared"
You can easily generate one with openssl:
openssl rand -base64 32
uMap uses python-social-auth for user authentication. So you will need to configure it according to your needs. For example
AUTHENTICATION_BACKENDS = (
'social_auth.backends.contrib.github.GithubBackend',
'social_auth.backends.contrib.bitbucket.BitbucketBackend',
'social_auth.backends.twitter.TwitterBackend',
'django.contrib.auth.backends.ModelBackend',
)
GITHUB_APP_ID = 'xxx'
GITHUB_API_SECRET = 'zzz'
BITBUCKET_CONSUMER_KEY = 'xxx'
BITBUCKET_CONSUMER_SECRET = 'zzz'
TWITTER_CONSUMER_KEY = "xxx"
TWITTER_CONSUMER_SECRET = "yyy"
Example of callback URL to use for setting up OAuth apps
http://umap.foo.bar/complete/github/
Adapt the STATIC_ROOT
and MEDIA_ROOT
to your local environment.
Bootstrapping the database⚓︎
Here are the commands you'll need to run to create the tables, collect the static files, etc.
# Create the database tables
umap migrate
# Collect static files
umap collectstatic
# Create a super user
umap createsuperuser
# Finally start the server
umap runserver 0.0.0.0:8000
Configuring emails⚓︎
UMap can send the anonymous edit link by email. For this to work, you need to add email specific settings. See the related settings for more info.
Upgrading your installation⚓︎
Usually, for upgrading, you need those steps:
pip install umap-project --upgrade
umap migrate
umap collectstatic