Saltar a contenido

Sync Knowledge Portal From Git

Fecha: 2026-06-01

Objetivo

Dejar el Knowledge Portal sincronizable desde origin/main sin editar documentacion directamente en el VPS.

Regla central

  • la fuente de verdad es siempre este repo Git
  • el VPS solo publica una copia generada
  • si hay diferencia entre VPS y repo, gana Git

SAFE POINT obligatorio

Antes de cualquier sync:

  1. git status -sb
  2. git rev-parse HEAD

Diagnostico O9.3

Estado real auditado por SSH el 2026-06-01:

  • URL publicada: https://doc.alpuntodeventa.com.ar/
  • snapshot publicado en VPS: /opt/openclawai
  • metodo de deploy previo: sync controlado de archivos + docker compose up -d --build
  • contenedor publicado: knowledge-portal
  • compose rector: /opt/openclawai/infra/knowledge-portal/docker-compose.yml
  • bind local esperado: 127.0.0.1:8085 -> 8085
  • upstream esperado en NPM: knowledge-portal:8085
  • gap actual: el checkout del VPS sigue como snapshot sin .git
  • consecuencia: hoy no existe garantia de origin, rama ni git pull operativo en el VPS
  • evidencia viva de runtime:
  • docker compose -f /opt/openclawai/infra/knowledge-portal/docker-compose.yml ps muestra knowledge-portal en Up
  • curl -I http://127.0.0.1:8085/ -> HTTP/1.1 200 OK
  • curl -I https://doc.alpuntodeventa.com.ar/ -> HTTP/2 200
  • search/search_index.json responde
  • una pagina real sigue renderizando Mermaid
  • hallazgo clave: el snapshot publicado no coincide con el HEAD local f49b9c581c1599ed72cec60cad5bf704f7108673
  • interpretacion: el portal publicado sigue sirviendo un snapshot anterior a O9.2; por eso hoy faltan tanto .git como el contenido mas nuevo del repo

Diagnostico operativo a correr en el VPS

Estos comandos sirven para cerrar el estado real sin editar contenido:

  1. cd /opt/openclawai
  2. pwd
  3. ls -la
  4. test -d .git && echo git-present || echo git-missing
  5. git status -sb
  6. git rev-parse HEAD
  7. git branch --show-current
  8. git remote -v
  9. stat -c '%U:%G %a %n' /opt/openclawai /opt/openclawai/infra /opt/openclawai/docs
  10. docker ps --filter name=knowledge-portal
  11. docker inspect -f '{{json .Config.Labels}}' knowledge-portal
  12. docker compose -f /opt/openclawai/infra/knowledge-portal/docker-compose.yml ps
  13. curl -I http://127.0.0.1:8085/
  14. curl -I https://doc.alpuntodeventa.com.ar/

Si git no existe o falla por snapshot sin .git, el gap queda confirmado y no habilita inventar credenciales.

Flujo recomendado de sincronizacion

Opcion recomendada

  • usar deploy key SSH de solo lectura asociada al repo privado
  • alternativa aceptable: token de acceso solo lectura almacenado fuera del repo
  • no guardar secretos en Markdown, Git ni logs del script

Secuencia objetivo

  1. el cambio nace en este repo
  2. validacion local: mkdocs build --strict
  3. commit y git push
  4. en el VPS: git pull --ff-only origin main
  5. rebuild: mkdocs build --strict
  6. redeploy: docker compose -f infra/knowledge-portal/docker-compose.yml up -d --build --force-recreate
  7. validacion local del servicio: curl -I http://127.0.0.1:8085/
  8. validacion publica final: curl -I https://doc.alpuntodeventa.com.ar/

Scripts operativos preparados

Archivos:

  • infra/knowledge-portal/deploy-knowledge-portal.sh
  • infra/knowledge-portal/activate-real-git-checkout.sh

deploy-knowledge-portal.sh:

  • exige checkout Git real
  • exige repo limpio
  • registra SAFE POINT
  • valida origin y rama main
  • hace git fetch y git pull --ff-only
  • crea o reutiliza .venv-portal
  • corre mkdocs build --strict
  • valida docker compose config
  • recrea knowledge-portal
  • valida http://127.0.0.1:8085/
  • imprime evidencia final con commit y estado HTTP

activate-real-git-checkout.sh:

  • exige una deploy key SSH real en el VPS
  • valida acceso read-only a GitHub con git ls-remote
  • clona main en un path temporal
  • compara snapshot vs checkout Git y deja reporte
  • conserva backup del snapshot anterior
  • activa el checkout real en /opt/openclawai
  • ejecuta deploy-knowledge-portal.sh
  • evita imprimir claves privadas o tokens
  • puede ejecutarse versionado desde el repo o ya staged en el VPS como /root/activate-real-git-checkout.sh

Diagnostico O9.5

Estado real revalidado por SSH el 2026-06-01 despues de O9.4:

  • el checkout del VPS ya era Git real: /opt/openclawai/.git
  • la deploy key seguia vigente: ~/.ssh/openclawai_github_deploy
  • ssh -T git@github.com con esa key seguia autenticando en modo read-only
  • origin seguia apuntando a: git@github.com:gcanuti/openclawai-vps-lab.git
  • la rama seguia siendo: main
  • permisos observados: root:root 755 /opt/openclawai, root:root 755 /opt/openclawai/infra, root:root 707 /opt/openclawai/docs
  • GIT_SSH_COMMAND no estaba exportada de forma permanente en la sesion del host, pero el deploy la recompone en runtime cuando detecta la deploy key
  • causa real del fallo de git pull: el working tree del VPS quedo con cambios manuales de O9.4 sin commitear sobre 8106783, por lo que git pull --ff-only rechazaba el merge aunque la autenticacion y origin estuvieran correctos
  • evidencia de la causa: git status -sb mostraba archivos de docs y mkdocs.yml modificados mas docs/governance/operations/O9.4-SERVICE-ACCESS-PUBLICATION.md sin trackear

Correccion aplicada en O9.5

  • se comparo el contenido sucio del VPS contra origin/main
  • se confirmo que esos cambios coincidian con el commit correcto ya publicado en GitHub: d30c336e2e547d69a76b49ebc767911464b84891
  • se genero un stash preventivo: o95-pre-pull-safety-20260601
  • con el repo limpio, el deploy oficial ejecuto: git fetch --prune origin main y luego git pull --ff-only origin main
  • el fast-forward efectivo fue: 8106783 -> d30c336
  • despues del pull, el script rebuildo y recreo knowledge-portal
  • no se usaron scp, tokens ni secretos embebidos

Procedimiento para habilitar Git real en VPS

Con deploy key SSH

  1. generar o reutilizar una key dedicada en el VPS: ssh-keygen -t ed25519 -N '' -f ~/.ssh/openclawai_github_deploy -C knowledge-portal-deploy
  2. leer la clave publica sin tocar la privada: cat ~/.ssh/openclawai_github_deploy.pub
  3. agregar esa clave publica como Deploy key read-only en GitHub para gcanuti/openclawai-vps-lab
  4. cargar known_hosts: ssh-keyscan github.com >> ~/.ssh/known_hosts
  5. validar acceso read-only sin imprimir secretos: GIT_SSH_COMMAND='ssh -i ~/.ssh/openclawai_github_deploy -o IdentitiesOnly=yes' git ls-remote git@github.com:gcanuti/openclawai-vps-lab.git main
  6. ejecutar el bootstrap seguro ya staged en el VPS: bash /root/activate-real-git-checkout.sh
  7. evidencia esperada del bootstrap:
  8. backup del snapshot anterior en /opt/openclawai-backups/openclawai-snapshot-<timestamp>
  9. reporte de comparacion en /opt/openclawai-backups/openclawai-compare-<timestamp>.txt
  10. checkout Git real activado en /opt/openclawai
  11. ejecucion final de deploy-knowledge-portal.sh

Con token read-only

  1. guardar el token fuera del repo y fuera de docs
  2. configurar el remote en el VPS usando helper seguro del sistema
  3. validar git remote -v sin imprimir el secreto
  4. correr el mismo script de deploy

Estado operativo actual

  • la deploy key dedicada del VPS ya fue aceptada por GitHub: ~/.ssh/openclawai_github_deploy
  • fingerprint publica validada: SHA256:e6g0Mxk83ELK0Njm7B4URwlcE7pTjp5Z5i+tTYV9L9w
  • autenticacion SSH validada: Hi gcanuti/openclawai-vps-lab! You've successfully authenticated
  • bootstrap real ejecutado: bash /root/activate-real-git-checkout.sh
  • resultado: /opt/openclawai dejo de ser snapshot y paso a checkout Git real con .git
  • validacion Git: git rev-parse HEAD y git rev-parse origin/main coinciden en d30c336e2e547d69a76b49ebc767911464b84891
  • deploy final: bash /opt/openclawai/infra/knowledge-portal/deploy-knowledge-portal.sh ejecuta OK usando la deploy key read-only
  • detalle relevante del host: el VPS no tiene python3-venv, por eso el script hace fallback al build estricto dentro del Dockerfile con mkdocs build --strict
  • validacion publica: https://doc.alpuntodeventa.com.ar/ responde 200 search/search_index.json responde governance/knowledge/infrastructure/dns-tls/ sigue entregando Mermaid
  • validacion O9.5 adicional: el deploy oficial del portal ya vuelve a hacer el git pull real desde origin/main; el workaround por scp deja de ser necesario
  • secretos: no se imprimieron claves privadas ni tokens durante la activacion

Revalidacion 2026-06-02

  • SAFE POINT remoto revalidado en /opt/openclawai:
  • git status -sb -> ## main...origin/main
  • git rev-parse HEAD -> f20c91ef8eff3c405e4620b063927393943c1e51
  • el checkout seguia siendo Git real: /opt/openclawai/.git
  • origin seguia apuntando a: git@github.com:gcanuti/openclawai-vps-lab.git
  • nueva causa real del fallo publickey: la deploy key ~/.ssh/openclawai_github_deploy seguia presente y valida, pero root ya no tenia ~/.ssh/config, por lo que ssh no seleccionaba automaticamente esa identidad para github.com
  • evidencia:
  • ssh -T git@github.com devolvia Permission denied (publickey)
  • git pull --ff-only origin main fallaba con el mismo error
  • GIT_SSH_COMMAND='ssh -i ~/.ssh/openclawai_github_deploy -o IdentitiesOnly=yes -o UserKnownHostsFile=~/.ssh/known_hosts' git ls-remote ... si autenticaba correctamente
  • correccion aplicada: se recreo ~/.ssh/config con entrada explicita para github.com usando IdentityFile ~/.ssh/openclawai_github_deploy
  • validacion posterior:
  • ssh -T git@github.com vuelve a autenticar en read-only
  • git pull --ff-only origin main vuelve a operar en /opt/openclawai
  • fast-forward observado: f20c91e -> 7a78ce1

Validacion de cierre

  • SAFE POINT inicial: obligatorio
  • diagnostico VPS: documentado
  • flujo recomendado: definido
  • script operativo: creado
  • bootstrap de reemplazo seguro: creado
  • validacion local: mkdocs build --strict
  • validacion local del contenedor cuando se ejecute en VPS: curl -I http://127.0.0.1:8085/
  • validacion publica final: curl -I https://doc.alpuntodeventa.com.ar/

Politicas de seguridad

  • no editar docs manualmente en el VPS
  • no guardar secretos en el repo
  • no pegar tokens en runbooks
  • no imprimir claves privadas ni tokens en logs