Maintain Knowledge Portal

Fecha: 2026-06-01

Objetivo

Mantener publicado el portal web de conocimiento sin duplicar documentacion ni convertir al VPS en otra fuente de verdad.

Regla central

• Git y el repo siguen siendo la fuente oficial.
• El portal solo publica una copia navegable de docs/.

Opcion elegida

• Stack recomendado: MkDocs Material
• Motivo: bajo consumo, busqueda integrada, Markdown nativo, Mermaid simple, build estatico y deploy Docker liviano

URL sugerida

• privada o semi-privada: https://doc.alpuntodeventa.com.ar/

Publicacion recomendada

• contenedor knowledge-portal
• bind local en VPS: 127.0.0.1:8085 -> 8085
• red Docker compartida con NPM: proxy-network
• publicacion externa solo por Nginx Proxy Manager

Proteccion recomendada

• usar Access List o Basic Auth en NPM
• no publicar este portal abierto si sigue describiendo infraestructura, backups, puertos, dominios y operacion interna

Archivos que gobiernan el portal

• mkdocs.yml
• infra/knowledge-portal/Dockerfile
• infra/knowledge-portal/docker-compose.yml
• infra/knowledge-portal/nginx.conf
• docs/

SAFE POINT minimo

1. correr git status -sb
2. correr git rev-parse HEAD
3. confirmar si hay cambios previos no relacionados

Flujo normal de actualizacion

1. editar la documentacion oficial en docs/
2. revisar si cambia navegacion en mkdocs.yml
3. correr build local: .\.venv-portal\Scripts\mkdocs build --strict
4. revisar que no haya secretos nuevos: rg -n -i "api[_-]?key|token|password|secret|bearer |sk-" docs
5. commitear y hacer git push
6. entrar al VPS y actualizar el repo
7. reconstruir y levantar el contenedor
8. validar portal, busqueda y Mermaid

Deploy o redeploy en VPS

Modo preferido, si el VPS tiene acceso al repo privado con deploy key o token:

1. cd /opt/openclawai
2. git pull --ff-only
3. docker compose -f infra/knowledge-portal/docker-compose.yml build --no-cache
4. docker compose -f infra/knowledge-portal/docker-compose.yml up -d
5. docker compose -f infra/knowledge-portal/docker-compose.yml ps

Modo fallback, si el VPS todavia no puede leer el repo privado:

1. generar snapshot local del commit aprobado
2. copiarlo al VPS por scp
3. extraerlo en /opt/openclawai
4. correr el mismo docker compose
5. dejar pendiente configurar deploy key o token para volver al flujo normal

Publicacion por dominio con NPM

1. crear Proxy Host para doc.alpuntodeventa.com.ar
2. forward host: knowledge-portal
3. forward port: 8085
4. activar certificado SSL
5. aplicar Access List o Basic Auth

Validacion final

• curl -I http://127.0.0.1:8085
• abrir portada del portal
• abrir documentos de ROADMAP, PROJECT-STATE y knowledge/README
• buscar una palabra real, por ejemplo Portainer
• abrir un diagrama Mermaid y confirmar render
• confirmar que no aparecen secretos reales

Cuando hay que tocar navegacion

• si entra una carpeta nueva importante en docs/governance/
• si una seccion cambia de nombre
• si la portada deja de reflejar el estado real

Checklist de cierre

• safe point registrado
• docs actualizadas en Git
• build local OK
• deploy Docker OK
• NPM apuntando al puerto local si se publica
• busqueda OK
• Mermaid OK
• secretos no expuestos
• git status -sb limpio