🏗️ Arquitectura — WSL Container Center#

Versión: v1 Estado: 🟢 Activo Audiencia: 👥 Técnico, DevOps, administradores de sistemas Objetivo: Visión técnica del workspace y de cómo Windows controla contenedores wslc

📌 Objetivo de arquitectura#

wsl-labs es un panel para levantar y controlar contenedores con wslc, el motor de contenedores nativo de WSL (WSL 2.9+, tipo Docker). Es el equivalente de docker-labs pero usando wslc como motor. La arquitectura busca tres cosas:

• 🕹️ operación local con un clic: 📦 Construir → ▶ Levantar → 🌐 Abrir
• 🐳 contenedores reales (imágenes OCI, redes, multi-contenedor) accesibles desde localhost
• 🔗 una única fuente de verdad (containers/containers.config.json) que alimenta panel y launcher

📊 Estado arquitectónico#

🧱 Capas del sistema#

La frontera clave es el límite Windows → motor de contenedores. Todo lo que el usuario ve (navegador, launcher, panel) corre en Windows; los contenedores corren en el motor wslc. El panel cruza esa frontera ejecutando wslc.exe como proceso hijo.

flowchart LR
    subgraph WIN["🪟 Windows 11"]
        B["Navegador"]
        L["Launcher .exe (Go)"]
        D["🧭 Panel<br/>Node.js :9092"]
        WSLC["wslc.exe<br/>C:\\Program Files\\WSL"]
    end
    subgraph ENGINE["🐳 Motor de contenedores wslc"]
        subgraph NET["red wslc-pg-net"]
            APP["05 pg-app :8106"]
            PG["postgres"]
        end
        N["06 nginx :8104"]
        J["12 jenkins :8114"]
    end
    L --> D
    B --> D
    D -->|spawn| WSLC
    WSLC --> ENGINE
    APP <--> PG
    D -.->|"health HTTP<br/>IPv4 + IPv6"| ENGINE

🧠 Componentes principales#

1. 🧭 Panel#

Responsabilidades:

• Servir la UI estática (index.html, dashboard.css, dashboard.js)
• Exponer GET /api/wslc/overview
• Ejecutar acciones vía POST /api/wslc/{build,up,down,logs}
• Traducir cada acción a comandos wslc (build, run, stop, rm, logs, network)
• Localizar wslc.exe (env WSL_LABS_WSLC → C:\Program Files\WSL\wslc.exe → PATH)
• Sondear salud (HTTP, IPv4 + IPv6) y detectar imágenes construidas

2. 🪟 Launcher Windows#

Responsabilidades:

• Verificar que WSL 2 esté disponible
• Arrancar el panel en segundo plano
• Hacer polling a /api/wslc/overview hasta que responda
• Abrir el navegador en http://localhost:9092

3. 🐳 Motor de contenedores wslc#

Responsabilidades:

• Construir imágenes custom desde Dockerfile (wslc build, contexto containers/NN-*/)
• Ejecutar contenedores publicando puertos en localhost (wslc run -d -p …)
• Crear redes para los casos multi-contenedor (wslc network create)
• Exponer logs consultables desde el panel (wslc logs)

4. 📇 Catálogo containers/containers.config.json#

Responsabilidades:

• Definir cada caso: id, name, title, category, port, url, healthProtocol
• Declarar las imágenes a construir (build[]) con su context
• Declarar los contenedores (containers[]: name, image, ports, env) y la network
• Alimentar tanto al panel como al launcher

🗂️ Categorías del catálogo#

🔄 Flujo de una acción (Construir / Levantar)#

El corazón del sistema es cómo una pulsación en el navegador termina cambiando el estado de un contenedor. Ejemplo: 📦 Construir → ▶ Levantar el caso 05 API + PostgreSQL.

flowchart TD
    A["Usuario pulsa 'Construir' en el panel"] --> B["dashboard.js → POST /api/wslc/build { id: 05 }"]
    B --> C["server.js valida id contra el catálogo"]
    C --> D["wslc build -t wsl-labs/pg-app:latest containers/05-postgres-api"]
    D --> E["Usuario pulsa 'Levantar' → POST /api/wslc/up"]
    E --> F["wslc network create wslc-pg-net"]
    F --> G["wslc run -d --name wslc-postgres --network wslc-pg-net postgres:15"]
    G --> H["wslc run -d --name wslc-pg-app --network wslc-pg-net -p 8106:8000<br/>-e PG_HOST=wslc-postgres wsl-labs/pg-app:latest"]
    H --> I["Health-check HTTP (IPv4 e IPv6) a localhost:8106"]
    I --> J["Panel muestra 🟢 running"]

🩺 Modelo de health-check#

Un contenedor puede publicar el puerto por IPv4 (0.0.0.0) o por IPv6 (::). Un check que solo probara IPv4 marcaría "abajo" un caso que solo escucha por ::1. Por eso los checks prueban ambas familias (127.0.0.1 y ::1), igual que curl localhost. Todos los casos usan healthProtocol: http.

🧩 Principios de diseño#

📚 Documentos relacionados#

• README
• FILE_ARCHITECTURE.md
• SYSTEM_SPECS.md
• TECHNICAL_SPECS.md
• Track de contenedores WSLC
• Setup del panel