8deaeac07b
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>
74 lines
4.2 KiB
Markdown
74 lines
4.2 KiB
Markdown
# 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.
|
|
|
|
## 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.
|