Skip to content

Getting started

This guide starts the complete CHART development environment on your computer.

Requirements

Install these before continuing:

  • Docker Desktop, with the Docker engine running
  • Node.js 22 and npm
  • Python 3.11
  • Git

uv is optional. When it is installed, the Makefile uses it to create and populate the Python environment more quickly.

Install CHART

From a terminal:

git clone https://github.com/CHART-Scope/CHART.git
cd CHART
make install

If you already have the repository, update it and run make install from the repository root.

Start the application

make run

The first run starts the local infrastructure, applies database migrations, loads seed data, and starts the web, API, and Dagster processes. Keep this terminal open while using CHART.

After startup, open the service you need:

Service Local address
CHART web application http://127.0.0.1:3100
CHART API documentation http://127.0.0.1:3210/docs
Dagster http://127.0.0.1:3002
Keycloak http://127.0.0.1:8080
Mailpit inbox (sign-in codes, see sign-in) http://127.0.0.1:8025

These are local addresses

Addresses beginning with 127.0.0.1 only work on the computer running CHART, and only while the relevant service is running. They are shown as text rather than public links for that reason.

Verify the setup

Check that the Python API is healthy:

curl http://127.0.0.1:3210/health

The response should be:

{"status":"ok"}

Then open the CHART web application at http://127.0.0.1:3100.

Complete installation setup

A fresh installation has no users, workspaces, or geographies configured. The web application redirects to /onboarding and walks you through a four-step wizard: country, administrative area, sector and collaborators, and the first administrator account. Sign in with the administrator credentials once the wizard finishes.

The wizard, reset flow, and troubleshooting for stuck bootstraps are covered in Installation setup.

Load climate history

The dashboard reads observed climate and observed estimates from the database; it does not fetch them when a place is opened. After installation setup, load the history once for each country you use, with make run still running:

make climate-backfill COUNTRY=IN YEARS=2

This fills every place the model configuration lists for the country (its state, divisions and districts; for Kenya the country, counties and constituencies) from January YEARS years ago to the newest month ERA5 has published. It also stores India's observed estimates for every modelled area and month. Two years is enough to try CHART; use 5, 10 or 20 for planning work. Running it again with more years only downloads the years it adds, and make climate-verify COUNTRY=IN YEARS=2 lists any place still missing a month.

Grids are read from CHART's public mirror when it holds them; otherwise they come from the Copernicus Climate Data Store, which needs a free account and its API key in ~/.cdsapirc (how to). Measured on the sandbox, two years for India took 28 minutes and needed about 200 MB; twenty years for both countries about six hours and 2.2 GB (ERA5 cache plus database). Times are mostly Copernicus queue time. After that, the six-hourly top-up keeps the newest months current. Architecture, timings and storage: Observed climate data.

Climate pipeline only

To work on the climate data path without starting the complete web application:

make migrate
PRESET=madhya-pradesh make climate-materialize
make dev

make dev keeps Dagster running at http://127.0.0.1:3002. In another terminal, start the Python API:

make climate-api

Documentation only

To preview this documentation site locally:

make install
make docs-serve

The preview is available at http://127.0.0.1:8000.

Common startup problems

Docker is not running

Start Docker Desktop, wait for the Docker engine to become ready, and run make run again.

Port 8080 is already in use

CHART uses port 8080 for Keycloak. Stop the other local application or container using that port, then run make run again. The startup command reports the name of a conflicting Docker container when it can.

A service stopped during startup

Read the first error in the terminal, correct it, and rerun make run. Database migrations and seed operations are designed to be rerun safely.