Skip to main content

Entorno de desarrollo

1. Despliegue en local

Requisitos​

Para desplegar el sistema en local, debes cumplir con lo siguiente:

  1. Tener instalado Docker con Docker Compose v2.
  2. Tener arrancado Docker.
  3. Tener instalado Git.
  4. Disponer de acceso SSH al servidor ubuntu@213.32.26.205.
  5. Tener los siguientes puertos locales libres: 3010, 13001, 18083, 15447 y 17018.

Configuración del directorio de trabajo​

Una vez cumplidos los requisitos, clone el repositorio de infraestructura destinado para el despliegue local del sistema y accede a la carpeta generada:

git clone --branch despliegue-local --single-branch \
  https://github.com/ASPA-TECH/infra.git

Dentro de esta carpeta (que será tu directorio de trabajo principal), debes descargar el código fuente de los 3 servicios. Para clonar los repositorios en sus ramas correspondientes, ejecuta estos comandos:

git clone --branch develop --single-branch \
  https://github.com/ASPA-TECH/aspa-back-node-prod.git

git clone --branch develop --single-branch \
  https://github.com/ASPA-TECH/aspa-worker-cpp-prod.git

git clone --branch V4 --single-branch \
  https://github.com/ASPA-TECH/aspa-front-next-prod.git

El comando anterior para descargar el código del servicio Frontend únicamente lo hace para la rama V4 del repositorio GitHub que aloja dicho servicio. Si quisieras tener otra rama, tendrías que utilizar estos comandos:

cd aspa-front-next-prod/
git remote set-branches --add origin nombre-rama
git fetch origin nombre-rama
git switch nombre-rama

Recuerda que tras ejecutar estos comandos, estaría localizado en el directorio del servicio Frontend. Para volver al directorio de la infraestructura ejecute:

cd ..

Nota: Si en su defecto, quisieras probar alguno de los servicios que tengas en local, simplemente tendrías que mover la carpeta que aloja por completo el servicio que tengas en local, al directorio de trabajo, y clonar el resto.

Al levantar la infraestructura por primera vez, el sistema se desplegará vacío, sin ningún dataset base cargado para realizar los cálculos de accesibilidad.

Entonces, descagarás el código de un servicio extra que utilizarás más adelante para importar datasets pequeños en el sistema:

git clone --branch main --single-branch \
  https://github.com/ASPA-TECH/small-datasets.git

Este servicio contiene un script para crear datasets personalizados según unos parámetros de opciones. Puedes conocer más detalles sobre él aquí.

Por último, deberás crear el archivo .env con las credenciales para acceder al sistema:

cp .env.example .env

En este archivo .env recomendamos agregar las siguientes credenciales iniciales:

  • AUTH_BOOTSTRAP_USERNAME: aspa
  • AUTH_BOOTSTRAP_PASSWORD: 4sp4Us3r

Tras ejecutar los comandos, la estructura principal resultante de tu directorio debe ser esta:

infra/
├── aspa-back-node-prod/
├── aspa-front-next-prod/
├── aspa-worker-cpp-prod/
├── configurations/caddy/
|                    ├── Caddyfile
|                    └── Caddyfile.local
├── datasets/
├── docker/postgres/10-restore-geom-grid.sh
├── results/
├── small-datasets/
├── tests_velocidad/
├── .env
├── .env.example
├── docker-compose.local.yml
├── docker-compose.yml
└── README.md

Descarga de puntos geoespaciales desde el servidor​

El sistema necesita la base de datos espacial para funcionar. Desde la raíz del directorio infra, descarga el dump correcto directamente desde el servidor a tu máquina local ejecutando:

ssh ubuntu@213.32.26.205 \
  "docker exec aspa_postgres_dev \
    pg_dump -U aspa -d aspa_db \
      --format=custom \
      --no-owner \
      --no-acl \
      --table=malla.geom_grid_250m" \
  > geom_grid_250m.backup

Verifica que el archivo se ha descargado correctamente:

test -s geom_grid_250m.backup
file geom_grid_250m.backup

El resultado del último comando debe indicar PostgreSQL custom database dump, lo que confirma que la descarga fue exitosa y el archivo es válido.

Despliegue​

Sigue estos pasos para realizar el despliegue en local:

  1. Construir e iniciar los servicios: Ejecuta el siguiente comando para construir las imágenes Docker y levantar los contenedores en segundo plano (detached mode):
docker compose -f docker-compose.local.yml up --build -d
  1. Monitorizar el proceso: La importación de la base de datos solo se ejecuta la primera vez que se crea el volumen aspa-local_pg_data. Puedes monitorizar este proceso, además del estado de los contenedores e imágenes con:
docker compose -f docker-compose.local.yml logs -f postgres
docker compose ps

Acceso al sistema​

Una vez levantados los servicios, puedes acceder a la aplicación desde tu navegador a través de la dirección: http://localhost:3010.

Nota de acceso: Si has utilizado los valores recomendados en el archivo .env, las credenciales iniciales del sistema en el Frontend son:

  • Usuario: aspa
  • Contraseña: 4sp4Us3r

A nivel técnico, el proxy inverso Caddy recibe las peticiones en el puerto 3010, envía las rutas de la API al backend, y deriva el resto del tráfico al frontend en Next.js (el cual se está ejecutando internamente con npm run dev). Esto significa que si realizas cambios en el servicio Frontend, se actualizarán automáticamente, sin necesidad de relanzar las imágenes Docker.

Importación de un dataset inicial​

Para poder empezar a probar la plataforma y realizar consultas, necesitas importar datos. Por lo que necesitas utilizar la rama V4 del Frontend, en la que tienes habilitada la funcionalidad necesaria para cargar nuevos datasets. Para utilizar esta versión del Frontend, debes de estar utilizando su rama V4 en el direcotorio de trabajo. Para ello, puedes usar este comando:

cd aspa-front-next-prod/
git checkout V4

Recuerda usar el siguiente comando para volver a colocarte sobre la dirección raíz del directorio de trabajo:

cd ..

Puedes utilizar esta guía paso a paso para importar un conjunto de datos en el sistema:

  1. Inicia sesión en la plataforma, dirígete a la sección de Administración y selecciona el apartado Gestión de Datasets, ahora pulsa en el botón Nuevo dataset. Deberás agregarle un nombre al dataset y seleccionar el escenario de accesibilidad por defecto. Cuando finalices, para continuar pulsa en el botón Siguiente.

image

  1. Debes de importar los archivos correspondientes a cada campo. Una vez importados, pulsa en el botón Importar conjunto de datos. Si no ha ocurrido ningun error, podrás finalizar con la subida del dataset en el sistema.

  2. En este momento, puedes ver el dataset listado en la vista. Finalmente, debes de pulsar en el botón Cargar y con eso tendrías disponible tu dataset en la plataforma.

image

Comandos habituales​

Aquí tienes una lista de comandos recurrentes que te serán útiles durante el desarrollo:

  • Ver el estado de los contenedores y los healthchecks:
docker compose -f docker-compose.local.yml ps
  • Ver los logs de un servicio específico (en tiempo real):
docker compose -f docker-compose.local.yml logs -f caddy
docker compose -f docker-compose.local.yml logs -f frontend
docker compose -f docker-compose.local.yml logs -f backend
docker compose -f docker-compose.local.yml logs -f worker
  • Ver todos los logs combinados:
docker compose -f docker-compose.local.yml logs -f
  • Reconstruir backend o worker tras modificar su código:
docker compose -f docker-compose.local.yml up -d --build backend worker
  • Parar los servicios (sin borrar los datos ni las bases de datos):
docker compose -f docker-compose.local.yml down
  • Borrar todo (incluyendo bases de datos y volúmenes locales):
docker compose -f docker-compose.local.yml down -v
  • Volver a iniciar todo el ecosistema:
docker compose -f docker-compose.local.yml up -d
  • Repetir la importación de PostgreSQL sin borrar MongoDB:
docker compose -f docker-compose.local.yml down
docker volume rm aspa-local_pg_data
docker compose -f docker-compose.local.yml up --build -d

Carpetas compartidas: Los datasets generados e importados se comparten entre el backend y el worker a través de la carpeta ./datasets. Los resultados de las consultas se comparten mediante la carpeta ./results.

2. Entorno de desarrollo GitHub

El código fuente y la documentación del sistema están organizados en los siguientes repositorios:

3. Herramientas requeridas

Las herramientas necesarias para trabajar con el sistema ASPA serían las siguientes: