urieljareth
f587a8baa2
- scripts/Invoke-CloudflareApi.ps1: control de tunnel/DNS via API - scripts/Install-CoolifyAutostart.ps1 + scripts/host/: autostart de LXC 102 + tunnel tras corte - scripts/Apply-ChatwootEnterprisePatch.ps1: parche enterprise (autodetecta creds) - Deploy-SoloLeveling.ps1: deploy build-on-server verificado - docs/runbooks/cloudflare-tunnel.md y autostart-coolify.md - docs/casos/chatwoot-enterprise-patch.md (credenciales redactadas) - docs/AGENTS-coolify-apps.md + issues y reportes - deploy_skill/references/coolify-4.1.2-notes.md: hallazgos verificados (seccion 7) - package.json para verify-online.mjs del coolify-deploy skill - .gitignore: excluye .claude/ y .opencode/ (config local de herramientas)
122 lines
8.1 KiB
Markdown
122 lines
8.1 KiB
Markdown
# 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 ...`.
|
|
- **The deploy pipeline** ([deploy_skill/](deploy_skill/)) is the end-to-end path from "local project" to "live on `*.urieljareth.org`": scaffold compliant Dockerfile/compose → pre-deploy checklist → create GitHub repo → push → register + deploy via Coolify API → verify. It also covers rollback. Requires `GITHUB_TOKEN` + `COOLIFY_TOKEN` in `.env.local.ps1`; `git push` uses Windows Credential Manager (`wincred`), verified for the `urieljarethbusiness-cpu` GitHub account. See [deploy_skill/SKILL.md](deploy_skill/SKILL.md) and [docs/AGENTS-coolify-apps.md](docs/AGENTS-coolify-apps.md).
|
|
|
|
## 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
|
|
|
|
# Cloudflare API (requires CLOUDFLARE_API_TOKEN) — full tunnel/DNS control
|
|
.\scripts\Invoke-CloudflareApi.ps1 -Path "/user/tokens/verify"
|
|
```
|
|
|
|
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.
|
|
|
|
## Deploying a new project to Coolify
|
|
|
|
End-to-end pipeline (scaffold → checklist → GitHub repo → push → Coolify app +
|
|
deploy → verify). Requires `GITHUB_TOKEN` and `COOLIFY_TOKEN` in
|
|
`.env.local.ps1`. `git push` uses Windows Credential Manager, not the PAT.
|
|
|
|
```powershell
|
|
. .\.env.local.ps1
|
|
|
|
# Full pipeline on a local project
|
|
.\deploy_skill\scripts\Publish-ProjectToCoolify.ps1 `
|
|
-AppPath .\my-app -AppName my-app `
|
|
-Fqdn https://my-app.urieljareth.org `
|
|
-Stack node -AppPort 8080 -Init
|
|
|
|
# Or step-by-step
|
|
.\deploy_skill\scripts\Initialize-CoolifyProject.ps1 -Path .\my-app -Stack node
|
|
.\deploy_skill\scripts\Test-PreDeployChecklist.ps1 -Path .\my-app -Strict
|
|
.\deploy_skill\scripts\New-GitHubRepo.ps1 -Name my-app
|
|
.\deploy_skill\scripts\New-CoolifyApplication.ps1 -RepoUrl https://github.com/urieljarethbusiness-cpu/my-app.git `
|
|
-Fqdn https://my-app.urieljareth.org -PortsExposes 8080
|
|
.\deploy_skill\scripts\Test-PostDeploy.ps1 -Fqdn https://my-app.urieljareth.org -ContainerName my-app-main
|
|
|
|
# Rollback to a previous commit
|
|
.\deploy_skill\scripts\Invoke-CoolifyRollback.ps1 -AppPath .\my-app -ApplicationUuid <uuid> -CommitSha <sha>
|
|
```
|
|
|
|
## 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`, `cloudflare-tunnel.md`, `autostart-coolify.md` (power-outage auto-start of LXC 102 + tunnel), plus app-specific `nextcloud.md` and `baserow.md`.
|
|
- Cloudflare tunnel: the tunnel is **dashboard-managed** (ingress comes from the edge, see `INF Updated to new configuration version=N` in `cloudflared` logs) — fix routes in the dashboard or via [scripts/Invoke-CloudflareApi.ps1](scripts/Invoke-CloudflareApi.ps1), not by editing files on the host. Ports 6001/6002 must use `http://`. See [docs/runbooks/cloudflare-tunnel.md](docs/runbooks/cloudflare-tunnel.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.
|
|
- [docs/AGENTS-coolify-apps.md](docs/AGENTS-coolify-apps.md) — compatibility guide for agents **developing** an app to deploy on this Coolify instance (networking, ports, domains/TLS, env, volumes, healthchecks) + pre-deploy checklist. Source this when building a new app, not when operating an existing one.
|
|
- [deploy_skill/SKILL.md](deploy_skill/SKILL.md) + [deploy_skill/TOOLS.md](deploy_skill/TOOLS.md) — deploy pipeline skill (scaffold → push → Coolify API → verify → rollback).
|
|
- `PROXMOX/`, `proxmox-agent/`, `proxmox-skill/` are **legacy pointer folders** — they only redirect to the live docs above. Don't add content there.
|