Fix: "Funcional" apuntaba a una URL que no existe — VitePress real en dev con subdominio local

Date: 2026-07-25 Status: ✅ Ya aplicado y en uso — este documento describe trabajo YA HECHO, no pendiente. Traefik, docs.soterex.localhost y VITE_DOCS_URL ya están en docker-compose.yml/infra/traefik/ y frontend/.env.example desde hace varias tareas — ver doc/plans/2026-07-25-revertir-doc-nativa-volver-vitepress.md (el plan real que se siguió) y doc/architecture/ADR-004-sso-docs-api.md. El checklist de abajo queda como referencia histórica, no como pendiente.

El problema

El link "Funcional" del sidebar apuntaba a https://docs.soterex.cislatam.net — una URL hardcodeada que nunca existió, era un placeholder que quedó puesto a propósito hasta tener el deploy real. En dev, hacer click ahí no lleva a ningún lado — de ahí la mala experiencia que reportó el cliente ("la documentación quedó malísima").

La solución

No se abandona VitePress — sigue siendo la herramienta correcta para la documentación técnica (ver la decisión original). Lo que se corrige es que:

1. El portal de VitePress (doc/) corre de verdad en dev, como parte de docker-compose.yml — hoy no estaba integrado ahí, había que levantarlo a mano aparte con npm run docs:dev (ver doc/site/README.md viejo) y era fácil que quedara desactualizado o ni se levantara.
2. La URL del link sale de una variable de entorno, no está hardcodeada — así cambiar de ambiente (dev → staging → producción) es cambiar un valor en .env, no tocar código.
3. En dev, apunta a un subdominio local real: docs.soterex.localhost — sin puerto, gracias a un reverse proxy (Traefik) que se suma al stack.

Cambios concretos

1. frontend/src/layouts/AppLayout.vue (ver reference/AppLayout.vue)

href: import.meta.env.VITE_DOCS_URL || 'http://docs.soterex.localhost',

2. frontend/.env.example — agregar:

# URL del portal de documentación (VitePress) — cambia por ambiente.
VITE_DOCS_URL=http://docs.soterex.localhost

3. docker-compose.yml — agregar Traefik (reverse proxy) + el servicio de docs

Ver reference/docker-compose-snippet.yml, completo y ya validado (python3 -c "import yaml..." sin errores). Resumen de lo que hace:

• traefik: reverse proxy — mapea nombres de host limpios (docs.soterex.localhost) a los puertos internos de cada servicio, sin que el usuario tenga que acordarse de puertos. Dashboard opcional en http://localhost:8090.
• docs: corre npm run docs:dev (VitePress) montando la carpeta doc/ como volumen — reemplaza tener que levantarlo a mano aparte.

Nota: dejé comentado (no aplicado) un ejemplo de cómo sumarle las mismas labels de Traefik al servicio frontend existente, para que en algún momento también tenga un nombre limpio (soterex.localhost en vez de localhost:5173) — no es parte de este fix puntual, pero queda ahí para cuando se quiera hacer.

4. start-dev.sh — agregar nota

Actualizar el mensaje de URLs útiles al final del script para incluir http://docs.soterex.localhost (portal de documentación).

Qué hace falta en la máquina — probablemente nada

Los dominios que terminan en .localhost están reservados por estándar (RFC 6761) para resolver siempre a 127.0.0.1 — la mayoría de los sistemas operativos modernos (macOS incluido) lo resuelven solos, sin tocar /etc/hosts. Si por algún motivo no resuelve solo (por ejemplo, un DNS corporativo/VPN que lo pisa), el fallback es agregar una línea a mano:

echo "127.0.0.1 docs.soterex.localhost" | sudo tee -a /etc/hosts

Recién hacer esto si docs.soterex.localhost no carga después de levantar docker compose up.

Staging y Producción — próximo paso, no incluido acá

Ya resuelto — ver doc/plans/2026-07-25-staging-go-live-runbook.md: Firebase Hosting (no Route53+S3/CloudFront) sirve el sitio VitePress ya buildeado (npm run docs:build) en docs.soterex.stag.cislatam.net (Staging) / docs.soterex.cislatam.net (Producción), y VITE_DOCS_URL en el .env/GitHub Secret de cada ambiente apunta a esa URL real.

Checklist

• [ ] Aplicar el cambio de AppLayout.vue (URL desde variable de entorno).
• [ ] Agregar VITE_DOCS_URL a frontend/.env.example y al .env local.
• [ ] Agregar los servicios traefik y docs a docker-compose.yml.
• [ ] Confirmar que docker compose up levanta todo y que http://docs.soterex.localhost carga el sitio VitePress real.
• [ ] Actualizar start-dev.sh con la URL nueva en el resumen final.
• [ ] (Fallback, solo si hace falta) agregar la línea a /etc/hosts.

Archivos de referencia adjuntos (reference/)

• AppLayout.vue — con la URL desde variable de entorno
• docker-compose-snippet.yml — servicios traefik + docs, validado