10. Experiencia de Desarrollo¶
Esta sección cubre todo lo que un desarrollador necesita para comenzar con el ecosistema AClimate v3, desde la configuración de un entorno de desarrollo local hasta la comprensión de los estándares de código y cómo contribuir al proyecto.
Prerrequisitos¶
Antes de configurar cualquiera de los componentes de AClimate, necesitas tener instaladas las siguientes herramientas en tu máquina de desarrollo:
- Python 3.10 o superior, requerido para la WebAPI, el paquete ORM, el portal admin y todos los pipelines ETL
- Node.js 20 o superior, requerido para la aplicación frontend
- Docker, para ejecutar servicios contenerizados como la base de datos, Keycloak y GeoServer durante el desarrollo local
- PostgreSQL 14 o superior, la base de datos utilizada por todos los componentes de la plataforma
- Git, para control de versiones y clonación de los repositorios
Estructura de Repositorios¶
Todos los repositorios de AClimate v3 siguen una convención consistente. Cada componente vive en su propio repositorio bajo la organización CIAT-DAPA de GitHub, nombrado con el prefijo aclimate_v3_. Los repositorios con los que trabajarás son aclimate_v3_orm para el modelo de datos, aclimate_v3_webapi para la API, aclimate_v3_frontend para la interfaz de usuario, aclimate_v3_admin para el portal administrativo, y los tres repositorios ETL para el procesamiento de datos: aclimate_v3_historical_spatial_etl, aclimate_v3_historical_location_etl y aclimate_cut_spatial_data.
Cada repositorio sigue la misma estructura con un directorio src/ que contiene el código fuente, un directorio tests/ para las pruebas, un Dockerfile para las compilaciones de contenedores y un requirements.txt o package.json para las dependencias.
Instalación del Paquete ORM¶
El paquete ORM es la base de todos los componentes Python, por lo que debe instalarse primero. Comienza clonando el repositorio e instalándolo en modo desarrollo. De esta manera, cualquier cambio que realices en los modelos o servicios estará inmediatamente disponible para los otros componentes sin necesidad de reinstalar.
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 .
Una vez instalado, puedes verificar que funciona ejecutando las pruebas existentes:
Configuración de la Base de Datos¶
AClimate usa PostgreSQL como su almacén de datos principal. Después de instalar PostgreSQL, crea una base de datos para la plataforma:
El paquete ORM incluye migraciones Alembic que crean y actualizan el esquema de la base de datos. Para aplicar las migraciones y crear todas las tablas, navega al directorio del ORM y ejecuta:
Esto creará todas las tablas definidas por los modelos ORM, incluyendo las entidades de gestión, tablas de pronóstico, tablas de datos climáticos y tablas relacionadas con seguridad.
Instalación de la WebAPI¶
La WebAPI es el servicio backend que expone datos a través de endpoints RESTful. Después de clonar el repositorio, crea un entorno virtual e instala las dependencias. La WebAPI depende del paquete ORM, que deberías haber instalado en modo desarrollo.
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
Copia el archivo de entorno de ejemplo y ajusta la configuración para tu entorno local. Las variables más importantes son la cadena de conexión a la base de datos y la URL de Keycloak para la autenticación.
Para iniciar el servidor API localmente para desarrollo, usa uvicorn con el indicador de recarga para que los cambios se recojan automáticamente:
La API estará disponible en http://localhost:8000 y la documentación interactiva en http://localhost:8000/docs.
Instalación del Frontend¶
El frontend es una aplicación Next.js que requiere Node.js. Después de clonar el repositorio, instala las dependencias e inicia el servidor de desarrollo.
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
El frontend estará disponible en http://localhost:3000. El archivo de configuración define a qué URL de API y servidor Keycloak se conecta el frontend, así que asegúrate de que apunten a tus servicios locales en ejecución.
Instalación del Portal Admin¶
El portal admin es una aplicación Flask. Después de clonar, crea un entorno virtual e instala las dependencias. Al igual que la WebAPI, depende del paquete ORM.
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
Copia el archivo de entorno de ejemplo y ajusta la configuración, luego inicia el servidor de desarrollo Flask:
El portal admin estará disponible en http://localhost:9000.
Variables de Entorno¶
Cada componente lee su configuración desde variables de entorno. Las más comunes que necesitarás configurar para el desarrollo local son:
- DATABASE_URL, utilizada por todos los componentes Python, define la cadena de conexión a la base de datos PostgreSQL
- KEYCLOAK_URL, utilizada por la API, frontend y admin, apunta al servidor de autenticación Keycloak
- KEYCLOAK_REALM, el nombre del realm configurado en Keycloak para AClimate
- KEYCLOAK_CLIENT_ID, el identificador de cliente registrado en Keycloak para cada aplicación
- NEXT_PUBLIC_ACLIMATE_API_URL, utilizada por el frontend, apunta a la URL de la WebAPI
- NEXT_PUBLIC_GEOSERVER_URL, utilizada por el frontend, apunta al servicio WMS de GeoServer
Probando tu Configuración¶
Una vez que todos los componentes estén en ejecución, puedes verificar que todo funciona revisando los endpoints de salud. La WebAPI expone una verificación de salud en /health que retorna una respuesta de estado simple. El frontend debería cargar sin errores y redirigirte a la página de inicio de sesión de Keycloak cuando accedas a él. El portal admin debería permitirte iniciar sesión y navegar por las secciones de configuración.
También puedes ejecutar las pruebas automatizadas incluidas en cada repositorio para verificar que los componentes están correctamente instalados y configurados:
# Ejecutar todas las pruebas de Python
pytest tests/ -v
# Ejecutar las pruebas del frontend
npm run test
Estándares de Código¶
El código Python en todos los componentes sigue las convenciones PEP 8 con Black para formateo y Ruff para linting. Los type hints son obligatorios en todas las firmas de funciones, y los docstrings siguen la guía de estilo de Google. El código TypeScript en el frontend usa la configuración ESLint del proyecto con modo estricto habilitado, y Prettier maneja el formateo con indentación de dos espacios.
Los mensajes de commit siguen el formato conventional commits, lo que ayuda a automatizar la generación de changelogs y la gestión de versiones. Las ramas de funcionalidad se crean desde la rama develop y se fusionan a través de pull requests que requieren pruebas exitosas, linting limpio y aprobación en la revisión de código.
Trabajando con los Pipelines ETL¶
Los pipelines ETL están diseñados para ejecutarse como procesos por lotes en lugar de servicios de larga duración. Cada repositorio ETL tiene una estructura similar con conectores para descargar datos, procesadores para transformarlos y herramientas para subir los resultados a la base de datos o a GeoServer. Para ejecutar un pipeline ETL localmente, instala las dependencias, configura las fuentes de datos en los archivos de configuración y ejecuta el script de punto de entrada principal.