# Configuration

Most of the configuration takes place over environment variables. These can be passed to applications in so many ways, it's worth expanding a little on that below.

**Note**, the PostgreSQL related variables are named the same as in Kartoza's excellent [PostGIS image](https://github.com/kartoza/docker-postgis) which we highly recommend.

## Places to look for configuration

Flask applications are most often configured globally by a root `config.py` file. Configuration parameters are usually taken from environment variables, but also have sensible defaults in `config.py`.

#### `.flaskenv`

This is only relevant for Flask and points only to the app module.

#### `.env`

As many frameworks, Flask supports the `dotenv` strategy, i.e. placing all variables in a root `.env` file, which is automatically read on app startup and used to configure the project.

Normally those files are excluded from version control. We decided to include one in this project.

**Note**, also `docker-compose` reads `.env` files by default so one can use it to parameterize the `docker-compose.yml` file (but **not to pass environment variables to containers**).

#### `.docker_env`

It's a similar concept as `.env` only that there's no auto-magic happening and needs to be explicitly passed.

The `.docker_env` file is targeted at the `docker-compose` approach and should be used to configure the project when using the [docker installation](https://github.com/gis-ops/routing-graph-packager/wiki/Installation#docker-installation). The main reason for its existence is that the database hosts need to be named like the docker service names.

## Variables

### Important notes

There are some inter-dependencies in the setup of the configuration variables:

**`DATA_DIR`**: This directory will be used to
- store the PBF files in the `osm`, `tomtom`, `here` subdirectories
- store the graph packages in subdirectories (named after the routing engine)
- store temporary files create while generating the graphs (and mostly be removed by the end of a _successful_ operation)

**`ENABLED_ROUTERS`**: All routing engine names specified here are expected to have the corresponding docker image on the host, which you can tweak with the `<ROUTER>_<IMAGE` environment variables. E.g. `valhalla,osrm` checks if the `VALHALLA_IMAGE` and `OSRM_IMAGE` are locally available.

**`ENABLED_PROVIDERS`**: All providers specified here need the corresponding PBF directory in `DATA_DIR` (with at least one PBF file). E.g. `osm,tomtom` checks if the `$DATA_DIR/osm` and `$DATA_DIR/tomtom` directories exist and contain at least one PBF file.

### Complete list

For an overview over configuration variables, types and their meaning, see the following table:

| Variable            | Type | Description                                                                                                                       |
|---------------------|------|-----------------------------------------------------------------------------------------------------------------------------------|
| **FLASK**           |      |                                                                                                                                   |
| `FLASK_ENV`         | str  | Determines the Flask environment, see the [official documentation](https://flask.palletsprojects.com/en/1.1.x/config/).           |
| `SECRET_KEY`        | str  | The Flask secret. Even though there's a default, it's **strongly recommended to change this**.                                        |
| `FLASK_CONFIG`      | str  | Controls the app-specific environment, one of `production`, `development`, `testing`. Default `production`.                             |
| **APP**             |      |                                                                                                                                   |
| `DATA_DIR`          | str  | The directory where the routing packages will be generated. Also the directory where the PBF files are expected. Default `./data`. |
| `OSM_PBF`           | str  | The name of the OSM PBF file which will be used to cut the extracts. It needs to reside in `DATA_DIR`. Default `andorra-latest.osm.pbf`. |
| `TOMTOM_PBF`        | str  | The name of the TomTom PBF file (if any) which will be used to cut the extracts. It needs to reside in `DATA_DIR`. Default `andorra-latest.tomtom.pbf`. |
| `HERE_PBF`          | str  | The name of the HERE PBF file (if any) which will be used to cut the extracts. It needs to reside in `DATA_DIR`. Default `andorra-latest.here.pbf`. |
| `ENABLED_ROUTERS`   | str  | The routing engines to enable as a comma-delimited string, e.g. `valhalla,openrouteservice,osrm,graphhopper` (see [README](https://github.com/gis-ops/routing-graph-packager) for up-to-date list of available routing engines). Default `valhalla`. |
| `ENABLED_PROVIDERS` | str  | The data providers to enable as a comma-delimited string, e.g. `osm,tomtom,here`. Default `osm`.                                  |
| `ADMIN_EMAIL`       | str  | The email address of the admin user. Acts as user name. Default `admin@example.org`.                                               |
| `ADMIN_PASSWORD`    | str  | The password of the admin user. Default `admin`.                                                                                   |
| `VALHALLA_IMAGE`    | str  | The Valhalla docker image to use in the graph generation. Default `gisops/valhalla:latest`.                                         |  
| `OSRM_IMAGE`        | str  | The OSRM docker image to use in the graph generation. Default `osrm/osrm-backend:latest`.                                         |  
| `GRAPHHOPPER_IMAGE` | str  | The Graphhopper docker image to use in the graph generation. Default `graphhopper/graphhopper:latest`.                                         |  
| `ORS_IMAGE`         | str  | The OpenRouteService docker image to use in the graph generation. Default `openrouteservice/openrouteservice:latest`.                                         |     
| **DATABASES**       |      |                                                                                                                                   |
| `POSTGRES_HOST`     | str  | The host of your PostgreSQL installation, e.g. IP, `localhost` or `postgis.example.org`. Default `localhost`.                                  |
| `POSTGRES_PORT`     | int  | The port of your PostgreSQL installation. Default `5432`.                                                                           |
| `POSTGRES_DB`       | str  | The name of the **existing** database to use. Default `gis`.                                                                      |
| `POSTGRES_USER`     | str  | The admin user of the **existing** database. Default `admin`.                                                                     |
| `POSTGRES_PASS`     | str  | The admin password of the **existing** database. Default `admin`.                                                                 |
| `REDIS_URL`         | str  | The Redis URL as db string, e.g. `redis://<host:port>/<database>`. Default `redis://localhost:6379/0`.                                                                 |
| **SMTP**            |      |                                                                                                                                   |
| `SMTP_HOST`         | str  | The host name for the SMTP server, e.g. `smtp.gmail.com`. Default `localhost`.                                                    |
| `SMTP_PORT`         | int  | The port for the SMTP server. Default `1025`.                                                                                         |
| `SMTP_USER`         | str  | The user name for the email account. If omitted, no authentication will be attempted.                                             |
| `SMTP_PASS`         | str  | The password for the email account. If omitted, no authentication will be attempted.                                              |
| `SMTP_SECURE`       | bool | Whether TLS should be used to secure the email communication, `True` or `False` Default `False`.                                  |                                                                  |