docs: add semantics.md — the apply contract and Coolify 4.1.2 limits #2

Merged

dan-claude-bot merged 1 commit from docs/semantics into main

2026-07-11 13:16:16 +00:00

dan-claude-bot commented

2026-07-11 13:13:22 +00:00

(Migrated from github.com)

Fixes a gap I introduced in #1. docs/semantics.md was written after that PR's commit was already pushed, so it never landed — while heavy-duty/infra#2 removed the same content from that repo's README on the assumption it had. Between the two merges, these notes survived only in git history.

They're the expensive part of the executor, and the part that is genuinely hard to reconstruct:

apply guarantees — never deletes; never recreates a database; fails loudly naming the field rather than recreating on un-updatable drift; always ends a mutated resource with a redeploy (API writes land in Coolify's DB, not in running containers); one-way, manifest → Coolify.
The dockercompose build pack — service_domains map vocabulary, the wire translation to {name, domain}, and why a compose app's create must set connect_to_docker_network.
Hostname-overlay shapes for compose vs plain apps.
Known limitations, not defects — backup schedules are create-time only; a service's domains cannot be set via the 4.1.2 API; the redis default image tag is an unverified extrapolation.

Each Coolify claim is cited against coollabsio/coolify v4.1.2 source and the vendored OpenAPI in reference/ — because the published OpenAPI is wrong or silent in exactly the places that matter (it documents docker_compose_domains as a nullable string on read but an array on write, and describes the bulk-env endpoint in a way that would make apply's never-delete rule unsafe if believed).

Linked from the README so it's found before someone changes apply.

**Fixes a gap I introduced in #1.** `docs/semantics.md` was written *after* that PR's commit was already pushed, so it never landed — while `heavy-duty/infra#2` removed the same content from that repo's README on the assumption it had. Between the two merges, these notes survived only in git history. They're the expensive part of the executor, and the part that is genuinely hard to reconstruct: - **`apply` guarantees** — never deletes; never recreates a database; fails loudly naming the field rather than recreating on un-updatable drift; always ends a mutated resource with a redeploy (API writes land in Coolify's DB, not in running containers); one-way, manifest → Coolify. - **The `dockercompose` build pack** — `service_domains` map vocabulary, the wire translation to `{name, domain}`, and why a compose app's create must set `connect_to_docker_network`. - **Hostname-overlay shapes** for compose vs plain apps. - **Known limitations, not defects** — backup schedules are create-time only; a service's `domains` cannot be set via the 4.1.2 API; the redis default image tag is an unverified extrapolation. Each Coolify claim is cited against `coollabsio/coolify` v4.1.2 source and the vendored OpenAPI in `reference/` — because the *published* OpenAPI is wrong or silent in exactly the places that matter (it documents `docker_compose_domains` as a nullable string on read but an array on write, and describes the bulk-env endpoint in a way that would make `apply`'s never-delete rule unsafe if believed). Linked from the README so it's found before someone changes `apply`.

No reviewers

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: heavy-duty/cast#2

No description provided.