Commit inicial - estructura base del proyecto
This commit is contained in:
@@ -0,0 +1,87 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## What this repo is
|
||||
|
||||
This is **not an application codebase**. It is an operations toolkit: PowerShell
|
||||
wrapper scripts plus context/runbook documentation that let an agent diagnose and
|
||||
manage a single local Proxmox host (`192.168.0.200`, node `thinkcentre`) and the
|
||||
self-hosted Coolify stack running inside its LXC `102`. There is no build, lint,
|
||||
or test step — the "commands" are the operational scripts in `scripts/` and
|
||||
`coolify_skill/scripts/`.
|
||||
|
||||
User-facing docs are in Spanish; scripts and skill files are in English.
|
||||
|
||||
## Core architecture
|
||||
|
||||
**Everything reaches the host through one SSH path.** There is no direct Docker or
|
||||
local network access. The layering is:
|
||||
|
||||
```
|
||||
PowerShell script → Invoke-ProxmoxSshCommand (scripts/ProxmoxAgent.ps1)
|
||||
→ ssh [email protected]
|
||||
→ pct exec 102 -- docker ... (for any Docker/Coolify container work)
|
||||
```
|
||||
|
||||
- [scripts/ProxmoxAgent.ps1](scripts/ProxmoxAgent.ps1) is the shared library. **Dot-source it** (`. .\scripts\ProxmoxAgent.ps1`) to get `Get-ProxmoxConfig`, `Invoke-ProxmoxSshCommand`, and `Invoke-ProxmoxApi`. Every other script dot-sources it rather than reimplementing connection logic.
|
||||
- **Config resolution:** `Get-ProxmoxConfig` reads env vars (`PROXMOX_HOST`, `PROXMOX_NODE`, `PROXMOX_SSH_KEY`, `PROXMOX_COOLIFY_LXC`, etc.) and falls back to hardcoded local defaults. SSH works with defaults alone; **API calls require `PROXMOX_API_TOKEN_ID` + `PROXMOX_API_TOKEN_SECRET`** (otherwise `Invoke-ProxmoxApi` throws). The Coolify LXC ID (`102`) comes from config — don't hardcode it in new scripts; use `$config.CoolifyLxc`.
|
||||
- Two independent APIs: the **Proxmox REST API** (via `curl.exe -k`, PVE token header) and the **Coolify API** (via `Invoke-RestMethod`, Bearer token, base `https://coolify.urieljareth.org/api/v1`). They use different scripts and different env vars.
|
||||
- Docker is **not** managed on the Proxmox host directly — it lives inside LXC `102`. Any container command must be wrapped as `pct exec 102 -- docker ...`.
|
||||
|
||||
## Common commands
|
||||
|
||||
Run from the project root in PowerShell.
|
||||
|
||||
```powershell
|
||||
# Load private secrets (gitignored) — needed for any API call
|
||||
. .\.env.local.ps1
|
||||
|
||||
# Smoke test: config + SSH read + Docker sample + API auth (exits 1 on any FAIL)
|
||||
.\scripts\Test-ProxmoxConnection.ps1
|
||||
|
||||
# Full inventory snapshot (host, LXC, QEMU, Docker in LXC 102)
|
||||
.\scripts\Get-ProxmoxInventory.ps1
|
||||
|
||||
# Arbitrary read-only SSH command
|
||||
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct list"
|
||||
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker ps -a"
|
||||
|
||||
# Proxmox REST API (after env token loaded)
|
||||
. .\scripts\ProxmoxAgent.ps1
|
||||
Invoke-ProxmoxApi -Path "/version"
|
||||
|
||||
# Coolify container status through LXC 102
|
||||
.\coolify_skill\scripts\Get-CoolifyDockerStatus.ps1 -All
|
||||
|
||||
# Coolify API (requires COOLIFY_TOKEN)
|
||||
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/projects"
|
||||
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Method POST -Path "/projects" -BodyJson $body
|
||||
```
|
||||
|
||||
For the Coolify API reference: don't read the whole tree. Search
|
||||
`coolify_skill/references/` with `rg`, then open the single matching
|
||||
`references/ops/*.md` operation file.
|
||||
|
||||
## Operating rules (enforced by the skills — follow them)
|
||||
|
||||
- **Read-only first.** Default to diagnostics: list, status, logs, inspect, health checks.
|
||||
- **Confirm before any state change.** Explicitly ask the user before: `pct`/`qm` start/stop/reboot/destroy; `docker` restart/stop/rm/compose up/down; Coolify deploys or any `POST`/`PUT`/`PATCH`/`DELETE`; env-var writes; and any firewall/network/storage/volume/key/token change. For risky actions, capture current state and state the rollback path first.
|
||||
- **Never write secrets into the repo.** No tokens, passwords, private keys, cookies, or PVE token secrets in Markdown, scripts, or logs. Secrets live only in `.env.local.ps1` (gitignored) or the OS secret store. `.gitignore` also blocks `ACCESS.md`, `*.key`, `*.pem`, `*.crt`, etc. When debugging databases, verify connectivity without echoing credentials.
|
||||
- **Prefer repo scripts over long manual command strings**, and don't run broad destructive commands built from generated strings.
|
||||
|
||||
## Docker networking gotcha
|
||||
|
||||
When a Coolify app and its database are sibling containers on the same Docker
|
||||
network, the app must reach the DB by its **Docker service name, not `localhost`**
|
||||
(e.g. Nextcloud uses host `nextcloud-db`). Service-to-service DNS is the usual
|
||||
root cause of "database connection" failures here — check with
|
||||
`pct exec 102 -- docker exec <app> getent hosts <service-name>`.
|
||||
|
||||
## Where context lives
|
||||
|
||||
- [docs/proxmox-inventory.md](docs/proxmox-inventory.md) — verified topology, LXC list, observed containers, access model. Treat as the source of truth for current state.
|
||||
- [docs/runbooks/](docs/runbooks/) — concrete procedures: `conexion.md`, `diagnostico.md`, `coolify-docker.md`, `seguridad.md`, plus app-specific `nextcloud.md` and `baserow.md`.
|
||||
- [agent/SKILL.md](agent/SKILL.md) + [agent/TOOLS.md](agent/TOOLS.md) — Proxmox agent operating skill.
|
||||
- [coolify_skill/SKILL.md](coolify_skill/SKILL.md) + [coolify_skill/TOOLS.md](coolify_skill/TOOLS.md) — Coolify agent operating skill and API reference index.
|
||||
- `PROXMOX/`, `proxmox-agent/`, `proxmox-skill/` are **legacy pointer folders** — they only redirect to the live docs above. Don't add content there.
|
||||
Reference in New Issue
Block a user