147 lines
5.6 KiB
Markdown
147 lines
5.6 KiB
Markdown
# Coolify Tooling
|
|
|
|
All commands assume PowerShell from the project root.
|
|
|
|
> **Canonical catalog:** [`docs/TOOL-INDEX.md`](../docs/TOOL-INDEX.md). This file
|
|
> holds usage examples; the index holds verified signatures, env requirements,
|
|
> read-only/mutating classification and the gotchas. Read its §1 first.
|
|
|
|
## Two gotchas specific to this wrapper
|
|
|
|
**1. `-Raw` is inverted.** `Invoke-CoolifyApi.ps1` returns a **JSON string** by
|
|
default and **PowerShell objects with `-Raw`**. Filtering the default output
|
|
silently yields nothing — no error:
|
|
|
|
```powershell
|
|
# WRONG: $r is a System.String, so this prints an empty row
|
|
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/resources" | Select-Object name, uuid
|
|
|
|
# RIGHT
|
|
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/resources" -Raw | Select-Object name, uuid
|
|
```
|
|
|
|
**2. `/applications/*` 404s through the public hostname — that block is
|
|
Cloudflare's, not Coolify's** (re-verified 2026-08-29 on v4.3.14: same token,
|
|
same route → 200 against the origin `http://192.168.0.117:8000/api/v1`, 404 via
|
|
`https://coolify.urieljareth.org`). For those endpoints use
|
|
`$env:COOLIFY_API_URL_ORIGIN`. Also: state-changing endpoints are POST-only
|
|
since v4.2 (`GET /deploy` → 405). Endpoints that work through either path:
|
|
`/version`, `/resources`, `/services`, `/databases`, `/projects`, `/servers`,
|
|
`/teams`, `/deployments`. Use `/resources` to enumerate apps.
|
|
|
|
## Environment
|
|
|
|
Load private values from an ignored local file:
|
|
|
|
```powershell
|
|
. .\.env.local.ps1
|
|
```
|
|
|
|
Expected variables:
|
|
|
|
```powershell
|
|
$env:COOLIFY_API_URL = "https://coolify.urieljareth.org/api/v1"
|
|
$env:COOLIFY_TOKEN = "REPLACE_WITH_TOKEN"
|
|
```
|
|
|
|
## Read-Only Diagnostics
|
|
|
|
```powershell
|
|
.\scripts\Test-ProxmoxConnection.ps1
|
|
.\coolify_skill\scripts\Get-CoolifyDockerStatus.ps1 -All
|
|
.\coolify_skill\scripts\Get-CoolifyDockerStatus.ps1 -Filter "coolify|cloudflared|nextcloud|postgres|redis"
|
|
```
|
|
|
|
```powershell
|
|
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker stats --no-stream"
|
|
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker network ls"
|
|
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker volume ls"
|
|
```
|
|
|
|
## A New Service Is Green In Coolify But Its Domain Returns 503
|
|
|
|
Coolify's green dot means the container is `running`. Traefik only routes a
|
|
container Docker reports `healthy`. A brand-new service is `running` long before
|
|
it is `healthy`, so its route does not exist yet and the request falls through to
|
|
Coolify's catch-all (`noop` service, empty server list) — which is what prints
|
|
`no available server`.
|
|
|
|
```powershell
|
|
# Contrast running vs healthy, flag a too-short start_period, probe the domain.
|
|
.\coolify_skill\scripts\Test-CoolifyServiceReady.ps1 -Uuid <resource-uuid>
|
|
|
|
# First boot on this host can take minutes (HDD-backed loopback rootfs). Wait it out.
|
|
.\coolify_skill\scripts\Test-CoolifyServiceReady.ps1 -Uuid <resource-uuid> -WaitSeconds 600
|
|
```
|
|
|
|
Read the status code before changing anything:
|
|
|
|
- `502 Bad Gateway` — the route exists, the backend refuses. App or port problem.
|
|
- `503 no available server` — there is no route. Usually still starting.
|
|
**Do not redeploy**: that restarts the entrypoint from scratch and restarts the
|
|
slow boot. See TOOL-INDEX.md 1.5.
|
|
|
|
## Logs And Inspect
|
|
|
|
```powershell
|
|
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker logs <container> --tail 100"
|
|
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker inspect <container>"
|
|
```
|
|
|
|
## Coolify API
|
|
|
|
Verified working on this instance (2026-08-07):
|
|
|
|
```powershell
|
|
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/version"
|
|
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/resources" # 28 — the app inventory
|
|
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/projects" # 7
|
|
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/services" # 14
|
|
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/databases" # 5
|
|
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/servers" # 1
|
|
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/teams" # 1
|
|
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/deployments" # in-flight deploys
|
|
```
|
|
|
|
**`/applications` and its whole namespace 404 through the public hostname
|
|
(Cloudflare edge block) but work via the origin** — point
|
|
`COOLIFY_API_URL` at `http://192.168.0.117:8000/api/v1` for those calls. Either
|
|
way, to enumerate applications and resolve a name or uuid, `/resources` is the
|
|
reliable inventory:
|
|
|
|
```powershell
|
|
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/resources" -Raw |
|
|
Where-Object { $_.name -match 'chatwoot' } | Select-Object name, uuid, fqdn
|
|
```
|
|
|
|
### Resolving a container name from a resource
|
|
|
|
Container names are `<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>"
|
|
```
|
|
|
|
For write calls, prepare the JSON body first and ask for confirmation:
|
|
|
|
```powershell
|
|
$body = @{ name = "example" } | ConvertTo-Json -Depth 20
|
|
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Method POST -Path "/projects" -BodyJson $body
|
|
```
|
|
|
|
## API Reference Search
|
|
|
|
```powershell
|
|
rg -n "applications|deploy|database|environment" .\coolify_skill\references
|
|
Get-Content .\coolify_skill\references\ops\list-applications.md
|
|
Get-Content .\coolify_skill\references\ops\deploy-by-tag-or-uuid.md
|
|
```
|
|
|
|
## Commands That Require Confirmation
|
|
|
|
- Coolify deploys and API writes: `POST`, `PUT`, `PATCH`, `DELETE`.
|
|
- Docker lifecycle: `restart`, `stop`, `rm`, `compose up`, `compose down`.
|
|
- Environment variable writes or full env exports.
|
|
- Key, token, SSH, domain, proxy, server, network, or volume changes.
|