Documentación
Carpeta: docs/ · Puerto: 8080 · Enlace: http://localhost:8080
· Tecnología: Docusaurus 3 compilado a estáticos y servido con Nginx
Esto que estás leyendo. Se levanta como un módulo más del sistema, así que está disponible sin conexión en cualquier instalación.
Responde a la funcionalidad de plan de formación y wiki (helpdesk) del diseño del proyecto, cuyo propósito era que la comunidad pudiera consultar por su cuenta tanto los conceptos —autoconsumo, comunidad energética, tarifas, legislación— como el funcionamiento de la plataforma.
Configuración
| Argumento | Qué es | Por defecto |
|---|---|---|
DOCS_URL | URL pública del sitio, para las URL canónicas y el sitemap | http://localhost:8080 |
DOCS_BASE_URL | Subcarpeta desde la que se sirve | / |
Docusaurus fija estos valores al compilar, no al arrancar, así que llegan como argumentos de construcción. Ponerlos como variables de entorno del contenedor no tendría ningún efecto.
./dev.sh up -d --build docs
Buscador
El sitio lleva buscador propio, que indexa el contenido al compilar y busca en el navegador contra un índice estático. No depende de ningún servicio externo, así que funciona en una intranet o sin conexión. Es deliberado: la alternativa habitual, Algolia DocSearch, obliga a registrar el sitio y a depender de un tercero en cada búsqueda.
Desplegar sólo la documentación
Para publicar únicamente el sitio de documentación en su propio dominio, sin el
resto del sistema, hay un compose aparte: docs/docker-compose.yml.
El docker-compose.yml de la raíz levanta el sistema completo —base de
datos, dos APIs y tres aplicaciones web— y publica puertos en el anfitrión. Para
publicar sólo la documentación no sirve.
En Portainer
Stacks → Add stack → Repository
| Campo | Valor |
|---|---|
| Repository URL | https://github.com/zertifier/ris3cat-mono |
| Repository reference | refs/heads/master |
| Compose path | docs/docker-compose.yml |
Y en Environment variables:
VIRTUAL_HOST=ris3cat-docs.zdevutils.com
LETSENCRYPT_HOST=ris3cat-docs.zdevutils.com
DOCS_URL=https://ris3cat-docs.zdevutils.com
PROXY_NETWORK=docker_default
Ninguna es obligatoria: todas traen ese mismo valor por defecto. Se declaran para poder publicarlo en otro dominio sin tocar el código.
Cómo llega el tráfico
El servidor tiene nginx-proxy + acme-companion. nginx-proxy vigila el socket
de Docker y, al ver un contenedor con VIRTUAL_HOST, genera solo el vhost y
recarga Nginx; acme-companion pide el certificado TLS. No hay que editar ninguna
configuración en el servidor.
Por eso este contenedor no publica puertos: el proxy llega a él por la red
interna de Docker. VIRTUAL_PORT es el 80 de dentro del contenedor, no uno del
anfitrión.
La red va como external porque la crea el stack del proxy, no este. En este
servidor es docker_default; comprobarlo con docker network ls.
El registro A del dominio tiene que apuntar al servidor, y eso se hace en el
proveedor de DNS. Lo que enlaza ese dominio con este contenedor es
VIRTUAL_HOST; Portainer no toca el DNS.
Al cambiar el dominio, reconstruir
DOCS_URL se incrusta al compilar. Cambiarla y reiniciar no basta: en Portainer
hay que usar Update the stack marcando Re-pull image and redeploy, o
Pull and redeploy, para que se vuelva a construir.
Editar la documentación
Las páginas son archivos Markdown en docs/docs/. La estructura del menú lateral
se genera sola a partir de las carpetas; el orden y las etiquetas salen de:
sidebar_positionytitleen la cabecera de cada archivo;_category_.jsonen cada carpeta.
Para trabajar con recarga automática, sin Docker:
cd docs && npm install && npm start
El sitio está configurado con onBrokenLinks: 'throw'. Si un enlace interno
apunta a una página que no existe, la compilación falla en lugar de publicar un
enlace muerto. Es intencionado.