Skip to content

10. Dev Experience

This section covers everything a developer needs to get started with the AClimate v3 ecosystem, from setting up a local development environment to understanding coding standards and contributing to the project.

Prerequisites

Before setting up any of the AClimate components, you need to have the following tools installed on your development machine:

  • Python 3.10 or higher, required for the WebAPI, ORM package, admin portal, and all ETL pipelines
  • Node.js 20 or higher, required for the frontend application
  • Docker, for running containerized services like the database, Keycloak, and GeoServer during local development
  • PostgreSQL 14 or higher, the database used by all platform components
  • Git, for version control and cloning the repositories

Repository Structure

All AClimate v3 repositories follow a consistent convention. Each component lives in its own repository under the CIAT-DAPA GitHub organization, named with the prefix aclimate_v3_. The repositories you will work with are aclimate_v3_orm for the data model, aclimate_v3_webapi for the API, aclimate_v3_frontend for the user interface, aclimate_v3_admin for the administrative portal, and the three ETL repositories for data processing: aclimate_v3_historical_spatial_etl, aclimate_v3_historical_location_etl, and aclimate_cut_spatial_data.

Each repository follows the same structure with a src/ directory containing the source code, a tests/ directory for tests, a Dockerfile for container builds, and a requirements.txt or package.json for dependencies.

Setting Up the ORM Package

The ORM package is the foundation of all Python components, so it should be installed first. Start by cloning the repository and installing it in development mode. This way, any changes you make to the models or services are immediately available to the other components without reinstalling.

git clone https://github.com/CIAT-DAPA/aclimate_v3_orm.git
cd aclimate_v3_orm
python -m venv env
source env/bin/activate
pip install -e .

Once installed, you can verify it works by running the existing tests:

pytest tests/ -v

Setting Up the Database

AClimate uses PostgreSQL as its primary data store. After installing PostgreSQL, create a database for the platform:

createdb aclimate_v3

The ORM package includes Alembic migrations that create and update the database schema. To apply the migrations and create all tables, navigate to the ORM directory and run:

alembic upgrade head

This will create all the tables defined by the ORM models, including the management entities, forecast tables, climate data tables, and security-related tables.

Setting Up the WebAPI

The WebAPI is the backend service that exposes data through RESTful endpoints. After cloning the repository, create a virtual environment and install the dependencies. The WebAPI depends on the ORM package, which you should have installed in development mode.

git clone https://github.com/CIAT-DAPA/aclimate_v3_webapi.git
cd aclimate_v3_webapi
python -m venv env
source env/bin/activate
pip install -r requirements.txt

Copy the example environment file and adjust the configuration for your local setup. The most important variables are the database connection string and the Keycloak URL for authentication.

cp .env.example .env

To start the API server locally for development, use uvicorn with the reload flag so changes are picked up automatically:

uvicorn src.main:app --reload --port 8000

The API will be available at http://localhost:8000 and the interactive documentation at http://localhost:8000/docs.

Setting Up the Frontend

The frontend is a Next.js application that requires Node.js. After cloning the repository, install the dependencies and start the development server.

git clone https://github.com/CIAT-DAPA/aclimate_v3_frontend.git
cd aclimate_v3_frontend/src
cp .env.example .env.local
npm install
npm run dev

The frontend will be available at http://localhost:3000. The configuration file defines which API URL and Keycloak server the frontend connects to, so make sure these point to your locally running services.

Setting Up the Admin Portal

The admin portal is a Flask application. After cloning, create a virtual environment and install the dependencies. Like the WebAPI, it depends on the ORM package.

git clone https://github.com/CIAT-DAPA/aclimate_v3_admin.git
cd aclimate_v3_admin
python -m venv env
source env/bin/activate
pip install -r requirements.txt

Copy the example environment file and adjust the configuration, then start the Flask development server:

cp .env.example .env
python src/run.py

The admin portal will be available at http://localhost:9000.

Environment Variables

Each component reads its configuration from environment variables. The most common ones you will need to configure for local development are:

  • DATABASE_URL, used by all Python components, defines the connection string to the PostgreSQL database
  • KEYCLOAK_URL, used by the API, frontend, and admin, points to the Keycloak authentication server
  • KEYCLOAK_REALM, the realm name configured in Keycloak for AClimate
  • KEYCLOAK_CLIENT_ID, the client identifier registered in Keycloak for each application
  • NEXT_PUBLIC_ACLIMATE_API_URL, used by the frontend, points to the WebAPI URL
  • NEXT_PUBLIC_GEOSERVER_URL, used by the frontend, points to the GeoServer WMS service

Testing Your Setup

Once all components are running, you can verify everything works by checking the health endpoints. The WebAPI exposes a health check at /health that returns a simple status response. The frontend should load without errors and redirect you to the Keycloak login page when you access it. The admin portal should allow you to log in and navigate through the configuration sections.

You can also run the automated tests included in each repository to verify that the components are correctly installed and configured:

# Run all Python tests
pytest tests/ -v

# Run frontend tests
npm run test

Coding Standards

Python code across all components follows PEP 8 conventions with Black for formatting and Ruff for linting. Type hints are required for all function signatures, and docstrings follow the Google style guide. TypeScript code in the frontend uses the project's ESLint configuration with strict mode enabled, and Prettier handles formatting with two-space indentation.

Commit messages follow the conventional commits format, which helps automate changelog generation and version management. Feature branches are created from the develop branch and merged through pull requests that require passing tests, clean linting, and code review approval.

Working with the ETL Pipelines

The ETL pipelines are designed to be run as batch processes rather than long-running services. Each ETL repository has a similar structure with connectors for downloading data, processors for transforming it, and tools for uploading results to the database or GeoServer. To run an ETL pipeline locally, install the dependencies, configure the data sources in the configuration files, and execute the main entry point script.