v4.2 upgrade tracker: settings as diffed fields, destinations resolver, read:sensitive token, OpenAPI re-vendor #77

New issue

Open

opened 2026-07-16 12:18:05 +00:00 by dan-claude-bot · 1 comment

dan-claude-bot commented

2026-07-16 12:18:05 +00:00

(Migrated from github.com)

Summary

Tracker for everything cast does when the box's Coolify moves from 4.1.2 to v4.2 (the next branch, release train coollabsio/coolify#10872). Per the #72 audit, v4.2 dissolves three of cast's manual-UI steps and changes the API's read semantics out from under the current client. Blocked until v4.2 is released and the box upgrades — nothing here is actionable against 4.1.2.

What v4.2 changes (verified on `upstream/next` as of 2026-07-16, `7d699818e`)

Application settings, read+write (34e6a6dd5): GET /applications/{uuid} returns a nested settings object (ApplicationSetting row minus ids/timestamps); create/PATCH accept ~13 more settings fields incl. include_source_commit_in_build, disable_build_cache, is_gzip_enabled, stop_grace_period, …
Destinations CRUD (coollabsio/coolify#10405): GET /destinations, GET/DELETE /destinations/{uuid}, GET/POST /servers/{server_uuid}/destinations. Create provisions the real Docker network on the host (StandaloneDocker created hook) and connects the proxy. Response carries the uuid that environments.yaml's destination_uuid needs.
Per-container service endpoints: GET/PATCH /services/{uuid}/applications/{app_uuid} (PATCH takes url → stored as fqdn), plus service-database endpoints (908b5cc09) and logs/start/stop per container.
Token abilities — the breaking one: reads of custom_labels, http_basic_auth_password, dockerfile, docker_compose(_raw), webhook secrets move behind read:sensitive/root token abilities, model-level (8b7dbbafb, 9a2c432c7). New routes are gated by api.ability:read/write middleware. A pre-upgrade token without these abilities silently loses fields on reads — cast must detect this, not guess.
Assorted: POST /{resource}/{uuid}/move (between environments), tags API, GET /databases|services/{uuid}/logs, backup executions list, docker_compose_domains populated for API-created compose apps (#9300).

Upgrade checklist (in order)

Re-vendor the OpenAPI spec at the new tag into reference/, diff against coolify-openapi-4.1.2.json, re-run infra smoke (the reference/README.md standing rule)
Mint/upgrade the API token with read:sensitive + write abilities; add a preflight that detects an under-privileged token instead of reading absent fields as absent state
Settings become diffed fields: include_source_commit_in_build (delete the dockercompose warn in resolve.ts ~L555), is_static un-degrades (verify per #70's remaining checklist — the response shape is a nested settings object, projectLiveFields predates it), and decide which other toggles enter the manifest vocabulary
Destinations resolver: create/enumerate via the new endpoints; environments.yaml destination_uuid stops being a hand-copied value; per-project network separation becomes a bootstrap act, not a UI act
Optionally move service hostname handling to the per-container PATCH (nicer errors than whole-urls replace — but #73 should already work on 4.1.2 and keeps working)
Re-check the two gaps that survive v4.2 and keep their UNCAPTURED rows: S3 storages API (none — unclaimed upstream, #72 feature-request 1) and backup S3-target readback (int s3_storage_id, #72 feature-request 2)

Refs

#72 (the audit) · #70 (is_static residuals) · #73 (service urls — 4.1.2-actionable, not gated on this) · #74 · #76

## Summary Tracker for everything cast does when the box's Coolify moves from 4.1.2 to v4.2 (the `next` branch, release train coollabsio/coolify#10872). Per the #72 audit, v4.2 dissolves three of cast's manual-UI steps and changes the API's read semantics out from under the current client. **Blocked until v4.2 is released and the box upgrades** — nothing here is actionable against 4.1.2. ## What v4.2 changes (verified on `upstream/next` as of 2026-07-16, `7d699818e`) 1. **Application settings, read+write** (`34e6a6dd5`): `GET /applications/{uuid}` returns a nested `settings` object (ApplicationSetting row minus ids/timestamps); create/PATCH accept ~13 more settings fields incl. `include_source_commit_in_build`, `disable_build_cache`, `is_gzip_enabled`, `stop_grace_period`, … 2. **Destinations CRUD** (coollabsio/coolify#10405): `GET /destinations`, `GET/DELETE /destinations/{uuid}`, `GET/POST /servers/{server_uuid}/destinations`. Create provisions the real Docker network on the host (StandaloneDocker `created` hook) and connects the proxy. Response carries the `uuid` that `environments.yaml`'s `destination_uuid` needs. 3. **Per-container service endpoints**: `GET/PATCH /services/{uuid}/applications/{app_uuid}` (PATCH takes `url` → stored as fqdn), plus service-database endpoints (`908b5cc09`) and logs/start/stop per container. 4. **Token abilities — the breaking one**: reads of `custom_labels`, `http_basic_auth_password`, `dockerfile`, `docker_compose(_raw)`, webhook secrets move behind `read:sensitive`/`root` token abilities, model-level (`8b7dbbafb`, `9a2c432c7`). New routes are gated by `api.ability:read/write` middleware. **A pre-upgrade token without these abilities silently loses fields on reads** — cast must detect this, not guess. 5. Assorted: `POST /{resource}/{uuid}/move` (between environments), tags API, `GET /databases|services/{uuid}/logs`, backup executions list, `docker_compose_domains` populated for API-created compose apps (#9300). ## Upgrade checklist (in order) - [ ] Re-vendor the OpenAPI spec at the new tag into `reference/`, diff against `coolify-openapi-4.1.2.json`, re-run `infra smoke` (the `reference/README.md` standing rule) - [ ] Mint/upgrade the API token with `read:sensitive` + write abilities; add a preflight that detects an under-privileged token instead of reading absent fields as absent state - [ ] Settings become **diffed fields**: `include_source_commit_in_build` (delete the dockercompose warn in `resolve.ts` ~L555), `is_static` un-degrades (verify per #70's remaining checklist — the response shape is a *nested* `settings` object, `projectLiveFields` predates it), and decide which other toggles enter the manifest vocabulary - [ ] Destinations resolver: create/enumerate via the new endpoints; `environments.yaml` `destination_uuid` stops being a hand-copied value; per-project network separation becomes a bootstrap act, not a UI act - [ ] Optionally move service hostname handling to the per-container PATCH (nicer errors than whole-`urls` replace — but #73 should already work on 4.1.2 and keeps working) - [ ] Re-check the two gaps that survive v4.2 and keep their UNCAPTURED rows: S3 storages API (none — unclaimed upstream, #72 feature-request 1) and backup S3-target readback (int `s3_storage_id`, #72 feature-request 2) ## Refs #72 (the audit) · #70 (is_static residuals) · #73 (service urls — 4.1.2-actionable, not gated on this) · #74 · #76

claude-bot-andresmgsl referenced this issue

2026-08-17 22:43:46 +00:00

Audit: every manual Coolify-UI step, verified against v4.1.2 and next — two claims refuted, two gaps survive into v4.2 #72

claude-bot-andresmgsl commented

2026-08-17 22:43:57 +00:00

Member

Triage status, 2026-08-17 — half the gate has resolved: Coolify v4.2.0 released 2026-07-21 (release tag; upstream is already at v4.3.1 as of 2026-08-12).

The tracker stays blocked: the condition is "v4.2 is released and the box upgrades", nothing on this board records the fleet moving off 4.1.2, and that upgrade is operator-owned infrastructure work outside this repo. Two things turn concrete now, worth having on record before the upgrade happens:

the checklist's first step has a real target — re-vendor the OpenAPI spec at v4.2.0 (or whichever tag the fleet actually adopts, upstream is past it already) and diff against coolify-openapi-4.1.2.json;
the breaking change (token abilities, item 4 in the body) is live upstream, so upgrade order matters: mint the read:sensitive token before pointing cast at an upgraded instance, or reads silently lose fields exactly as the body warns.

Labels normalized to the board taxonomy: enhancement, scope:coolify-api, blocked. Flips when the fleet's instances actually move.

Triage status, 2026-08-17 — half the gate has resolved: Coolify **v4.2.0 released 2026-07-21** ([release tag](https://github.com/coollabsio/coolify/releases/tag/v4.2.0); upstream is already at v4.3.1 as of 2026-08-12). The tracker stays `blocked`: the condition is "v4.2 is released **and the box upgrades**", nothing on this board records the fleet moving off 4.1.2, and that upgrade is operator-owned infrastructure work outside this repo. Two things turn concrete now, worth having on record before the upgrade happens: - the checklist's first step has a real target — re-vendor the OpenAPI spec at `v4.2.0` (or whichever tag the fleet actually adopts, upstream is past it already) and diff against `coolify-openapi-4.1.2.json`; - the breaking change (token abilities, item 4 in the body) is live upstream, so upgrade order matters: mint the `read:sensitive` token **before** pointing cast at an upgraded instance, or reads silently lose fields exactly as the body warns. Labels normalized to the board taxonomy: `enhancement`, `scope:coolify-api`, `blocked`. Flips when the fleet's instances actually move.

claude-bot-andresmgsl added the

enhancement

scope:coolify-api

blocked

labels 2026-08-17 22:43:59 +00:00

No milestone

No project

No assignees

2 participants

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#77

No description provided.

v4.2 upgrade tracker: settings as diffed fields, destinations resolver, read:sensitive token, OpenAPI re-vendor #77

Summary

What v4.2 changes (verified on upstream/next as of 2026-07-16, 7d699818e)

Upgrade checklist (in order)

Refs

What v4.2 changes (verified on `upstream/next` as of 2026-07-16, `7d699818e`)