api-ubigeo/docs/active_context.md

Active Context - api-ubigeo

Última actualización: 2026-03-10

Estado Actual

PRODUCCIÓN ACTIVA — https://api-ubigeo.darkcodex.dev responde correctamente desde internet.

• Health: GET /api/v1/health → {"status":"ok"}
• Distritos: GET /api/v1/ubigeo/distritos?q=lima&limit=10 → HTTP 200

Decisiones Recientes

2026-03-10

• Traefik en Easypanel usa file provider con main.yaml — NO es directory:, solo lee ese único archivo
• El archivo api-ubigeo.yaml separado que creamos antes era ignorado por Traefik
• Solución: inyectar los routers/services directamente en main.yaml usando jq vía docker run -v
• El runner de Gitea corre en un contenedor sin acceso directo al host filesystem, pero puede usar docker run -v /host/path:/container/path para acceder a rutas del host
• main.yaml está en JSON (no YAML real), Traefik lo acepta igual
• Routers agregados: http-ubigeo-0 (redirect https) y https-ubigeo-0 (TLS letsencrypt)
• Service: ubigeo_api-0 → http://ubigeo-api:3200/

Infraestructura

Contenedor

• Imagen: ubigeo-api:latest (multi-stage build, node:20-alpine)
• Puerto interno: 3200
• Redes: api-ubigeo_ubigeo_network + easypanel
• Deploy path: /home/deployer/api-ubigeo/

Traefik

• Config file: /etc/easypanel/traefik/config/main.yaml (JSON)
• El CI inyecta routers via jq con docker run -v
• Idempotente: verifica si https-ubigeo-0 ya existe antes de agregar

CI/CD

• Gitea runner: contabo-runner en gitea_gitea_net
• Runner corre en contenedor pero con acceso a Docker socket del host
• Workflow: .github/workflows/deploy.yml
• Run exitoso: #29

Pendiente Próxima Sesión

• Nada crítico en api-ubigeo
• Pendiente en Impulsa Mobile: probar autocomplete de distrito con API live

Contexto Técnico

Workarounds

• main.yaml se sobreescribe en cada deploy de Easypanel → el CI debe reinjectar la ruta si eso ocurre
• El step Register Traefik route es idempotente (no duplica si ya existe)

Archivos Clave

• .github/workflows/deploy.yml — CI/CD completo
• docker-compose.production.yml — producción con red easypanel
• scripts/register-traefik.sh — script legacy (ya no se usa, se puede eliminar)
• src/modules/ubigeo/ubigeo.controller.ts — endpoints
• src/modules/ubigeo/dto/ubigeo.dto.ts — DTOs