# Installation ## 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. 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: ```bash 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](https://docs.djangoproject.com/en/dev/ref/contrib/gis/install/) 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 🫣 ```bash python -m venv venv source venv/bin/activate ``` ### Installing the dependencies You can get all the project dependencies installed with the following command: ```bash pip install umap-project ``` ### Configuration Create a default `local_settings.py` file, that you will modify with your setting. ```bash wget https://raw.githubusercontent.com/umap-project/umap/master/umap/settings/local.py.sample -O local_settings.py ``` Reference it as env var: ```bash export UMAP_SETTINGS=`pwd`/local_settings.py ``` Add database connection information in `local_settings.py`, for example ```python title="local_settings.py" 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: ```python title="local_settings.py" 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 ```title="local_settings.py" SECRET_KEY = "a long and random secret key that must not be shared" ``` You can easily generate one with [openssl](https://www.openssl.org/): ```bash 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 ```title="local_settings.py" 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. ```bash # 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](config/settings.md#email_backend) for more info. ## Upgrading your installation Usually, for upgrading, you need those steps: ```bash pip install umap-project --upgrade umap migrate umap collectstatic ```