# 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).