Añadir una demo.

Registrar una demo es editar un archivo versionable, no guardar un formulario. El catálogo solo enlaza; no ejecuta ni despliega aplicaciones.

Prepara una unidad independiente

Crea demos/<slug>/ dentro del repositorio, o utiliza un repositorio externo. No importes código del catálogo ni de otra demo. Cada unidad tiene README, runtime fijado, instalación, tests, Dockerfile y Compose propios.

HTML, CSS y JavaScript estáticos

Sirve los archivos terminados en un contenedor HTTP no root, puerto interno 8080. Incluye recursos y fuentes locales. Una demo estática no necesita Node en producción. Comprueba sus rutas y permisos antes de marcarla disponible.

Python o ML

Fija versión de Python, dependencias y modelo con checksum/revisión. El servicio de la demo sirve su propia UI/API en 8080. Documenta RAM, CPU/GPU y tamaño de modelo medidos; no presupongas GPU. Separa el modo sintético del conectado y deshabilita proveedores por defecto. No pongas claves ni descargas de modelos en el catálogo.

Una demo con base de datos

La base pertenece a esa demo, nunca al catálogo. Usa una red privada y un volumen propio, sin publicar el puerto de DB. Documenta migración, retención, backup y restauración probada. SQLite exige un almacén compatible y política de réplica; una DB de servidor exige readiness y credenciales runtime exclusivas.

Contrato operativo por demo: propietario, propósito, arranque, URL, estado editorial, health local, datos sintéticos, límites, variables sin secretos, puertos de loopback libres, retención, retirada y procedimiento de recuperación. El catálogo no vigila su health.

Edita el registro único

catalogo/demos.json contiene {"schemaVersion":1,"demos":[...]}. Añade un objeto completo a demos. Este ejemplo es únicamente documentación y no una demo registrada:

{
  "slug": "mi-demo",
  "title": "Nombre de la demo",
  "description": "Qué muestra y cuáles son sus límites.",
  "category": "Categoría real",
  "technologies": ["Python"],
  "owner": "Responsable real",
  "status": "preparing",
  "launchUrl": "https://demo.example.test/"
}

El slug es único y admite letras minúsculas, números y guiones internos. sourceUrl es opcional y público, sin credenciales. preview es opcional: imagen real dentro de assets/, sin traversal ni URL remota. No añadas una captura de una aplicación inexistente. Los ejemplos de ML o DB no se registran como productos reales.

preparing no ofrece apertura. available requiere que el responsable haya comprobado URL y permisos y deja constancia de cuándo y cómo. archived conserva la ficha sin apertura. No se cambia el estado por un reloj ni por salud no medida.

cd /Users/sicora/Artekia/Demos/catalogo
python3 scripts/validate.py --allow-local
python3 -m unittest discover -s tests -v
node --test tests/*.test.mjs
python3 -m http.server 4173 --bind 127.0.0.1

Solo en desarrollo explícito: visita http://127.0.0.1:4173/?local=1. Si el puerto está ocupado, no detengas el proceso ajeno. Python 3.9+ no necesita dependencias para validar. El navegador valida el mismo esquema antes de renderizar.

Publica sin trasladar el modo local

Asigna un destino HTTPS real, autorizado y sin credenciales. Edita la URL en el JSON canónico y ejecuta python3 scripts/validate.py sin bandera local. No marques la ficha disponible si la aplicación no lo está. Nunca uses un dominio de ejemplo como destino real.

Alternativa para conservar el registro de desarrollo: produce un artefacto con scripts/publish.py --launch slug=HTTPS_URL --output .build/production/demos.json. No edita el original ni cambia estados. Se valida en modo producción antes de escribir. Para Docker proporciona REGISTRY_FILE dentro del contexto; para un servidor estático instala el artefacto como demos.json.

En Coolify crea un recurso Git + Docker Compose independiente: Base Directory /catalogo, Compose Location /compose.yaml, Watch Paths catalogo/**. Domina el servicio catalogo con HTTPS y puerto interno :8080. No uses compose.local.yaml, red predefinida, raw mode ni puertos host en producción. Auto Deploy apagado hasta autorización y prueba de filtros.

El build por defecto es producción y rechaza loopback. La bandera ?local=1 solo tiene efecto en origen loopback: un host público no habilita desarrollo. No hay secretos runtime del catálogo. Revisar y publicar el catálogo no arranca ni reconstruye una demo. Los comandos de despliegue necesitan autorización aparte.

Retira sin borrar el historial

Cambia el estado a archived, valida y revisa el catálogo. Retirar contenedores, datos, volúmenes o DNS es una operación independiente del responsable de la demo, con su política de retención. Nunca renombres un slug para ocultar un cambio de destino.

Para los comandos completos de Docker, validación y publicación, consulta catalogo/README.md del repositorio.