urieljareth/Proxmox-Coolify-Manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Actualiza toolkit operativo y documentación

Browse Source
This commit is contained in:
urieljareth
2026-09-10 20:53:50 -06:00
parent 3b7209dcc1
commit 714057bfc8
69 changed files with 6023 additions and 384 deletions
Download Patch File Download Diff File Expand all files Collapse all files
agent/SKILL.md
+17 -8
View File
@@ -4,18 +4,27 @@ Use this project-local skill when helping manage the local Proxmox host.
## Scope
- Host: `192.168.0.200`
- Host: `192.168.0.200`, Proxmox VE `9.1.1`, single node
- Node: `thinkcentre`
- Main Docker LXC: `102` (`coolify`)
- Secondary LXC currently observed: `100` (`hermes`)
- Access methods: SSH first, Proxmox REST API when token env vars are present.
- Main Docker LXC: `102` (`coolify`) — **running**, 68 containers
- Secondary LXC: `100` (`hermes`) — **running** (commit `5d3c15aaa`, MiniMax-M3, IPs: `192.168.3.23` / `192.168.3.15`)
- No QEMU VMs
- Access methods: SSH first, Proxmox REST API when token env vars are present
(they are **not** loaded today — see [`TOOLS.md`](TOOLS.md))
## Startup routine
1. Read `README.md`, `docs/proxmox-inventory.md`, and the relevant runbook.
2. Run `.\scripts\Test-ProxmoxConnection.ps1` before operational work.
3. For fresh state, run `.\scripts\Get-ProxmoxInventory.ps1`.
4. Prefer `.\scripts\Invoke-ProxmoxSsh.ps1 -Command "<command>"` for remote commands.
1. Load secrets: `. .\.env.local.ps1`.
2. Read [`docs/TOOL-INDEX.md`](../docs/TOOL-INDEX.md) — the canonical tool
catalog. **Its §1 lists four gotchas that produce silently wrong results.**
The one that bites hardest here: `Invoke-ProxmoxSsh.ps1` mangles nested
quotes, so anything with two levels of quoting needs base64 (see
[`TOOLS.md`](TOOLS.md)).
3. Read [`docs/proxmox-inventory.md`](../docs/proxmox-inventory.md) for current
state, plus the relevant runbook in `docs/runbooks/`.
4. Run `.\scripts\Test-ProxmoxConnection.ps1` before operational work.
5. For fresh state, run `.\scripts\Get-ProxmoxInventory.ps1`.
6. Prefer `.\scripts\Invoke-ProxmoxSsh.ps1 -Command "<command>"` for remote commands.
## Safety policy
agent/TOOLS.md
+107 -15
View File
@@ -1,26 +1,34 @@
# Tooling
# Tooling — Proxmox host
All commands assume PowerShell from the project root.
> **Canonical catalog:** [`docs/TOOL-INDEX.md`](../docs/TOOL-INDEX.md) — verified
> signatures, env requirements, and read-only/mutating classification for every
> script in the repo. This file holds the host-level usage patterns.
## Environment
```powershell
. .\.env.local.ps1
```
If no private env file is loaded, SSH still uses the local defaults from
Without a private env file, SSH still works from the hardcoded defaults in
`scripts/ProxmoxAgent.ps1`. API calls require token env vars.
## Smoke test
> **Status of `.env.local.ps1` (2026-08-29):** `PROXMOX_API_TOKEN_ID`
> (`root@pam!openclaw`, verified 200 against `/version` and
> `/cluster/resources`), `PROXMOX_API_TOKEN_SECRET`, `COOLIFY_EMAIL`,
> `COOLIFY_PASSWORD` (probable — unverified) and a working `GITHUB_TOKEN`
> (extracted from Windows Credential Manager after the old PAT expired) are all
> loaded. The Proxmox REST API, the Coolify API and GitHub work. Only
> `CLOUDFLARE_API_TOKEN` is still missing — tunnel changes go through the
> Cloudflare dashboard.
## Smoke test and inventory
```powershell
.\scripts\Test-ProxmoxConnection.ps1
```
## Inventory
```powershell
.\scripts\Get-ProxmoxInventory.ps1
.\scripts\Test-ProxmoxConnection.ps1 # config + SSH + Docker sample + API auth; exits 1 on FAIL
.\scripts\Get-ProxmoxInventory.ps1 # host, LXC, QEMU, Docker in LXC 102
```
## SSH wrapper
@@ -31,7 +39,49 @@ If no private env file is loaded, SSH still uses the local defaults from
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker ps -a"
```
## API from a PowerShell session
### ⚠️ Nested quotes get mangled — use base64
`Invoke-ProxmoxSshCommand` passes `$Command` as a single argument to `ssh`, and
PowerShell 5.1 destroys embedded quotes when calling a native executable. A
command with two levels of quoting arrives corrupted (`bash: line 1: -c: command
not found`). Encode it instead:
```powershell
$remote = @'
pct exec 102 -- docker exec -i <db-container> bash -lc 'PGPASSWORD="$POSTGRES_PASSWORD" psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -At -c "SELECT 1"'
'@
$b64 = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($remote))
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "echo $b64 | base64 -d | bash 2>&1"
```
The single-quoted here-string `@'...'@` is required so PowerShell does not expand
`$POSTGRES_PASSWORD` on the Windows side. Single-level quoting
(`docker ps --format '{{.Names}}'`) works through the plain wrapper.
## Safe read-only commands
```powershell
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "hostname && pveversion && uname -r && uptime"
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct list && qm list"
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "df -h / && free -h"
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pvesh get /cluster/resources"
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "systemctl --failed"
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'"
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker stats --no-stream"
```
## Resolving a container name
Coolify names containers `<service>-<uuid>` plus an optional build suffix, so they
are **not guessable and change when a redeploy recreates the container**:
```powershell
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker ps --format '{{.Names}}' | grep -i <app>"
```
## Proxmox REST API from a PowerShell session
Requires `PROXMOX_API_TOKEN_ID` + `PROXMOX_API_TOKEN_SECRET`; throws without them.
```powershell
. .\scripts\ProxmoxAgent.ps1
@@ -40,9 +90,51 @@ Invoke-ProxmoxApi -Path "/nodes"
Invoke-ProxmoxApi -Path "/cluster/resources"
```
## Cloudflare API — tunnel and DNS
Requires `CLOUDFLARE_API_TOKEN`. `GET` is read-only; everything else mutates.
`-Raw` returns objects, the default returns a JSON string.
```powershell
.\scripts\Invoke-CloudflareApi.ps1 -Path "/user/tokens/verify"
```
The tunnel is **dashboard-managed** — fix routes there or via this API, never by
editing files on the host. See [`docs/runbooks/cloudflare-tunnel.md`](../docs/runbooks/cloudflare-tunnel.md).
## Host automation
```powershell
# Power-outage auto-start of LXC 102 + tunnel. Audit without touching anything:
.\scripts\Install-CoolifyAutostart.ps1 -VerifyOnly
```
Installed on the host: `coolify-autostart.service` (systemd, **enabled**) and the
Chatwoot guard at `/root/scripts/chatwoot-enterprise-guard.sh`, scheduled by
`/etc/cron.d/chatwoot-enterprise-guard` every 5 minutes.
## Chatwoot enterprise licence
```powershell
.\scripts\Get-ChatwootLicenseStatus.ps1 -Deep # read-only diagnosis
.\scripts\Apply-ChatwootEnterprisePatch.ps1 -DryRun -ReenableAccountFeatures # preview the repair
```
Full context: [`docs/runbooks/chatwoot-update.md`](../docs/runbooks/chatwoot-update.md).
## Per-app deploy helpers
`scripts/apps/` holds app-specific one-off deploy scripts with hardcoded uuids
and domains — e.g. `Deploy-SoloLeveling.ps1`, which builds the image on the
server to work around a private GHCR without `read:packages`. Read the header
before running one; they are **mutating** and tied to a specific resource.
## Commands that require confirmation
- `pct start`, `pct shutdown`, `pct reboot`, `pct stop`, `pct destroy`
- `qm start`, `qm shutdown`, `qm reboot`, `qm stop`, `qm destroy`
- `docker restart`, `docker stop`, `docker rm`, `docker compose up/down`
- package updates, firewall edits, network edits, storage edits
- `pct start|shutdown|reboot|stop|destroy`
- `qm start|shutdown|reboot|stop|destroy`
- `docker restart|stop|rm|compose up|compose down`
- Package updates, firewall edits, network edits, storage edits
- Any Cloudflare write (`POST`/`PUT`/`PATCH`/`DELETE`)
- `Install-CoolifyAutostart.ps1` without `-VerifyOnly`
- `Apply-ChatwootEnterprisePatch.ps1` without `-DryRun`