umap/docs/install.md

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.

=== "Debian"

```bash
sudo apt update
sudo apt install python3 python3-dev python3-venv virtualenv postgresql gcc postgis libpq-dev
``` 

=== "Arch Linux" bash yay postgis extra/postgresql-libs

=== "OS X (with brew)"

```bash
brew install postgis
```

=== "Fedora"

```bash
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 and compress static files
umap collectstatic
umap compress

# 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
umap compress