docs(create-app): issue-resolution spec for local Docker start failure and the resulting permanent UVE 403 (#37262)

[fmontes]

Proposed Changes

Spec-only PR (PR 1 of 2) for #37262, per the repo's spec-kit flow. No code changes — this PR is the approval gate for the approach. Implementation lands in the stacked PR on top of this branch.

• Adds specs/37262-create-app-docker-uve/spec.md — an issue-resolution spec for the @dotcms/create-app local-Docker failure
• Points .specify/feature.json at the new feature

What's broken (three compounding defects):

1. dotCMS never starts. single-node-demo-site/docker-compose.yml lets dotcms boot before Postgres accepts connections and gives it no restart policy, so it exits and stays exited. The CLI reports "containers started successfully" and burns its retry budget on a dead container. Users get past this only by pressing ▶ in Docker Desktop.
2. A non-essential config call aborts the run. Token and default site both resolve fine; the UVE app-config POST then returns a transient 403 and the CLI calls process.exit(1). Because UVE setup runs before scaffolding, the user is left with an empty directory and the working token and site ID are discarded without ever being printed.
3. Recovery is blocked by the CLI's own side effects. The port pre-check hard-fails on the now-running dotCMS's ports, and the directory-clearing prompt would delete the docker-compose.yml needed to tear it down.

Verified against the tree before writing — every claim in the issue holds:

• compose: dotcms has depends_on with no condition, no restart:, no healthcheck, and does not publish 8090; opensearch has no healthcheck; db's healthcheck exists but nothing consumes it
• src/index.ts:370 exits before the scaffolding at :377
• src/index.ts:597 tests if (!result) against a truthy { ok: false, val }, making the npm-install failure branch unreachable
• checkPortsAvailability() (src/utils/index.ts:479) hard-fails on exactly the ports a successful run holds
• the package contains no spec files at all — this fix establishes the test harness

Deliberately deferred as explicit non-goals, so the P0 fix stays bounded:

• user.isAdmin() swallowing exceptions into a false "not admin" — real defect, but legacy Liferay code on a hot permission path with wide blast radius, and the P0 fix doesn't depend on it
• Pinning the image tag alongside CUSTOM_STARTER_URL — intersects binding ADR-0019 (date-lockstep SDK versioning), so it deserves its own decision rather than riding along in a bug fix

Reviewers — and two questions for you

.github/CODEOWNERS does not cover docker/, so the highest-blast-radius file in this fix gets no automatic reviewer. Reviewers below are derived from git blame on the exact hunks the implementation will change, weighting design ownership over line count (the two largest raw counts are a bulk restore, #27432, and a pgvector bump, #29915 — both mechanical).

Reviewer	Why
@wezell	OpenSearch 1.x + SSL in this file (#27754) and the Postgres 18 upgrade (#34236); owns the db/opensearch shape we're adding healthchecks to. Most senior still-active owner of docker/.
@erickgonzalez	Most recent semantic change to the dotcms service (#36490); closest to the CUSTOM_STARTER_URL / starter-import behavior the readiness race depends on
@jcastro-dotcms	Not from blame on this file — added because blame's strongest signal is unavailable (below). Second-most-active contributor to docker/ over the last 12 months.

Blame's two strongest signals can't be assigned. spbolton holds dominant blame on every hunk in scope and authored lgtm-observability (#32980) — the exact condition: service_healthy pattern this change copies — and dcolina holds part of the opensearch block (#29915). Both are no longer collaborators on this repo (last commits 2026-03-30 and 2026-04-07), so GitHub rejects the review request. Flagging it rather than quietly dropping them: the person who designed the pattern we're copying is not available to check that we're copying it faithfully. If anyone has context on the lgtm-observability healthcheck choices, that's the gap to fill.

⚠️ Updated — the diagnosis changed

Planning tested this spec's own root cause 2 and disproved it. The 403 is not a transient
startup race. It is permanent damage caused by root cause 1, and the two "independent bugs"
are one causal chain. Details in Root-Cause Hypothesis; summary below.

Experiment 1 — a clean boot has no settling window. Measured on an M5/64GB host with dotCMS constrained to 2 CPUs / 4G:

Signal	First success
POST api-token	46s
GET apps/dotema-config-v2/{site}	46s
/dotmgt/livez, /dotmgt/readyz	48s
/api/v1/appconfiguration (current CLI probe)	49s

The UVE endpoint is usable two seconds before readyz goes green. The starter import (T+20s) and ES reindex (T+44s) both complete inside Tomcat startup, and the connector accepts no traffic until after them. The hypothesised race cannot happen.

Experiment 2 — the reporter's actual path reproduces it, permanently. Killing dotCMS mid starter-import and hand-starting it (reproduction step 4):

T+39s  appconfiguration 200 — CLI proceeds
T+41s  api-token 200 ・ defaultSite 200 ・ UVE GET 403 ・ UVE POST 403
   … 193 consecutive attempts over ~7 minutes, zero successes …
T+440s UVE GET 403 ・ UVE POST 403

The reported log, line for line. Server-side:

DotSecurityException: User 'Admin User [dotcms.org.1][admin@dotcms.com]'
  does not have READ permissions on Site 'demo.dotcms.com'

The interrupted import never wrote the site's permission rows; the restart re-runs Task00004LoadStarter, reports a clean startup, and the permissions never appear. The instance does not recover.

What changed in the spec as a result:

• AC-005 no longer polls until 200 — it would never terminate. Retry is restricted to 5xx; 403 explicitly does not retry.
• The failure guidance is rewritten. "Configure UVE manually at this URL" is wrong advice — manual setup fails identically. The CLI must say the instance is unrecoverable and to run docker compose down -v.
• The P2 backend non-goal is re-pointed. Not user.isAdmin() swallowing an exception (there is nothing to swallow — the data is absent), but a larger defect: any interrupted first boot silently bricks the instance while reporting success. Filed separately as An interrupted first boot silently bricks the instance: starter import leaves site permissions unwritten and every Apps API call 403s forever #37268.
• Title and Reproducibility corrected — the 403 is deterministic once the crash has happened, not timing-dependent.

This raises US1's value. Fixing the compose file doesn't just stop a crash — it removes the 403 entirely, because it removes the interrupted boot that causes it.

Evidence limits: one host, one starter, one image, kill point fixed at 25s. Which kill-points corrupt is unmapped.

---

Updated after planning. Verifying the spec's claims against the tree turned up four that didn't hold, and I've folded the corrections back in before sign-off so you're approving what will actually be built:

• "Six siblings use condition: service_healthy" — there are three, and none of them gates dotcms on OpenSearch being healthy (all use service_started). So doing both is a deliberate deviation from every precedent, not the house pattern the spec implied. Kept, with the reasoning stated, using single-node-os-migration's proven probe.
• The flapping risk I flagged can't happen. Compose restart policies react to container exit, not health status. Replaced with the real exposure: a wrong probe blocks docker compose up --wait until timeout.
• 8090:8090 → 127.0.0.1:8090:8090. InfrastructureManagementFilter authorizes purely by arrival port — no credential check, no IP allowlist — so a wildcard binding puts /dotmgt/health and /dotmgt/metrics on the local network. New AC-011 asserts it's refused on the LAN address.
• The Jest harness already exists; only spec files are missing. The spec said this fix establishes it.

Also added AC-012 for a landmine found while reading: updateDockerComposeStarterUrl rewrites the compose file with a regex and throws on no match, so reformatting CUSTOM_STARTER_URL would break --starter for every already-installed CLI, with no release able to reach them.

What's left for you to settle (the 8090 question is now answered above):

1. Gating dotcms on opensearch: service_healthy goes further than all four existing examples. Right call for a stack driven by an unattended CLI, or should it match the house pattern? (My recommendation: keep the stricter gate.)
2. Is start_period: 180s enough for a cold demo-starter import on a slow machine? Above both precedents (lgtm 120s, metrics-monitoring 20s). Too short and --wait blocks to timeout.

Note on blast radius

The compose file is fetched from main at runtime by every installed @dotcms/create-app. A change ships instantly and unversioned to all existing CLI users — including older versions that won't know about port 8090. That cuts both ways: it's why the fix is P0 and reaches users without a release, and it's the single largest regression risk here. Worth a careful look.

Checklist

• Tests — n/a for a spec-only PR; the spec defines the Jest specs and cold-start compose verification that PR 2 must land first (constitution Principle V: Red before Green)
• Translations — n/a
• Security Implications Contemplated — publishing management port 8090 on the host is called out in the spec's Regression Risk and raised as review question 1 above

Additional Info

• Follows the spec-kit flow in CLAUDE.md: /speckit-specify-fix → PR 1 approved → /speckit-plan → /speckit-tasks → /speckit-implement → PR 2
• ADR consultation ran as the before_plan hook. ADR-0019 (accepted, binding) is recorded in the spec; ADR-0016 matched on keywords but is an unfilled template and imposes nothing. No conflicts with an accepted ADR.
• Related: e2e: Add E2E test suite for @dotcms/create-app CLI #35096 (E2E suite for @dotcms/create-app) — owns the fault-injection coverage, out of scope here

Refs #37262

This PR fixes: #37262

[claude]

Claude finished @fmontes's task in 1m 28s —— View job

---

Spec review — specs/37262-create-app-docker-uve/spec.md

Spec-only PR (approval gate). I verified the concrete tree claims and read for internal consistency. The code references hold up — src/index.ts:369-371 exits on UVE failure before :376-378 (compose move → scaffold → move back), :597 tests if (!result) against the truthy Result, and the compose file matches the described shape (dotcms depends_on: [db, opensearch] with no condition/restart/healthcheck, publishes only 8082/8443, opensearch has no healthcheck, only db has one). Good, accurate diagnosis.

Three internal inconsistencies remain after the rescope — worth fixing before sign-off since reviewers are approving these exact values:

New Issues

• 🟠 High: spec.md:266 vs spec.md:401 — start_period contradicts itself: 120s vs 180s. Fix Scope specifies the dotcms healthcheck at start_period: 120s ("~2.5× the measured ~46s boot"), but review question 2 asks reviewers "Is start_period: 180s enough headroom". These are different values for the same setting, so the reviewer question is asking about a number the spec doesn't actually propose. Pick one and make both places agree (120s matches the lgtm precedent cited; 180s does not). Fix this →

• 🟡 Medium: spec.md:463-467 — Compose verification targets the file the rescope no longer changes. The Verification method runs docker compose -f docker/docker-compose-examples/single-node-demo-site/docker-compose.yml up -d --wait and asserts dotcms reaches healthy without manual start. But the rescope (lines 247-252) says the shared example is not modified and the CLI ships its own file at core-web/libs/sdk/create-app/assets/docker-compose.yml; AC-010 even asserts docker/docker-compose-examples/* is unchanged. So this verification step would test an unmodified file that still lacks the healthchecks/gating — it can't pass. Point it at the bundled asset. Fix this →

• 🟡 Medium: spec.md:106 — "Three siblings" but four are listed and referenced. The sentence says "Three siblings already use condition: service_healthy" then lists four (lgtm-observability, single-node-metrics-monitoring, experiments, plus single-node-os-migration), and lines 397/401 both say "all four existing examples". I confirmed against the tree: exactly four compose files use condition: service_healthy (os-migration, metrics-monitoring, lgtm-observability, experiments). Change "Three" to "Four". Fix this →

Nothing blocking the substance of the approach — the diagnosis, the rescope to a bundled compose file, the loopback-only 8090 binding, and the non-poll/no-retry-on-403 decision are all well-argued and consistent with the evidence. These three are numeric/wording mismatches that would otherwise get baked into PR 2's acceptance criteria.

· issue-37262-create-app-docker-uve-spec