Actualiza toolkit operativo y documentación

2026-09-10 20:53:50 -06:00
parent 3b7209dcc1
commit 714057bfc8
69 changed files with 6023 additions and 384 deletions
@@ -1,80 +1,115 @@
 # Proxmox & Coolify Manager

-Proyecto local para operar Proxmox con ayuda agentica desde Codex.
+Toolkit para operar un homelab con ayuda de un agente: un host Proxmox local y el
+stack Coolify que corre dentro de su LXC `102`, más el túnel de Cloudflare y los
+repos en GitHub y Gitea.

-La idea practica es simple: este repo guarda el contexto, los runbooks y los
-scripts seguros para que Codex pueda diagnosticar y ayudarte a gestionar el host
-Proxmox local sin depender de memoria suelta ni de secretos pegados en Markdown.
+La idea es simple: este repo guarda el contexto, los runbooks y los scripts
+seguros para que un agente pueda diagnosticar y ayudarte a gestionar la
+infraestructura sin depender de memoria suelta ni de secretos pegados en Markdown.
+
+## Empieza por aquí
+
+| Si quieres… | Lee |
+|---|---|
+| saber **qué script usar** para algo | **[docs/TOOL-INDEX.md](docs/TOOL-INDEX.md)** — el catálogo canónico |
+| saber **qué existe y qué versión corre** | [docs/proxmox-inventory.md](docs/proxmox-inventory.md) |
+| que un agente opere el sistema | [CLAUDE.md](CLAUDE.md) — arquitectura + router de intención |
+| resolver un problema concreto | [docs/runbooks/](docs/runbooks/) |
+
+> **Cuatro trampas conocidas** producen resultados silenciosamente incorrectos
+> (el flag `-Raw` invertido entre wrappers, comillas anidadas corrompidas en SSH,
+> nombres de contenedor no adivinables, y el 404 que Cloudflare impone a
+> `/applications/*` en el hostname público). Están documentadas en la §1 del
+> índice. Léela antes de operar.

 ## Estado verificado

-Verificado el 2026-05-30 desde esta maquina:
+Verificado el **2026-08-29** desde esta máquina:

- Host Proxmox: `192.168.0.200`
- Nodo: `thinkcentre`
- Version: Proxmox VE `9.1.1`
- Kernel: `6.17.2-1-pve`
- LXC detectados: `100 hermes`, `102 coolify`
- Docker corre dentro del LXC `102`
- SSH con clave local funciona
- API REST autenticada funciona cuando el token se carga desde entorno
+- Host Proxmox: `192.168.0.200`, nodo `thinkcentre`, Proxmox VE `9.1.1`,
+  kernel `6.17.2-1-pve`
+- LXC: `100 hermes` (running — commit `5d3c15aaa`, MiniMax-M3), `102 coolify` (running)
+- Sin VMs QEMU
+- Docker corre dentro del LXC `102`: **68 contenedores**, 28 recursos
+  registrados en Coolify
+- Coolify `v4.3.14` — su API está **completa contra el origen**
+  (`http://192.168.0.117:8000/api/v1`); vía Cloudflare `/applications/*` y
+  `/github-apps` devuelven 404 (bloqueo del edge, no de Coolify). Los endpoints
+  de estado exigen POST desde v4.2.
+- SSH con clave local: OK · API de Coolify: OK · **API de Proxmox: OK**
+  (token `root@pam!openclaw` cargado en `.env.local.ps1`)
+- API de Cloudflare: **sin token cargado**, se gestiona desde el dashboard
+
+Credenciales y llaves SSH verificadas: `ACCESS.md` (local, gitignored).

 ## Estructura

- `agent/SKILL.md`: reglas operativas para que Codex actue como agente Proxmox.
- `agent/TOOLS.md`: comandos seguros y patrones de uso.
- `coolify_skill/`: skill local para operar Coolify, Docker en LXC `102` y API
-  de Coolify sin guardar secretos.
- `deploy_skill/`: skill para deployar proyectos nuevos a Coolify de punta a
-  punta (scaffold Dockerfile/compose → checklist → repo GitHub → push → alta
-  via API → deploy → verificacion → rollback). Necesita `GITHUB_TOKEN` y
-  `COOLIFY_TOKEN` en `.env.local.ps1`.
- `gitea_skill/`: skill para operar la instancia Gitea self-hosted (crear/listar/
-  buscar repos, migrar desde GitHub, wire de un remoto `gitea` y push headless
-  con token inyectado por invocacion — sin persistirlo en `.git/config`).
-  Necesita `GITEA_URL`, `GITEA_USER`, `GITEA_TOKEN` en `.env.local.ps1`.
- `docs/proxmox-inventory.md`: inventario verificado y notas de arquitectura.
- `docs/runbooks/`: procedimientos concretos para conexion, diagnostico y Coolify.
- `docs/runbooks/nextcloud.md`: recuperacion y fix HTTPS para Nextcloud.
- `docs/runbooks/baserow.md`: puesta en vivo de Baserow y fix red/Traefik.
- `docs/casos/`: casos verificados paso a paso (ej. `chatwoot-enterprise-patch.md`).
- `docs/AGENTS-coolify-apps.md`: guia para agentes/LLMs que desarrollan una app destinada a esta instancia de Coolify (reglas de red, puertos, dominios/TLS, env, volumenes, healthchecks) + checklist pre-deploy.
- `scripts/`: wrappers PowerShell para SSH, API e inventario.
- `PROXMOX/`, `proxmox-agent/`, `proxmox-skill/`: carpetas legacy que ahora apuntan a la documentacion viva.
-
-## Configuracion local
-
-Los secretos no viven en el repo. Usa variables de entorno o un archivo privado
-ignorado por Git, por ejemplo `.env.local.ps1`.
-
-Plantilla:
-
-```powershell
-.\scripts\Set-ProxmoxEnv.example.ps1
+```
+CLAUDE.md              Arquitectura, router de intención y reglas para el agente
+docs/
+  TOOL-INDEX.md        Catálogo canónico de herramientas + gotchas   ← empieza aquí
+  proxmox-inventory.md Estado verificado del sistema (fuente de verdad)
+  AGENTS-coolify-apps.md  Contrato para construir una app deployable en este Coolify
+  runbooks/            Procedimientos vigentes
+  casos/               Casos resueltos paso a paso
+  incidentes/          Archivo histórico — NO es fuente de verdad
+scripts/               Wrappers de host: SSH, API, inventario, Cloudflare, Chatwoot
+  apps/                Scripts de deploy específicos de una app
+  host/                Artefactos que se despliegan en el host Proxmox
+agent/                 Skill de operación del host Proxmox
+coolify_skill/         Skill de operación de Coolify + referencia de su API
+deploy_skill/          Skill de deploy de proyectos nuevos a Coolify
+gitea_skill/           Skill de la capa de hosting git self-hosted
 ```

-Prueba de conexion:
+Cada carpeta `*_skill/` tiene un `SKILL.md` (reglas operativas) y un `TOOLS.md`
+(ejemplos ejecutables).
+
+### Runbooks
+
+| Runbook | Qué cubre |
+|---|---|
+| [conexion.md](docs/runbooks/conexion.md) | Establecer y verificar el acceso |
+| [diagnostico.md](docs/runbooks/diagnostico.md) | Triage general del host |
+| [coolify-docker.md](docs/runbooks/coolify-docker.md) | Operar Docker dentro del LXC 102 |
+| [seguridad.md](docs/runbooks/seguridad.md) | Postura de seguridad y manejo de secretos |
+| [cloudflare-tunnel.md](docs/runbooks/cloudflare-tunnel.md) | Túnel y rutas (**gestionado desde el dashboard**) |
+| [autostart-coolify.md](docs/runbooks/autostart-coolify.md) | Auto-arranque del stack tras un corte de luz |
+| [chatwoot-update.md](docs/runbooks/chatwoot-update.md) | Actualizar Chatwoot sin perder la edición enterprise |
+| [nextcloud.md](docs/runbooks/nextcloud.md) | Recuperación y fix HTTPS |
+| [baserow.md](docs/runbooks/baserow.md) | Puesta en vivo y fix de red/Traefik |
+
+## Configuración local
+
+Los secretos no viven en el repo. Van en `.env.local.ps1`, ignorado por Git.
+Copia la plantilla y rellénala:

 ```powershell
-.\scripts\Test-ProxmoxConnection.ps1
+Copy-Item .env.example .env.local.ps1
 ```

-Inventario rapido:
-
-```powershell
-.\scripts\Get-ProxmoxInventory.ps1
-```
-
-Comando SSH puntual:
+Luego, en cada sesión:

 ```powershell
+. .\.env.local.ps1
+.\scripts\Test-ProxmoxConnection.ps1     # smoke test; sale 1 si algo falla
+.\scripts\Get-ProxmoxInventory.ps1       # inventario completo
 .\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct list"
 ```

-## Reglas de operacion
+Para la verificación operativa con navegador (`Test-ServiceOnline.ps1`) hace
+falta Node: `npm install` una vez en la raíz del repo.

- Primero diagnostico de solo lectura.
- Cambios destructivos requieren confirmacion explicita: borrar, reiniciar,
-  apagar, editar red, mover discos, actualizar paquetes o modificar servicios.
- Preferir scripts del repo antes que comandos manuales largos.
- No registrar tokens, passwords ni claves privadas en Markdown.
+## Reglas de operación
+
+- **Solo-lectura primero.** El default es diagnosticar.
+- **Confirmación explícita antes de cualquier cambio de estado**: borrar,
+  reiniciar, apagar, deployar, editar red/storage, actualizar paquetes o
+  modificar servicios. Para acciones riesgosas, captura el estado actual y
+  enuncia el rollback antes de actuar.
+- **Prefiere los scripts del repo** antes que comandos manuales largos.
+- **Nunca registres tokens, passwords ni claves privadas en Markdown.**
+
+La versión completa y vinculante está en la §6 del
+[índice de herramientas](docs/TOOL-INDEX.md).