Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hotosm/tasking-manager/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through spinning up a complete HOT Tasking Manager stack — PostgreSQL/PostGIS database, FastAPI backend, and React frontend — on your local machine using Docker Compose. By the end you will have a running instance, an interactive API explorer, and you will know how to authenticate API requests with your own token.
1

Install Docker Engine

HOT Tasking Manager ships as a fully containerised application. The only prerequisite is Docker Engine (which includes Docker Compose v2). Verify your installation:
docker --version
docker compose version
Both commands should return version strings without errors.
2

Clone the Repository

Clone the official GitHub repository and change into the project directory:
git clone https://github.com/hotosm/tasking-manager.git
cd tasking-manager
3

Copy the Environment File

The repository ships with a fully-documented example environment file. Copy it to the name the application expects:
cp example.env tasking-manager.env
The new file contains sensible defaults for local development. The sections below walk through the values you must set before starting the stack.
4

Register an OSM OAuth2 Application

Tasking Manager uses OpenStreetMap’s OAuth 2.0 system for user authentication. You need to register a developer application on openstreetmap.org to obtain credentials.
  1. Log in to openstreetmap.org (create a free account if you do not have one).
  2. Open the dropdown on the top-right of the navigation bar and select My Settings.
  3. Navigate to OAuth 2 applications and click Register new application.
  4. Fill in the form:
    • Name: anything descriptive, e.g. Tasking Manager Local Dev
    • Redirect URIs: http://127.0.0.1:3000/authorized
    • Permissions: enable Read user preferences (read_prefs) and Modify the map (write_api)
  5. Submit the form and copy the Client ID and Client Secret that are shown.
You must use http://127.0.0.1:3000/authorized as the redirect URI — not localhost. OpenStreetMap’s OAuth2 implementation requires the literal IP address 127.0.0.1 for local development.
Open tasking-manager.env and set the three OAuth variables:
TM_CLIENT_ID=<your-client-id-from-osm>
TM_CLIENT_SECRET=<your-client-secret-from-osm>
TM_REDIRECT_URI=http://127.0.0.1:3000/authorized
5

Start the Stack

With the environment file configured, bring up all services (database, migration runner, backend API, cron jobs, frontend, and Traefik reverse proxy) in detached mode:
docker compose --env-file tasking-manager.env up -d
Docker will pull the pre-built images on the first run. The database migration container (tm-migration) runs automatically before the backend starts. You can follow the logs while everything initialises:
docker compose logs -f
Wait until you see the backend report that it is healthy (the tm-backend healthcheck polls /api/docs).
6

Open the Frontend

Once all containers are healthy, open your browser and navigate to:
http://127.0.0.1:3000
You will see the Tasking Manager home page. Click Log in in the top-right corner to authenticate via OpenStreetMap OAuth2 using the application you registered in Step 4.
7

Explore the Interactive API Docs

The FastAPI backend serves a Swagger UI at:
http://127.0.0.1:3000/api/docs
Every endpoint is documented with request/response schemas and can be exercised directly from the browser. The raw OpenAPI JSON schema is available at http://127.0.0.1:3000/api/openapi.json.
8

Make Your First API Call

The system statistics endpoint requires no authentication and returns aggregate project and mapping statistics — a useful smoke-test to confirm the stack is healthy end-to-end:
curl http://127.0.0.1:3000/api/v2/system/statistics/
A successful response looks like:
{
  "totalProjects": 42,
  "totalMappers": 1200,
  "totalTasks": 18500,
  "totalMappedTasks": 12300,
  "totalValidatedTasks": 8900,
  "totalTimeSpentMapping": 3456789,
  "totalTimeSpentValidating": 1234567
}
You can also hit the heartbeat endpoint to verify the backend process itself is alive:
curl http://127.0.0.1:3000/api/v2/system/heartbeat/

{
  "status": "Fastapi healthy",
  "release": {
    "version": "v5.5.0",
    "published_at": "2026-01-15T10:00:00"
  }
}
9

Obtain an API Token for Authenticated Requests

Many API endpoints require an Authorization header. The easiest way to obtain your personal API token is through the browser:
  1. Log in to your local instance at http://127.0.0.1:3000.
  2. Click your username in the top-right corner to open your profile.
  3. Go to Settings and enable Expert Mode.
  4. Scroll to the API Key section and copy the token displayed there.
Pass the token in subsequent curl requests using the Token scheme:
curl http://127.0.0.1:3000/api/v2/projects/ \
  -H "Authorization: Token <your-api-key>"
You can also pass it in the Swagger UI: click Authorize at the top of the /api/docs page and enter Token <your-api-key>.
Frontend-only development? If you only want to work on the React UI and do not need a local backend, point the frontend at the HOT staging API instead of running the full stack. In tasking-manager.env, set:
TM_APP_API_URL=https://tasking-manager-staging-api.hotosm.org
Then start only the frontend service:
docker compose --env-file tasking-manager.env up -d tm-frontend
Be aware that the staging API may be temporarily unavailable during HOT deployments and that some administrative views may be inaccessible due to permissions.

​
What’s Next?

Development Setup

Configure the React frontend and FastAPI backend as standalone processes for a full local development workflow.

API Overview

Learn about the REST API structure, authentication model, and key endpoint groups.

Build docs developers (and LLMs) love

Get started for freeTalk to us