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:
If you already have the repository, update it and run make install from the
repository root.
Start the application¶
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:
The response should be:
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:
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 dev keeps Dagster running at http://127.0.0.1:3002. In another
terminal, start the Python API:
Documentation only¶
To preview this documentation site locally:
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.