Desarrollo de Servicios – Ambiente de Desarrollo¶

Guía para levantar y mantener los dev-env de backend y frontend (shell + microfrontends).

Conceptos clave de ambientes¶

dev-env¶

Repositorio que orquesta servicios en desarrollo. Monta código fuente local en contenedores Docker (hot reload) y centraliza configuración, documentación y conectables.

deploy-env¶

Repositorio que orquesta imágenes versionadas en test/staging/producción. Solo usa código compilado; versiona imágenes y configuración por separado.

microservicio / microfrontend¶

Cada servicio o MFE es un repo independiente, agregado al dev-env como Git submodule bajo src/.

Backend – dev-env de microservicios¶

Inicializar un dev-env backend¶

Ejemplo de flujo recomendado:

git clone <proyecto_url>/dev-env.git <nombre_proyecto>
cd <nombre_proyecto>

make init   # copia config/env.example a .env, resetea submódulos, instala deps
make up     # levanta todos los servicios de desarrollo
make logs   # ver logs
make down   # bajar servicios

Estructura mínima¶

dev-env/
├── src/                      # Submódulos Git de cada servicio backend/frontend
│   ├── backend/              # Ejemplo: servicio backend NestJS
│   ├── frontend/             # Ejemplo: frontend integrado
│   └── ...
├── config/
│   └── env.example           # Todas las variables de ambiente del proyecto
├── doc/                      # Documentación (deploy, APIs, usuario, admin)
├── data/                     # Volúmenes locales (postgres, minio, etc.)
├── docker-compose.yml        # Orquestación de desarrollo
├── Makefile                  # Comandos: init, up, down, logs, etc.
└── .env                      # Copia editable de env.example (no en git)

docker-compose de desarrollo (backend)¶

Principios: - Servicios propios (backend, otros): imágenes dev (-dev:latest), código montado desde ./src/<servicio>. - Servicios externos (PostgreSQL, Mongo, etc.): versiones fijas hardcodeadas, volúmenes en ./data/<servicio>. - Variables de entorno solo las necesarias en environment.

Ejemplo abreviado:

services:
  backend:
    image: registry.url/proyecto/backend-dev:latest
    ports:
      - "${BACKEND_PORT}:3000"
    environment:
      - NODE_ENV=${NODE_ENV}
      - DATABASE_USER=${POSTGRES_USER}
      - DATABASE_PASSWORD=${POSTGRES_PASSWORD}
      - DATABASE_NAME=${POSTGRES_DB}
    depends_on:
      - postgres
    volumes:
      - ./src/backend:/app

  postgres:
    image: postgres:16
    ports:
      - "${POSTGRES_PORT}:5432"
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
    volumes:
      - ./data/postgres:/var/lib/postgresql/data

Makefile del dev-env backend¶

El Makefile centraliza inicialización y ciclo de vida:

.DEFAULT_GOAL := help

.PHONY: help init up down restart logs logs-backend

help:
    @echo "make init   - Setup inicial (submodulos + deps)"
    @echo "make up     - Levantar servicios"
    @echo "make down   - Bajar servicios"
    @echo "make logs   - Ver todos los logs"

init:
    @if [ ! -f .env ]; then cp config/env.example .env; fi
    git submodule update --init --recursive --remote
    @for submodule in backend frontend; do \
      if [ -d "src/$$submodule" ]; then \
        docker compose run --rm $$submodule rm -rf node_modules package-lock.json; \
        docker compose run --rm $$submodule npm install; \
      fi; \
    done

up:
    docker compose up -d

down:
    docker compose down --remove-orphans

logs:
    docker compose logs -f

Variables de ambiente¶

config/env.example documenta todas las variables del proyecto (puertos, DB, secrets).
Cada servicio puede tener su env.example local con solo las variables que usa.
.env (copiado desde config/env.example) se modifica para el entorno local y no va a git.

Frontend – dev-env del shell y microfrontends¶

En ETER, el dev-env frontend suele ser el repo apps/modernizacion/eter: - src/shell/: submódulo del shell Angular. - src/<mfe>/: submódulos de microfrontends.

Estructura típica frontend¶

dev-env/
├── src/
│   ├── eter-shell/                 # Shell (contenedor madre)
│   ├── eter-personas-frontend/     # Microfrontend Personas
│   ├── eter-usuarios-frontend/     # Microfrontend Usuarios
│   └── ...
├── config/
│   ├── env.example
│   └── microfrontends.json         # Configuración de MFEs
├── docker-compose.yml
├── Makefile
└── .env

docker-compose de desarrollo (shell + MFEs)¶

Orden recomendado: 1. Shell (contenedor madre, imagen versionada). 2. Microfrontends en modo dev (imágenes -dev:latest con código montado). 3. Backend (si aplica). 4. Conectables (DB, cache, etc.).

Ejemplo abreviado:

services:
  shell:
    image: registry.url/proyecto/eter-shell:${SHELL_VERSION}
    ports:
      - "${SHELL_PORT}:4200"
    environment:
      - NODE_ENV=${NODE_ENV}
      - BACKEND_URL=${BACKEND_URL}
    volumes:
      - ./src/personas:/microfrontends/personas
      - ./config/microfrontends.json:/config/microfrontends.json:ro

  personas-frontend:
    image: registry.url/proyecto/eter-personas-frontend-dev:latest
    ports:
      - "${PERSONAS_FRONTEND_PORT}:4200"
    environment:
      - NODE_ENV=${NODE_ENV}
      - BACKEND_URL=${BACKEND_URL}
    volumes:
      - ./src/personas:/app
    depends_on:
      - backend

Makefile frontend¶

Similar al backend, pero iterando sobre eter-shell y MFEs:

.PHONY: init up down restart logs

init:
    @if [ ! -f .env ]; then cp config/env.example .env; fi
    git submodule update --init --recursive --remote
    @for submodule in eter-shell eter-personas-frontend eter-usuarios-frontend; do \
      if [ -d "src/$$submodule" ]; then \
        docker compose run --rm $$submodule rm -rf node_modules package-lock.json; \
        docker compose run --rm $$submodule npm install; \
      fi; \
    done

Dependencias comunes¶

Node 20+ (o la versión indicada por cada repo).
Docker y Docker Compose.
Git con soporte para submódulos.

Observabilidad en dev¶

Logs estructurados en backend y shell.
Endpoints /health para cada servicio y MFE.
Uso consistente de puertos, registrados en config/env.example.