[shipmill-romamo]

Spec for #90

• A Domain may declare spec.routes: each a proxy route (upstream: {address, port}, full request path kept) or a static route serving <installRoot>/current/<directory> of a component on the proxy server, with an optional spaFallback
• Static routes follow the component's current symlink, so deploy and cloudfall rollback switch the served files with no nginx reload
• cloudfall config validate requires exactly one of proxy.upstream or routes, and refuses duplicate, reserved (/.well-known/acme-challenge) or unsafe paths, static paths without a trailing /, and components not deployed on the proxy server
• Locations render longest path first; a Domain with only proxy.upstream renders a byte-identical vhost
• The nginx worker gets traverse-only access to the static directory (not the application group, which can read env files); healthCheck stays per Domain
• Pairs with the component build steps spec (A component can't build a frontend: the artifact is the git tree, and deploy only runs uv sync #86), which puts the frontend build in the artifact

Plan

• Serves: G-3
• Files: docs/specs/003-domain-routes.md
• Order: the spec alone; build issues are split from it once it merges
• Proof: approved by @romamo's answer on this PR (every recommendation taken)

🤖 Generated with Claude Code

[shipmill-romamo]

Before merging this: its rule "exactly one of proxy.upstream or routes" would reject atlas-fleet's old-civic-club Domain, which leaves upstream out on purpose. The question is asked on #90; whichever answer comes back, this spec gets a matching change to that rule first.

[shipmill-romamo]

@romamo Decision needed: do you approve this spec, once its "exactly one of proxy.upstream or routes" rule matches your answer on #90? Merging a spec is its approval (the spec gate), so shipmill holds it for your review instead of merging it on green CI.

1. Answer A Domain proxies everything to one upstream: no path routing for UI and API on one origin #90 first (recommended): shipmill changes this spec's rule to match, then you approve it by merging it, or by replying "1" here
2. Request other changes: reply or review with what to change; shipmill revises the spec in this PR and asks again
3. Refuse: close the PR; A Domain proxies everything to one upstream: no path routing for UI and API on one origin #90 reads SPEC_REFUSED and triage decides again (postpone or won't fix)

Reply here with a number or your own answer; shipmill takes this up on the tick after your reply.

[shipmill-romamo]

@romamo Decision needed: does spec 003, path routes for a Domain (#90), now set the behaviour the way you want?

Changed since the last question, to match your answer on #90: a Domain may declare at most one of proxy.upstream or routes (both is refused), and a Domain with neither stays valid, so atlas-fleet's old-civic-club keeps validating. S-003-9 now says that. The domains playbook's early check for a Domain without upstream (the #90 fix) reads "upstream or routes" once routes exist.

1. Take every recommendation (recommended): your answer is the approval; shipmill merges this PR once it is green, then files its build issues under A Domain proxies everything to one upstream: no path routing for UI and API on one origin #90. You may still merge it by hand
2. Change some of it: reply with what you want instead; the spec is revised in this PR and you're asked again, and nothing merges until then

Reply here with a number or your own answer; shipmill takes this up on the tick after your reply.

[romamo]

Decision by @romamo, relayed by Claude Code

1. Take every recommendation: approved.