Cómo añadir un servicio al entorno local

Guía para desarrolladores: variables en el secret, servicio en Docker Compose y publicación HTTPS vía Nginx o Caddy (el proxy/gateway — no confundir con n8n ni otros backends).

Resumen en 6 pasos

1. Editar ~/devdocker/secrets/dev-enviroment.local.yaml (variables + ruta proxy).
2. Editar ~/devdocker/compose/docker-compose.yml (definición del servicio).
3. Opcional: crear ~/devdocker/pipelines/mi-servicio.Jenkinsfile para deploy con Jenkins.
4. bash scripts/devdocker.sh sync — copia compose a /home/usrdocker/compose y regenera Nginx/Caddy.
5. bash scripts/devdocker.sh secret — sube el secret a Jenkins.
6. bash scripts/devdocker.sh register y deploy del job proxy + tu servicio.

1. Secret — dev-enviroment.local.yaml

Archivo local (no commitear). Plantilla: secrets/dev-enviroment.example.yaml.

cp ~/devdocker/secrets/dev-enviroment.example.yaml \
   ~/devdocker/secrets/dev-enviroment.local.yaml

Variables de tu servicio

Añade un bloque con prefijo claro. Jenkins las lee en el pipeline y Compose las expande con ${VAR}.

# --- Mi API (job mi-api) ---
MI_API_IMAGE: "mi-api:dev"
MI_API_APP_PORT: "3000"
MI_API_PUBLIC_HOST: "localhost"

Jenkinsfile típico:

env.MI_API_IMAGE = "${yaml.MI_API_IMAGE ?: 'mi-api:dev'}"
env.MI_API_APP_PORT = "${yaml.MI_API_APP_PORT ?: '3000'}"

Rutas del proxy (Nginx / Caddy)

El gateway es el job proxy (Nginx) o proxy-caddy (Caddy). Las rutas se definen en PROXY_ROUTES:

PROXY_GATEWAY_DOMAIN: "localhost"
PROXY_ENGINE: "nginx"   # o caddy

PROXY_ROUTES:
  - subdomain: n8n
    upstream: n8n:5678
    enabled: true
  - subdomain: mi-api
    upstream: mi_api:3000
    enabled: true

devdocker sync ejecuta scripts/render-proxy-conf.py y escribe /home/usrdocker/compose/proxy/nginx/conf.d/default.conf y el Caddyfile. No edites esos archivos a mano salvo depuración puntual.

2. Compose — compose/docker-compose.yml

Añade el servicio en ~/devdocker/compose/docker-compose.yml (plantilla del proyecto).

  mi-api:
    image: ${MI_API_IMAGE:-mi-api:dev}
    container_name: mi_api
    restart: unless-stopped
    ports:
      - "${MI_API_APP_PORT:-3000}:3000"
    environment:
      APP_ENV: develop
    networks:
      - shared_network
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:3000/health"]
      interval: 20s
      timeout: 5s
      retries: 5

Servicios sin HTTP (Oracle :1521, Postgres, etc.) no van en PROXY_ROUTES: se exponen por puerto TCP en compose.

3. Proxy Nginx / Caddy — qué se genera

Con PROXY_GATEWAY_DOMAIN: localhost y la ruta anterior:

• URL: https://mi-api.localhost/
• Health del proxy: https://localhost/nginx-health (Nginx) o /proxy-health (Caddy)
• Certificados: /home/usrdocker/compose/proxy/certs/ (localhost.crt por defecto)

4. Pipeline Jenkins (recomendado)

Copia un job existente, p. ej. pipelines/portainer.Jenkinsfile → pipelines/mi-api.Jenkinsfile.

bash scripts/devdocker.sh register
bash scripts/devdocker.sh deploy mi-api
bash scripts/devdocker.sh deploy proxy    # o proxy-caddy — aplica rutas nuevas

Sin pipeline: tras sync, en el host:

cd /home/usrdocker/compose
docker compose up -d mi-api
docker compose up -d --force-recreate nginx-proxy

5. Comandos de verificación

cd ~/devdocker
bash scripts/devdocker.sh sync
bash scripts/devdocker.sh secret
bash scripts/devdocker.sh deploy proxy
bash scripts/devdocker.sh verify
curl -sk https://mi-api.localhost/health
docker ps

Ejemplo real: Oracle DB (sin proxy HTTP)

Checklist rápido

Actualizar plantillas del proyecto: bash scripts/devdocker.sh update (baja el último devdocker.tar.gz). Para apps de producto (ControlParking, etc.) ver Apps.