The HOT Tasking Manager helps you set up mapping projects and tasks for your mapping team. The Tasking Manager hosted on HOT infrastructure is available at https://tasks.hotosm.org/.

Use this repository, to set up your own instance of the tasking manager with customised member permissions and personalised mapping projects.

• Come, attend the working group meetings
• Review our roadmap
• Review our Contributor guidelines
• Feel free to submit pull requests to this repository!

The Tasking Manager is composed of two parts:

• Client: A front-end user interface built using AngularJS.
• Server: A back-end database and API built using python3.

The two parts can be developed independently of each other.

The client is the front-end user interface of the Tasking Manager. If you're interested in developing the client alone, you can build it using gulp, without having to worry about the server set up. You can point the client at a non-local API url (e.g. a staging environment), by changing the environment in client/taskingmanager.config.json. All the files pertaining to the client are available in the client/ directory.

Dependencies

The following dependencies must be available globally on your system:

• Download and install NodeJS LTS v6+ and NPM
• Install Gulp.
  • npm install gulp -g
• Install Karma
  • npm install -g karma karma-jasmine karma-chrome-launcher

Build

Once you have the above dependencies, install and run the client dependencies using npm and gulp

cd client
npm install
gulp build

Run

Once you've built the dependencies, run the client using

cd client
gulp run

Tests

The client has a suite of Jasmine Unit Tests. These can be run using Karma as follows

 cd client
 karma start ../tests/client/karma.conf.js

The backend server is made up of a postgres database and an associated API that calls various end points to create tasks, manage task state, and produce analytics.

Dependencies

• Python 3.6+
  • Note: The project does not work with Python 2.x. You will need Python 3.6+
• postgreSQL with postGIS
• pip

Get secrets from OpenStreetMap

Since the tasking manager works with OpenStreetMap credentials, register your local tasking manager application on OpenStreetMap to allow logins.

• Go to https://www.openstreetmap.org/user/<Your_OSM_UserName>/oauth_clients/new, and fill in the following information.

• Once registered, you should get a Consumer Key and Consumer Secret. Use these values for the TM_CONSUMER_KEY and TM_CONSUMER_SECRET environment variables below.

Environment

Set up the following environment variables to configure your local tasking manager instance(Required variables are in bold):

export TM_DB=postgresql://USER:PASSWORD@HOST/DATABASE
export TM_SECRET=secret-key-here
export TM_CONSUMER_KEY=oauth-consumer-key-goes-here
export TM_CONSUMER_SECRET=oauth-consumer-secret-key-goes-here
export TM_SMTP_HOST=smtp-server-host-here
export TM_SMTP_PORT=smtp-server-port-here
export TM_SMTP_USER=smtp-server-user-here
export TM_SMTP_PASSWORD=smtp-server-password-here

setx TM_DB "postgresql://USER:PASSWORD@HOST/DATABASE"
setx TM_SECRET "secret-key-here"
setx TM_CONSUMER_KEY "oauth-consumer-key-goes-here"
setx TM_CONSUMER_SECRET "oauth-consumer-secret-key-goes-here"
setx TM_SMTP_HOST "smtp-server-host-here"
setx TM_SMTP_PORT "smtp-server-port-here"
setx TM_SMTP_USER "smtp-server-user-here"
setx TM_SMTP_PASSWORD "smtp-server-password-here"

Build

• Create a Python Virtual Environment, using Python 3.6:
  • python3 -m venv ./venv
• Activate your virtual environment and install dependencies:
  • Linux/Mac:
    • . ./venv/bin/activate
    • pip install -r requirements.txt
  • Windows (use installer because of precompiled libs):
    • .\venv\scripts\activate
    • .\devops\win\install.bat

Tests

The project includes a suite of Unit and Integration tests that you should run after any changes

python -m unittest discover tests/server

Create a fresh database

We use Flask-Migrate to create the database from the migrations directory. If you can't access an existing DB refer to DevOps page to set up a local DB in Docker create the database as follows

python3 manage.py db upgrade

Migrating your data from TM2

You can use this script to migrate your data from the prior tasking manager version (v2) to the current one. Please see this wiki page for important information about this process.

Set permissions to create a task

To be able to create a task and have full permissions as an admin inside TM, login to the TM with your OSM account to populate your user information in the database, then execute the following command on your terminal (with the OS user that is the owner of the database):

psql -d <your_database> -c "UPDATE users set role = 1 where username = '<your_osm_username>'"

If you plan to only work on the API you only have to build the server architecture. Install the server dependencies, and run these commands:

• Run the server:
  • python manage.py runserver -d -r
• Point your browser to:
  • http://localhost:5000/api-docs

If you encounter any issues while setting up a dev environment, please visit our FAQ ❓ page to find possible solutions.

Go to the Transifex repository to translate the tasking Manager to your language.

We keep track of issues we troubleshoot during the installation at https://github.com/hotosm/tasking-manager/wiki/Dev-Environment-FAQ. Please feel free to extend this document with additional issues you find.

In addition to this README, you might want to check the Tasking Manager Wiki