🛠️ Developing#

Guía para extender y mantener wsl-labs sin romper la coherencia del proyecto ni el flujo real de Windows ↔ contenedores wslc.

<!-- -->

🧭 Principios#

• Cada caso empaqueta un contenedor (o stack de contenedores) reproducible con

wslc, portado de docker-labs o nuevo.

• La documentación debe coincidir con lo que el código realmente entrega.
• El launcher .exe y el instalador son una capa aditiva de Windows: no

reemplazan a wslc ni al panel Node.js.

• Si cambias puertos, imágenes o contenedores de un caso, **hazlo en

containers/containers.config.json** y refléjalo en el README del caso. No lo dupliques.

🗂️ Estructura del repo#

🐳 Cómo añadir un caso de contenedor#

1 · Naming y estructura#

Formato NN-nombre-kebab, número de dos dígitos:

containers/13-mi-caso/
├── Dockerfile   # solo si construyes una imagen propia (FROM …)
├── server.js    # (opcional) código de la app
└── README.md

2 · Registro en containers/containers.config.json#

Añade una entrada al array cases:

{
  "id": "13",
  "name": "mi-caso",
  "title": "Mi caso",
  "description": "Descripción corta (imagen base, qué expone).",
  "category": "starter",
  "port": 8115,
  "url": "http://localhost:8115",
  "healthProtocol": "http",
  "build": [{ "image": "wsl-labs/mi-caso:latest", "context": "containers/13-mi-caso" }],
  "containers": [{ "name": "wslc-mi-caso", "image": "wsl-labs/mi-caso:latest", "ports": ["8115:3000"] }]
}

3 · Contenedor único vs. stack#

4 · README del caso#

Sigue la plantilla de los casos existentes (mira containers/01-node-api/README.md): datos del caso en tabla, comandos wslc build/run, verificación con curl, uso desde el panel, bajar, y un diagrama Mermaid opcional.

🖥️ Cómo tocar el panel#

El panel es un servidor Node.js con el módulo http nativo (sin dependencias npm). Escucha solo en 127.0.0.1:9092 y ejecuta wslc.exe en Windows (lo localiza en C:\Program Files\WSL\wslc.exe, o vía WSL_LABS_WSLC).

Reglas al modificar el servidor:

• No introduzcas dependencias npm: se mantiene "solo stdlib".
• Respeta el rate-limit nativo y el token opcional WSL_LABS_TOKEN.
• Prueba health en IPv4 e IPv6 (como curl localhost).
• Localiza el motor por WSL_LABS_WSLC → C:\Program Files\WSL\wslc.exe → PATH.

✅ Validación local#

Antes de abrir un PR, ejecuta lo que aplique a tu cambio:

# 1. Catálogo + endpoint overview (equivale al workflow dashboard)
node dashboard-server/verify-localhost.js
#   o
make test-dashboard

# 2. Construye y levanta el caso, y comprueba localhost
Invoke-RestMethod -Method Post -Headers @{ 'Content-Type'='application/json' } `
  -Body '{ "id": "13" }' http://localhost:9092/api/wslc/build
Invoke-RestMethod -Method Post -Headers @{ 'Content-Type'='application/json' } `
  -Body '{ "id": "13" }' http://localhost:9092/api/wslc/up
Invoke-WebRequest http://localhost:8115 -UseBasicParsing

Los mismos checks que corre CI (replícalos en local cuando puedas):

🌿 Flujo git sugerido#

1. 🌿 Crea una rama descriptiva.
2. ✏️ Haz cambios pequeños y verificables (carpeta + Dockerfile + catálogo + README).
3. 📖 Actualiza docs si cambias flujo operativo.
4. ✅ Corre las validaciones que apliquen.
5. 🚀 Abre el PR con contexto claro.

feat: add mi-caso container (13) to catalog
fix: harden localhost dashboard for IPv6 health check
docs: align wslc setup with pre-release update

📖 Ver también: RUNBOOK.md · RELEASE.md · CONTRIBUTING.md · docs/MAINTAINERS.md · FILE_ARCHITECTURE.md