Climate Action Navigator

Table of Contents

1. About the Project
2. Getting Started
   • Prerequisites
   • Installation
   • Backend Server
   • Code Formatting & Pre-commit Hook
3. Build
4. Docker
5. Incident & Maintenance Announcements
6. Tests
7. References
8. Attribution

About the Project

This is the repository of the frontend website of HeiGIT's Climate Action project. Visit the Demo Website to view the current status of the dashboard, and access the available plugins.

Getting Started

Prerequisites

• pnpm
• Angular CLI pnpm install -g @angular/cli
• Docker Engine for Linux or Docker Desktop for Mac/Windows in case you wish to run the backend server

Installation

1. Clone the repository locally
2. Run pnpm install to install the dependencies
3. Create the configuration file:
   • Copy src/assets/env.template.js to src/assets/env.js
   • Edit env.js with your settings:
     • ENVIRONMENT_TYPE: Set to 'development' for local development
     • GEOCODE_API_KEY: Get an API key from HeiGIT for the Search function
     • CLIMATE_ACTION_API_URL: Set to 'http://api.localhost/climate-action-platform/v0' to use the Docker-based backend, or remove the line to use a natively run API Gateway (see Backend Server)
     • Other values can typically use the defaults provided
4. Run pnpm dev or ng serve to start the dev server
5. Navigate to http://localhost:4200/

The application will automatically reload if you change any of the source files.

Note: The src/assets/env.js file contains configuration for local development. For production deployments, these values are injected at runtime via environment variables (see Docker section below).

Backend Server

To see more than the raw website and access the plugins, you will need to set up a local dev environment of the Climate Action Infrastructure.

Make sure to start at least one plugin along with the API Gateway, for example docker compose up -d ca-plugin-blueprint ca-api-gateway

Running the API Gateway natively

Alternatively, run the API Gateway directly with Python (listening on http://localhost:8000, routes at the root). Leave CLIMATE_ACTION_API_URL unset in env.js so the default relative api path applies, and start the dev server with pnpm dev.

Code Formatting & Pre-commit Hook

Formatting is enforced automatically – there is nothing to activate or configure manually:

• Prettier formats all code and organizes/sorts imports. Configuration lives in .prettierrc.json.
• A pre-commit hook (husky + lint-staged) runs Prettier on staged files at every commit. The hook is installed automatically by pnpm install (via the prepare script) – no further setup needed.

To format the whole project manually, run pnpm exec prettier --write .

Build

Run pnpm build to build the project. The application is built as a single, environment-agnostic bundle that can be configured at runtime via environment variables.

Docker

The web app is Dockerised with runtime configuration support.

Building the Docker image

docker build . --tag repo.heigit.org/climate-action/web-app:{image_tag}

Running with environment variables

docker run --publish 8080:80 \
  -e ENVIRONMENT_TYPE="development" \
  -e CLIMATE_ACTION_API_URL="http://api.localhost/climate-action-platform/v0" \
  -e GEOCODE_API_KEY="your-ors-api-key" \
  -e APPWRITE_PROJECT_ID="your-project-id" \
  -e APPWRITE_ENDPOINT="appwrite-api-endpoint" \
  -e APPWRITE_WEBSITE_URL="appwrite-frontend" \
  repo.heigit.org/climate-action/web-app:{image_tag}

Then head to localhost:8080.

Pushing to Docker Hub

docker image push repo.heigit.org/climate-action/web-app:{image_tag}

Note: The same Docker image can be used for all environments (development, staging, production - if compatible) by simply changing the environment variables at runtime.

Incident & Maintenance Announcements

Incident and maintenance announcements are fetched from Cachet and displayed in the web app.

• The Cachet URL is stored in the CACHET_URL environment variable.
• The watched components are stored in the CACHET_WATCHED_COMPONENTS environment variable. This is a comma-separated list of Group: Component pairs (e.g. Climate Action: Climate Action Navigator, OpenRouteService: Directions API); an announcement is surfaced only when it references a component whose name and parent group match one of these pairs.
• The number of days to look ahead for maintenance announcements is stored in the SCHEDULE_LOOKAHEAD_DAYS environment variable.

If Cachet is unreachable, maintenance schedules fall back to a static JSON document, which can be hosted anywhere (e.g. NPoint). The full URL of the document is stored in the FALLBACK_SCHEDULES_URL environment variable (leave it empty to disable the fallback). To update the fallback maintenance announcements, simply edit the hosted document, and the changes will be reflected in the web app. The document is an array of announcements shaped like:

[
    {
        "maintenanceType": "Scheduled maintenance",
        "impact": "Expect brief downtime.",
        "downtimeStart": "2026-07-05T06:00:00Z",
        "downtimeEnd": "2026-07-05T08:00:00Z"
    }
]

Map Layers Sources

The Web App currently uses various sources for fetching the map layers that it has to display, all of which are outlined below:

---
config:
  layout: elk
---
flowchart RL
 subgraph s1["maps.heigit.org"]
        n7["pg_tileserv"]
        n8["GeoServer"]
  end
    n2["Climate Action Database"] --> n6["CA API Gateway"]
    n6 -- Centroids<br>(from the Search endpoint<br>used to display all<br>cached computations) --> n3["CAN Web App"]
    n1["Ohsome Boundaries<br>Database"] --> n7 & n8
    n7 -- "Vector Tiles<br>(used for AoI selection under<br>Admin. Boundaries mode)" --> n3
    n8 -- OGC WFS<br>(Individual Feature(s) used<br>in the computation request) --> n3
    n9["Versatiles"] -- Vector Basemaps --> n3
    n10["ArcGIS"] -- Raster Basemap<br>(ESRI World Imagery) --> n3

    n7@{ shape: diam}
    n8@{ shape: diam}
    n2@{ shape: db}
    n6@{ shape: diam}
    n3@{ shape: hex}
    n1@{ shape: db}
    n9@{ shape: diam}
    n10@{ shape: diam}

Loading

Tests

Run pnpm test:all to execute the unit & integration tests on Vitest (via ng test) and E2E tests on Cypress. For the cypress tests to succeed you will need a running instance of your app (see 4. under Installation). Additionally, for interactive cypress runs using cy:open you need to make sure your test-browser is set to English.

Vulnerabilities

After Docker images are built, the GitLab CI automatically scans the image and the production npm dependencies for vulnerabilities. Configuration of the scans is done via ci-variables. Default variables are available on a group level but may be overwritten on a per-project basis. There are no automated actions in place. In case a check fails, try updating the base image, OS packages and project dependencies, which may immediately resolve some vulnerabilities. Note that you may to need to rebuild the image from scratch (i.e. without cache). Note that some vulnerabilities may be unavoidable e.g. if they already exist in the latest base image.

To check the npm dependencies locally execute pnpm audit --prod.

To scan the image locally, pull or build the latest image of the web-app, then execute

docker run \
  --rm  \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $HOME/.cache/trivy:/root/.cache/trivy \
  aquasec/trivy \
  image \
  repo.heigit.org/climate-action/web-app:devel \
  --ignore-unfixed \
  --severity HIGH,CRITICAL

In case the image was improved, you may have to manually push and deploy the new image.

References

• Matplotlib Colormaps

Attribution

• Stars background image: Photo by Olena Bohovyk on Unsplash