Desarrollo Local con Docker

Un ambiente de desarrollo local bien configurado permite a los equipos trabajar de forma autónoma, rápida y consistente sin depender de ambientes compartidos. En HERA, utilizamos Docker y Docker Compose para emular localmente la infraestructura cloud (base de datos, caché, mensajería) y ejecutar los servicios de aplicación con hot-reload, replicando el comportamiento de los ambientes DEV/QA/PRD en la máquina del desarrollador.

Principio HERA

El ambiente local debe ser lo más cercano posible al ambiente de producción. Si la aplicación corre en un contenedor Docker en GKE, debe correr en un contenedor Docker en tu máquina. Esto elimina el “funciona en mi máquina” y adelanta la detección de problemas.

---

Herramientas Requeridas

Motor de contenedores: Podman

HERA estandariza Podman como motor de contenedores corporativo para el desarrollo local. En Linux, Docker Engine es una alternativa válida al ser open source. Docker Desktop no está autorizado en Grupo Herdez por restricciones de licenciamiento corporativo — usa Podman Desktop o Docker Engine (Linux) en su lugar.

Motor	Licencia	Daemon	Rootless	Compatibilidad
Podman	Apache 2.0 (open source)	Sin daemon (más seguro)	Por defecto	Compatible con Docker CLI y Compose
Docker Engine (Linux, alternativa)	Apache 2.0 (open source)	Requiere daemon root	Opcional	Nativo

Docker Desktop no está autorizado en Grupo Herdez

Docker Desktop requiere una suscripción de pago para uso corporativo bajo los términos actuales de Docker. Grupo Herdez ha estandarizado Podman como motor de contenedores corporativo para el desarrollo local — no se debe instalar Docker Desktop sin autorización explícita.

Si ya tienes Docker Desktop instalado, migra a Podman Desktop (o a Docker Engine si trabajas en Linux). Podman es compatible con la CLI y los Compose files de Docker — tus scripts y docker-compose.yml funcionan sin cambios.

Para consultar los términos de licenciamiento vigentes de Docker, ver política oficial de pricing de Docker.

Instalación por plataforma

Herramienta	Propósito	Windows	macOS	Linux
Podman Desktop	Motor de contenedores + Compose	podman-desktop.io	podman-desktop.io	apt/dnf install podman
Docker Engine + Compose (alternativa en Linux)	Motor de contenedores (nativo)	—	—	apt/yum install docker-ce docker-compose-plugin
Docker Scout	Escaneo de vulnerabilidades en imágenes	Incluido en Docker Desktop / CLI plugin	Incluido en Docker Desktop / CLI plugin	docker scout CLI plugin
VS Code	Editor con extensión Docker/Podman	code.visualstudio.com	Igual	Igual
Git	Control de versiones	git-scm.com	brew install git	apt install git

Si usas Podman, alias de compatibilidad

Podman es compatible con la CLI de Docker. Si tu equipo tiene scripts o documentación que usan docker, puedes crear un alias para no cambiar nada:

# Agregar a tu ~/.bashrc o ~/.zshrc
alias docker=podman
alias docker-compose="podman compose"

Todos los comandos de esta documentación (docker build, docker compose up, docker scout) funcionan igual con Podman.

Windows requiere WSL2

En Windows, Podman Desktop requiere WSL2 (Windows Subsystem for Linux 2). Trabaja con los archivos del proyecto dentro del filesystem de WSL2 (/home/user/projects/, accesible desde Windows como \\wsl$\Ubuntu\home\user\projects\) para evitar problemas de rendimiento con bind mounts.

Extensiones recomendadas para VS Code

Extensión	Propósito
Docker (ms-azuretools.vscode-docker)	Gestión visual de contenedores, imágenes y compose
Dev Containers (ms-vscode-remote.remote-containers)	Desarrollo dentro de un contenedor con todas las herramientas
Docker Compose (p1c2u.docker-compose)	Autocompletado y validación de docker-compose.yml
GitLab Workflow (GitLab.gitlab-workflow)	Integración con pipelines de GitLab HERA

---

Arquitectura del Ambiente Local

El ambiente local replica la arquitectura de microservicios de HERA usando Docker Compose:

Entorno de Desarrollo Local — Docker Compose

Capa de Aplicación

frontend Next.js / React :3000

bff-api Node.js / Python :4000

microservicio Java / .NET / Go :8080

Docker Network (red interna)

Capa de Infraestructura (emulada)

postgres PostgreSQL 16 :5432

redis Redis 7 Alpine :6379

pubsub GCP Emulator :8085

rabbitmq RabbitMQ 3 Mgmt :5672 / :15672

Mensaje clave Todos los servicios corren en contenedores aislados. El código se monta vía bind mounts para hot-reload.

---

Plantillas oficiales: grupo-herdez/platform/stacks/

Los artefactos de desarrollo local (Dockerfile.dev, docker-compose.yml, docker-compose.override.yml) no se escriben desde cero. El equipo de HERA publica y mantiene un catálogo de plantillas oficiales validadas y aprobadas en:

https://hera.gitlab.cloudherdez.com/grupo-herdez/platform/stacks/

Cada plantilla es el estándar de Grupo Herdez para su stack: base image aprobada, versión de runtime fijada, healthchecks, puerto de debug, convenciones de hot-reload y compatibilidad con el docker-compose.override.yml canónico.

Dos formas de consumir las plantillas

Los equipos de desarrollo pueden elegir el modo que mejor se adapte a su caso:

Modo	Cuándo usarlo	Cómo funciona	Updates de HERA
Fork (recomendado)	Proyectos nuevos o refactors planificados	Clonar el repo de la plantilla desde grupo-herdez/platform/stacks/* y adaptarla en el repositorio del producto. El upstream queda trackeado.	Automáticos — MRs de sincronización cuando HERA libera una nueva versión (nueva base image, fix de seguridad, mejora de healthcheck).
Copy-as-reference	Adaptación de un fragmento puntual, onboarding, aprendizaje del patrón	Copiar únicamente el fragmento que interesa (ej. un Dockerfile.dev) sin enlazar el repo con el upstream.	Manuales — el equipo es responsable de revisar los changelogs de grupo-herdez/platform/stacks/ y mantenerse al día.

Copy-as-reference no exime del estándar

Copiar el código no significa reescribirlo libremente. La plantilla define la base image, versión de runtime y convenciones obligatorias del estándar HERA. Si el fragmento copiado se diverge del upstream sin justificación, el escaneo de imágenes (Docker Scout) y las políticas de Golden Images lo marcarán como no conforme. Si necesitas un patrón que la plantilla no cubre, abre un issue en grupo-herdez/platform/stacks/ — puede evolucionar al catálogo oficial.

---

Ejemplo Completo: Proyecto E-Commerce

A continuación, la composición de la plantilla grupo-herdez/platform/stacks/compose-multiservice para un producto tipo e-commerce con frontend, BFF API, microservicio, base de datos, caché y mensajería.

Estructura del proyecto

Estructura de proyecto con Docker Compose

Ejemplo de un producto e-commerce con frontend, BFF API, microservicio y scripts de inicializacion.

Repositorio del Producto

tienda-herdez/
├── docker-compose.yml          ← Orquestacion de todos los servicios
├── docker-compose.override.yml ← Configuracion de desarrollo (hot-reload)
├── .env                        ← Variables de entorno (NO commitear)
├── .env.example                ← Template de variables (SI commitear)
├── frontend-next/
│   ├── Dockerfile
│   ├── Dockerfile.dev          ← Optimizado para desarrollo
│   └── src/
├── bff-api/
│   ├── Dockerfile
│   ├── Dockerfile.dev
│   └── src/
├── checkout-service/
│   ├── Dockerfile
│   ├── Dockerfile.dev
│   └── src/
└── scripts/
    ├── init-db.sql             ← Seed de base de datos
    └── init-pubsub.sh          ← Creacion de topics y suscripciones

Directorio Docker/Compose Config/Scripts Sensible (no commitear)

Mensaje clave Estructura estándar: docker-compose.yml + .env.example + Dockerfile.dev. Hot-reload incluido.

docker-compose.yml (base)

La plantilla base declara la topología completa del stack local: servicios de aplicación + servicios de infraestructura emulados en una red privada.

Servicios de aplicación

Servicio	Propósito	Puerto expuesto	Healthcheck
frontend	Frontend Next.js del producto	3000	— (depende de bff-api)
bff-api	Backend-for-Frontend (Node.js)	4000	GET /health cada 10 s
checkout-service	Microservicio de dominio (Spring Boot)	8080	Spring Boot Actuator

Servicios de infraestructura emulados

Servicio	Imagen	Puerto	Propósito	Persistencia
postgres	postgres:16-alpine	5432	Base de datos relacional	Volumen postgres-data
redis	redis:7-alpine	6379	Caché en memoria (LRU, 128 MB)	Volumen redis-data
pubsub-emulator	google-cloud-cli	8085	Emulador de GCP Pub/Sub	— (in-memory)
rabbitmq	rabbitmq:3-management-alpine	5672, 15672	Mensajería AMQP + UI	Volumen rabbitmq-data

Reglas de la plantilla

• Red privada hera-local (bridge) con resolución por nombre de servicio — ningún servicio expone puertos inter-servicio al host.
• Versiones de imagen fijas (postgres:16-alpine, no :latest) para reproducibilidad entre miembros del equipo.
• Healthchecks obligatorios en servicios de infraestructura — el depends_on: condition: service_healthy del compose los espera antes de arrancar la aplicación.
• Credenciales locales estándar (hera / hera_dev) — nunca reutilizar secretos de QA/PRD.

Consumo de la plantilla

Fork: clonar grupo-herdez/platform/stacks/compose-multiservice en el repo del producto y adaptar las rutas de context: a los servicios del proyecto. Las actualizaciones de HERA (nuevas versiones de imágenes base, fixes de seguridad, mejoras de healthcheck) llegan como MRs upstream.

Copy-as-reference: si sólo necesitas entender la topología o tomar un servicio puntual (ej. sólo postgres y redis para un proyecto más simple), copia el fragmento desde el repo de la plantilla. Revisa el changelog de grupo-herdez/platform/stacks/ periódicamente para mantener alineadas las versiones.

docker-compose.override.yml (desarrollo con hot-reload)

El override, incluido en la misma plantilla, aplica solo en desarrollo local (se ignora en CI): añade bind mounts del código fuente para hot-reload sin rebuild, volúmenes nombrados para node_modules que evitan conflictos host/contenedor, y expone el puerto de debug remoto (5005) para el servicio Java.

Servicio	Bind mount	Volumen nombrado	Comando modificado
frontend	./frontend-next/src, ./frontend-next/public	frontend-modules → /app/node_modules	— (hereda del base)
bff-api	./bff-api/src	bff-modules → /app/node_modules	npm run dev (watch mode)
checkout-service	./checkout-service/src	—	mvnw spring-boot:run con JDWP en 5005

Archivos .env

El archivo .env contiene variables sensibles para el ambiente local y nunca debe comitearse a Git. Incluye .env en tu .gitignore y provee un .env.example con los nombres de las variables sin valores. Esto se alinea con la política de secretos de HERA.

---

Dockerfile para Desarrollo (Dockerfile.dev)

El Dockerfile.dev está optimizado para desarrollo local con hot-reload, a diferencia del Dockerfile de producción que usa Golden Images multi-stage. HERA publica una plantilla oficial por stack bajo grupo-herdez/platform/stacks/; los equipos pueden forkear la plantilla (recomendado) o copiar el código como referencia para proyectos simples.

Catálogo oficial

Stack	Plantilla oficial	Base image	Puertos	Hot-reload
Node.js (frontend / BFF)	grupo-herdez/platform/stacks/nodejs	node:20-alpine	3000	npm run dev (watch)
Java / Spring Boot	grupo-herdez/platform/stacks/java-springboot	eclipse-temurin:21-jdk-alpine	8080 + 5005 (debug JDWP)	Spring Boot DevTools
Python / FastAPI	grupo-herdez/platform/stacks/python-fastapi	python:3.12-slim	8000	uvicorn --reload

Garantías comunes a todas las plantillas

• Capas de dependencias cacheadas: COPY del manifest de dependencias (package*.json, pom.xml, requirements.txt) antes del resto del código — cambiar una línea de código no invalida la capa de dependencias.
• Versión de runtime fija: ningún tag mutable (:latest, :lts). Las actualizaciones de runtime llegan como MRs upstream.
• Compatibilidad con bind mounts: el COPY . . final se sobrescribe por los bind mounts del docker-compose.override.yml, habilitando hot-reload sin rebuild.
• No son production-ready: los Dockerfile.dev no se usan nunca en PRD. Para producción cada stack tiene su propio Dockerfile multi-stage basado en Golden Images.

Fork vs. copy-as-reference

Fork (recomendado para proyectos nuevos): git clone desde grupo-herdez/platform/stacks/<tu-stack> → adaptar → los equipos reciben MRs automáticos cuando HERA actualiza la base image, parcha CVEs o mejora el Dockerfile.

Copy-as-reference (válido para proyectos simples o adaptaciones): abrir el repo de la plantilla en GitLab y copiar el fragmento necesario directamente desde ahí (el repo es la fuente de verdad — este portal no publica el contenido del Dockerfile para evitar drift). Sin upstream tracking — el equipo debe seguir manualmente el changelog de grupo-herdez/platform/stacks/ y aplicar updates.

Si tu proyecto usa un stack no listado, abre un issue en grupo-herdez/platform/stacks/ — el equipo de HERA lo evalúa y, si aplica, publica una nueva plantilla oficial.

---

Comandos Esenciales

Operaciones diarias

# Levantar todos los servicios (con build si es necesario)
docker compose up --build

# Levantar en background (detached)
docker compose up -d

# Ver logs de un servicio específico
docker compose logs -f bff-api

# Detener todos los servicios
docker compose down

# Detener y eliminar volúmenes (reset completo de datos)
docker compose down -v

# Reconstruir un servicio específico sin caché
docker compose build --no-cache bff-api

# Ejecutar un comando dentro de un contenedor en ejecución
docker compose exec bff-api sh

# Ver el estado de los servicios
docker compose ps

Gestión de base de datos

# Conectarse a PostgreSQL
docker compose exec postgres psql -U hera -d tienda_herdez

# Importar un dump de base de datos
docker compose exec -T postgres psql -U hera -d tienda_herdez < backup.sql

# Ver logs de la base de datos
docker compose logs postgres

Gestión de mensajería

# Crear un topic en el emulador de Pub/Sub
docker compose exec pubsub-emulator \
  gcloud pubsub topics create pedidos-creados \
  --project=hera-local

# Crear una suscripción
docker compose exec pubsub-emulator \
  gcloud pubsub subscriptions create sub-pedidos \
  --topic=pedidos-creados \
  --project=hera-local

# Acceder al panel de RabbitMQ
# Abrir en navegador: http://localhost:15672
# Usuario: hera / Contraseña: hera_dev

---

Escaneo de Seguridad Local con Docker Scout

Antes de hacer push al repositorio, es obligatorio escanear las imágenes localmente con Docker Scout. Esto se alinea con el Modelo de Responsabilidad Compartida:

# Construir la imagen de producción (no la de dev)
docker build -t tienda-herdez/bff-api:local ./bff-api

# Escanear vulnerabilidades críticas y altas
docker scout cves tienda-herdez/bff-api:local \
  --only-severity critical,high

# Ver recomendaciones de actualización de imagen base
docker scout recommendations tienda-herdez/bff-api:local

# Comparar con la versión anterior
docker scout compare tienda-herdez/bff-api:local \
  --to tienda-herdez/bff-api:previous

# Generar SBOM (Software Bill of Materials)
docker scout sbom tienda-herdez/bff-api:local

Obligatoriedad del escaneo

El Golden Pipeline ejecuta Docker Scout automáticamente y bloquea el despliegue si detecta vulnerabilidades Críticas o Altas. Ejecutar el escaneo localmente antes del push ahorra tiempo y evita pipelines fallidos. Los SLAs de remediación aplican desde la detección.

---

Validación del Dockerfile con Hadolint

Hadolint valida las mejores prácticas del Dockerfile antes de construir:

# Instalar Hadolint (una sola vez)
# Linux/macOS:
brew install hadolint
# O como contenedor:
docker pull hadolint/hadolint

# Validar un Dockerfile
hadolint ./bff-api/Dockerfile

# Validar con Docker (sin instalar):
docker run --rm -i hadolint/hadolint < ./bff-api/Dockerfile

# Ejemplo de salida:
# Dockerfile:3 DL3018 warning: Pin versions in apk add
# Dockerfile:7 DL3059 info: Multiple consecutive RUN instructions

---

Mejores Prácticas para el Ambiente Local

Rendimiento

Práctica	Detalle
Usar bind mounts solo para código fuente	No montar node_modules ni carpetas de dependencias compiladas
Usar named volumes para dependencias	frontend-modules:/app/node_modules evita conflictos host/container
Usar healthchecks en todos los servicios	Docker Compose respeta depends_on: condition: service_healthy
Separar Dockerfile.dev de Dockerfile (producción)	El de dev incluye herramientas de debug; el de prod usa Golden Images
En Windows, trabajar dentro de WSL2	El filesystem de WSL2 es 10x más rápido que el montaje cross-filesystem

Seguridad

Práctica	Detalle
Nunca usar contraseñas reales en el ambiente local	Usar hera_dev o similares; nunca reutilizar secretos de QA/PRD
No commitear .env	Incluir .env.example como template
Escanear con Docker Scout antes de push	Ejecutar docker scout cves contra la imagen de producción
Validar con Hadolint el Dockerfile de producción	Detectar malas prácticas antes de que lleguen al pipeline
Usar imágenes oficiales de infraestructura	postgres:16-alpine, redis:7-alpine, no builds custom

Consistencia

Práctica	Detalle
Usar docker-compose.override.yml para config de dev	El archivo base debe ser válido para CI también
Fijar versiones de imágenes de infraestructura	postgres:16-alpine, no postgres:latest
Documentar el setup en el README.md del proyecto	Incluir instrucciones de docker compose up y variables requeridas
Incluir scripts de inicialización	init-db.sql para seed de datos, init-pubsub.sh para topics

Flujo de trabajo recomendado

1. git clone del repositorio desde GitLab HERA
2. cp .env.example .env y completar variables locales
3. docker compose up --build para levantar todo el stack
4. Desarrollar con hot-reload — los cambios se reflejan al instante
5. docker scout cves antes de crear el Merge Request
6. docker compose down al terminar la jornada