116 lines
5.2 KiB
Markdown
116 lines
5.2 KiB
Markdown
# Proxmox & Coolify Manager
|
|
|
|
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 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-08-29** desde esta máquina:
|
|
|
|
- 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
|
|
|
|
```
|
|
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
|
|
```
|
|
|
|
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
|
|
Copy-Item .env.example .env.local.ps1
|
|
```
|
|
|
|
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"
|
|
```
|
|
|
|
Para la verificación operativa con navegador (`Test-ServiceOnline.ps1`) hace
|
|
falta Node: `npm install` una vez en la raíz del repo.
|
|
|
|
## 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).
|