feat: cast — the Coolify executor, extracted from the infra state repo
Public tool, private state. cast holds no hostnames, no bindings, no
secrets: it joins a product repo's .infra/ manifest with a state directory
you point it at, and makes Coolify match.
Extracted from heavy-duty/infra, which was half tool and half state — the
inconsistency that made it impossible to say whether "infra" named a CLI
or a runbook. rig builds the boxes; cast fills them; infra is what they
are filled with.
Two changes were required to make it genuinely stateless and publishable:
- The implicit cwd contract (environments.yaml / secrets/ / .coolify.env
resolved against the working directory, silently reading the wrong file
from the wrong place) is now an explicit --state <dir> / $CAST_STATE.
- BANNED_IN_PROD — a hardcoded list of one product's ALLOW_* flags, the
only product knowledge in the executor — becomes the generic, operator-
owned environments.<env>.forbidden_var_patterns. The guard now lives in
private state, so a product-side change cannot lower its own guard, and
it is a pattern rather than a list, so it catches unforeseen siblings.
Age identities resolve as $CAST_AGE_KEY_FILE_<ENV> then
~/.config/cast/age-<env>.key — which is the entire attended-vs-unattended
apply mechanism, with no environment names known to the tool.
Instance identity (org names, the GitHub App name, founder domains) is out
of the fixtures and out of register-github-app.sh, which took APP_NAME and
ORG as arguments rather than baking them in.
69 tests green; bin/cast + curl installer mirror rig's shape.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-11 12:25:44 +00:00
|
|
|
# API reference (pinned)
|
|
|
|
|
|
|
|
|
|
`coolify-openapi-4.1.2.json` is the OpenAPI spec at the pinned Coolify tag.
|
|
|
|
|
The executor is written against THIS file plus controller behavior verified
|
|
|
|
|
2026-07-10 (the published spec omits `is_buildtime`/`is_runtime` on env
|
|
|
|
|
write endpoints; the controllers accept them — `infra smoke` guards this).
|
|
|
|
|
On any Coolify upgrade: re-vendor at the new tag, diff, re-run `infra smoke`.
|
|
|
|
|
|
|
|
|
|
## Known gap: S3 storage destinations have no API surface (verified 2026-07-10)
|
|
|
|
|
|
|
|
|
|
Coolify 4.1.2 exposes **no endpoint at all** — not list, not create, not
|
|
|
|
|
read — for S3 storage destinations (the backup-target resource referenced
|
|
|
|
|
by `s3_storage_uuid` on database-backup payloads). Verified two ways:
|
|
|
|
|
|
|
|
|
|
- The vendored spec has zero `/storages`-as-a-resource paths; the only
|
|
|
|
|
`storages` paths are `/applications/{uuid}/storages`,
|
|
|
|
|
`/databases/{uuid}/storages`, `/services/{uuid}/storages` — these are
|
|
|
|
|
per-resource Docker volume mounts, a different Coolify concept.
|
|
|
|
|
- Upstream `routes/api.php` at tag `v4.1.2` imports only these Api
|
|
|
|
|
controllers: Applications, CloudProviderTokens, Databases, Deploy,
|
|
|
|
|
Github, Hetzner, Other, Project, Resources, ScheduledTasks, Security,
|
|
|
|
|
Sentinel, Servers, Services, Team. There is no Storage/S3 controller —
|
|
|
|
|
the route table has zero routes matching `storage` or `s3` outside the
|
|
|
|
|
three per-resource-type volume-mount groups above.
|
|
|
|
|
|
|
|
|
|
S3 storage destinations are UI-only in this Coolify version (Settings → S3
|
|
|
|
|
Storages). No S3 storage API exists in 4.1.2 — the destination UUID is
|
|
|
|
|
recorded in environments.yaml by the bootstrap runbook; the client
|
|
|
|
|
deliberately has no storage resolver. Re-check on any Coolify upgrade
|
|
|
|
|
re-vendor.
|
feat: place a resource on a destination — and a state file that can say which (#21)
A destination is the Docker network a resource is created on. cast never sent
one, so everything landed on the server's default — invisible and harmless while
each server hosts one project, and neither the moment a server hosts two.
The state file had nowhere to say otherwise, either. A destination is scoped
project × environment, and `environments.<env>` is scoped by environment alone:
a `destination:` key there would mean "one network shared by every project in
this environment", which is the isolation it is meant to provide, inverted.
So:
- `environments.<env>.projects.<repo>` — per-project state, keyed by repo, full
`<org>/<repo>` slug first with a bare-`<repo>` fallback, exactly like
`github_apps`. It carries `destination_uuid` and `smoke_target`.
- `smoke_target` moves there. It was state-file-scoped: it named ONE project's
app (`core`) from a key that could not tell two projects apart — or even prod's
app from staging's. The old key is still read (with a warning), so an unmigrated
state file keeps smoking, and `cast smoke` now takes an optional `<org>/<repo>`.
- `apply` sends `destination_uuid` on create, for applications, databases and
services alike — Coolify runs identical destination logic in all three.
The API turns out to be worse than the issue assumed, in a way that changes what
"diff should compare the destination" can honestly mean. Verified against
coollabsio/coolify v4.1.2 (routes/api.php + the three Api controllers), and
written up in reference/README.md:
- There is NO destinations API. Zero routes. A destination cannot be listed, read
or resolved by name — only a raw UUID from the UI identifies one, exactly as
with `s3_destination`. Hence `destination_uuid:` and not `destination:`.
- The field is WRITE-ONLY. Coolify takes `destination_uuid` on write and returns
`destination_id` (an integer PK) on read, with nothing mapping between them.
- On a server with >1 destination, a create that OMITS it is a hard 400. So cast
could not deploy onto a shared box at all — it did not silently misplace there,
it simply failed. On a single-destination server the uuid is ignored entirely
and never validated, so a wrong one is invisible until a second one exists.
A declared UUID therefore cannot be verified against the resource it was sent
for — by cast or by anything else. Diffing it as a field would compare a UUID to
an int and report drift that never clears, so it is reported rather than compared,
and the limit is stated out loud: every diff that declares a destination says it
did not verify it. Silence would make an unverified setting read as a verified
one, which is the failure shape #12/#14/#17/#18 are all about.
What IS comparable is the live side to itself. `diff` groups live resources by the
`destination_id` Coolify does report, and a project whose resources do not all
share one network is drift — non-clean, both sides named, and never repaired
(apply moves nothing between networks). That catches the thing actually worth
catching, including on a box whose destinations were made by hand.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-13 19:31:02 +00:00
|
|
|
|
|
|
|
|
## Known gap: a resource's destination is write-only (verified 2026-07-13)
|
|
|
|
|
|
|
|
|
|
The **destination** (the Docker network a resource is created on — a
|
|
|
|
|
`StandaloneDocker`, not the S3 thing above) can be *set* by the API and never
|
|
|
|
|
*read back*. Three separate facts, all verified at tag `v4.1.2`:
|
|
|
|
|
|
|
|
|
|
- **No destinations API at all.** `routes/api.php` has zero routes matching
|
|
|
|
|
`destination` — not list, not read, not create. So a destination name cannot
|
|
|
|
|
be resolved to anything; only a raw UUID, read out of the UI, identifies one.
|
|
|
|
|
(Same shape as the S3 gap above, same consequence: `environments.yaml` records
|
|
|
|
|
the UUID, and cast has no resolver.)
|
|
|
|
|
- **Write accepts `destination_uuid`** on create for applications
|
|
|
|
|
(`/applications/*`), all eight database types, and `/services`; and on PATCH
|
|
|
|
|
for applications and services.
|
|
|
|
|
- **Read returns `destination_id` + `destination_type`** — the integer primary
|
|
|
|
|
key and the morph class (`App\Models\StandaloneDocker`), never the UUID. They
|
|
|
|
|
survive serialization (none of the three controllers' `removeSensitiveData()`
|
|
|
|
|
hides them), but `ProjectController@environment_details` does not eager-load
|
|
|
|
|
the `destination` relation, and nothing else exposes it.
|
|
|
|
|
|
|
|
|
|
**Nothing maps an int to a UUID**, so a declared `destination_uuid` cannot be
|
|
|
|
|
compared against the live resource it was sent for. `diff` therefore *reports*
|
|
|
|
|
placement rather than comparing it (see `Placement` in `src/diff.ts`): it groups
|
|
|
|
|
live resources by `destination_id` — which is comparable to itself — so a
|
|
|
|
|
project whose resources do not all share one network is still caught, and it
|
|
|
|
|
says plainly that the declared UUID was not verified.
|
|
|
|
|
|
|
|
|
|
Coolify's own create-time behavior, identical in `ApplicationsController`
|
|
|
|
|
(~L1003), `DatabasesController` (~L1700) and `ServicesController` (~L378):
|
|
|
|
|
|
|
|
|
|
| server has | `destination_uuid` sent | result |
|
|
|
|
|
| --- | --- | --- |
|
|
|
|
|
| 0 destinations | anything | `400 Server has no destinations.` |
|
|
|
|
|
| exactly 1 | omitted | `$destinations->first()` — the default network |
|
|
|
|
|
| exactly 1 | **any value** | **ignored, never validated** — `first()` again |
|
|
|
|
|
| >1 | omitted | `400 Server has multiple destinations and you do not set destination_uuid.` |
|
|
|
|
|
| >1 | not on that server | `422 Provided destination_uuid does not belong to the specified server.` |
|
|
|
|
|
|
|
|
|
|
Two consequences worth keeping in mind. A **single-destination server silently
|
|
|
|
|
accepts a wrong UUID** — neither Coolify nor cast can catch that, and it is why
|
|
|
|
|
the declared value is never trusted as verified. And a **multi-destination
|
|
|
|
|
server rejects a create that omits it**, which is why cast could not deploy onto
|
|
|
|
|
a shared box at all until it could send this field.
|