Storefront host rename: marketplace. → apps. (design)
Status: built; this note is still its only description. The owner asked for the storefront to move from
marketplace.selfhostedcloud.orgtoapps.selfhostedcloud.org. The subdomain stays a subdomain; this is a LABEL change, not a move to the apex. Everything below is measured against the tree atfeat/storefront-seo-front-door(2026-08-20) and against the live hosts on the same day. Owner ruling still owed on §7’s two open items.
EXECUTED 2026-08-20, evening. Both phases ran through the gates and are
live-verified from public DNS: apps. and the shared api. alias serve on
the g2 estate (records daemon-published with correct heritage TXTs),
canonicals and all 172 sitemap <loc>s name apps., the retired host 301s
with exact path+query parity on page and api routes alike, and
api.marketplace. still answers, the alias-shaped commitment kept. The
execution surfaced a three-member incident family, all one class (cutover
artifacts nobody owned): the pipeline’s stale SHC_HOST deploying to the
retired generation, the --var transport’s colon reaching the bench alias
loop unsplit, and bare shc update rendering an import-created stack’s
persisted snapshot instead of CI’s rsync, with --from measured
NON-PERSISTENT on 0.0.60, which is why the fix is cicd passing --from on
every update (pinned by a bats test there), not a one-time re-point. The
paragraph below is the pre-execution record, kept as written.
Nothing in this repo has been flipped. The patch that landed with this document is behaviour-preserving and is described in §2; it exists so that the cutover is a config edit rather than an image rebuild.
1. What actually decides the storefront’s public address
Section titled “1. What actually decides the storefront’s public address”Three independent things, and before 2026-08-20 only two of them were configurable.
| # | Thing | Where it lives | Was it configurable? |
|---|---|---|---|
| 1 | Where traefik answers | deploy/marketplace.shc.yaml:221, marketplace:3000@marketplace.{host} | yes, deployfile |
| 2 | What the bench admits as a CORS origin | deploy/marketplace.shc.yaml, bench.allowCors | yes, deployfile |
| 3 | What the store says its own address is | features/marketplace/src/catalog/serverCatalog.ts:234 | NO, hardcoded |
Item 3 is the one that matters most for a rename and it was the one nobody
could change without rebuilding the image. siteOrigin() reads
MARKETPLACE_SITE_URL and falls back to a literal:
// features/marketplace/src/catalog/serverCatalog.ts:230-235export function siteOrigin(): string { const raw = (env?.MARKETPLACE_SITE_URL || "").trim(); return (raw || "https://marketplace.selfhostedcloud.org").replace(/\/+$/, "");}MARKETPLACE_SITE_URL was read here and set NOWHERE. Measured: the only
two occurrences of that variable in the entire tree were this line and
features/marketplace/src/catalog/serverCatalog.spec.ts:47. Not
compose.yaml, not vars.yaml, not the deployfile, not .gitlab-ci.yml. So
every canonical tag, every og:url and every <loc> in /sitemap.xml on the
live store came from that fallback string.
Everything downstream follows it and needs no separate change:
seo/listingSeo.ts:listingCanonical()builds frominput.siteOriginseo/homeSeo.ts:homeCanonical(), sameseo/sitemap.ts:buildSitemapXml(origin, …)andbuildRobotsTxt(origin)catalog/serverCatalog.ts:434,442,509: passessiteOrigin()into both page loaderscollections/serverCollections.ts:199,238: same for the collection pages
That is the good news: one value moves and the entire SEO surface follows.
2. The patch that landed with this document
Section titled “2. The patch that landed with this document”Behaviour-identical. Three wiring edits plus one guard.
deploy/shc/marketplace/vars.yaml: declaressiteUrl: "", defaulting empty exactly like the siblingapiUrl. Empty means the code’s own fallback answers, which is what a hand-run or local bench wants.deploy/shc/marketplace/compose.yaml: passesMARKETPLACE_SITE_URL: "{{ vars.siteUrl }}"into the storefront service, beside theMARKETPLACE_API_URLit already passed.deploy/marketplace.shc.yaml: setssiteUrl: https://marketplace.selfhostedcloud.org. The same string the hardcoded fallback produced, so production renders byte-identically.deploy/shc/marketplace/tests/tests.bats: asserts thatsiteUrl’s host and the storefront SURFACE resolve to the same name. Nothing in the tree tied those together before; a store serving 200s whose canonical names a different host is the one SEO defect that de-indexes rather than under-ranks. It is also the half-rename guard: flipping the surface without the canonical (or the reverse) now reds by name.
After the cutover, item 3 of §1 is one line in the deployfile.
3. Inventory
Section titled “3. Inventory”178 occurrences of marketplace.selfhostedcloud across the tree. Classified,
with the ones that require action called out.
(a) Runtime defaults: hardcoded hosts in shipped code
Section titled “(a) Runtime defaults: hardcoded hosts in shipped code”| File:line | What | Action |
|---|---|---|
features/marketplace/src/catalog/serverCatalog.ts:234 | siteOrigin() fallback | now overridable by MARKETPLACE_SITE_URL (§2). Leave the literal as the local-dev default; flip the deployfile instead. |
features/marketplace/src/listing/model.ts:298 | defaultSiteOrigin, used only when a caller omits siteOrigin | low risk; ListingFrame always passes the loader’s value. Update at leisure; it is a dev-path default. |
features/portal/src/ClustersScreen.tsx:17 | storefrontHref, the portal SPA’s link to the store | must flip, step 6 |
frappe/apps/portal/portal/www/clusters.py:111 | context.storefront_href, server-rendered portal page | must flip, step 6 |
features/console/src/MarketplaceScreen.tsx:51 | MARKETPLACE_URL, the console’s store tile, commented “config-free on purpose” | must flip, step 6. Note this ships inside estates’ console builds, so old estates keep the old URL until they upgrade, which is exactly why step 4’s 301 is permanent. |
(b) Deploy config
Section titled “(b) Deploy config”| File:line | What | Action |
|---|---|---|
deploy/marketplace.shc.yaml:221 | surface marketplace:3000@marketplace.{host} | add apps.{host}, then remove the old (steps 2 and 8) |
deploy/marketplace.shc.yaml bench.allowCors | https://marketplace.selfhostedcloud.org | must flip; the storefront’s browser-side catalogue reads are cross-origin to the api host; a stale value breaks the store on the new name. Note the generator refuses spaces in vars: values (measured on pipeline 2766503239), so this cannot carry two origins; it flips, it does not accumulate. This is the sharpest ordering hazard in the whole cutover. |
deploy/marketplace.shc.yaml siteUrl | new, §2 | must flip, step 5 |
.gitlab-ci.yml:1658 | environment.url for marketplace-catalog | flip with step 8 |
.gitlab-ci.yml:4052-4053 | the apex _redirects, /apps and /apps/* → the store, 302 | flip target host, step 7 |
api.marketplace.selfhostedcloud.org: RULED 2026-08-20: the public API
host becomes api.selfhostedcloud.org, ALIAS-FIRST. The owner’s reasoning,
near-verbatim: “should be api.selfhostedcloud.org; it’s the same API the
portal uses.” And it is: this bench is one frappe site serving both frappe
apps, with my.selfhostedcloud.org already riding as its alias
(bench.aliasHosts), so a marketplace-scoped OR apps-scoped API name
misdescribes the thing either way. The neutral name is the honest one.
What the ruling does NOT do is move the SITE NAME. The draft of this
section defaulted to KEEP because renaming bench.siteName is a
database-identity migration; frappe resolves the site from the Host header
with no default_site fallback, so a rename “would leave the database, the
volume and the encryption_key under a name nothing routes to and answer 404
to every existing consumer of the catalog API.” That reasoning survives the
ruling intact; the ruling routes AROUND it. api.marketplace. stays the
site name and stays answering forever; api.selfhostedcloud.org joins as
an alias, exactly as my. did:
- DNS record for
api.selfhostedcloud.org(same zone, same DNS-01 cert story as §4, issuable before anything resolves). bench.aliasHostsgainsapi.selfhostedcloud.org(space-separated list), and the bench’s ingress surface gains the host. The bats guard that pinsaliases == ['my.' + zone]moves WITH this step to expect both; that assertion is the ledger of ruled aliases, and it changing in the same diff is the point.apiUrlflips tohttps://api.selfhostedcloud.org; that key feeds both the browser’s bench origin andbench.allowCors“from one file so they cannot drift”, so the flip carries CORS with it.- Third-party consumers of the catalog API migrate at their leisure; the old host is an alias-shaped commitment, not a redirect, and never breaks.
This step is INDEPENDENT of the storefront cutover and safe to land ahead of it; it adds a host and removes nothing. Sequencing it first also means the storefront cutover’s CORS flip (§6 step 4-5) is against a name that no longer changes.
(c) Docs / prose
Section titled “(c) Docs / prose”~50 hits across docs/proposals, docs/decisions, docs/internal,
docs/architecture, docs/app-development, TIERS.md, CHANGELOG.md.
No action at cutover. Most are dated records of decisions that named the
host at the time; rewriting them would falsify the record. New prose should
name the storefront rather than its host where the host is incidental.
(d) Generated artifacts
Section titled “(d) Generated artifacts”website/landing/llms.txt and the built public/_redirects are generated;
fix generators, never artifacts. website/ is report-only for this document:
a sibling lane owns it.
(e) Test fixtures
Section titled “(e) Test fixtures”tests/unit/ci/pages_redirects_test.go:84, tests/unit/ci/document_private_hosts_test.go (×6),
deploy/shc/marketplace/tests/tests.bats, features/marketplace/src/catalog/serverCatalog.spec.ts:47,
tests/unit/catalog/ (×6), tests/unit/marketplace/ (×2), tests/_ce/modules/app/ (×13).
These red at cutover by design; they are the mechanism that proves the
rename is complete. Update them in the same MR as the flip, not before.
4. Certificates and DNS: the part that is easier than it looks
Section titled “4. Certificates and DNS: the part that is easier than it looks”The cert needs no manual step. deploy/marketplace.shc.yaml:59-61:
public: true means exposure=internet, and “the estate resolves
*.selfhostedcloud.org through acme-prod-dns-hetzner, so these take a PROD
LE chain rather than the estate’s LE-staging default.”
That is DNS-01 over the whole zone, which removes the usual chicken-and-egg:
the certificate for apps.selfhostedcloud.org can be issued before anything
resolves there publicly, because validation never touches the host. Declaring
the surface is sufficient; traefik requests the cert on next render.
DNS: one A/AAAA record for apps in the selfhostedcloud.org zone,
pointing where marketplace points today. Create it before step 3.
5. The 301: and the honest answer about where it lives
Section titled “5. The 301: and the honest answer about where it lives”There is no host-redirect mechanism in this stack today. Measured:
traefik/render/render.go emits no RedirectRegex middleware and has no
redirect concept at all. The HOST_ALIASES support on this branch
(render.go:324,352-388) is system-app only (SHC_INGRESS_KEYCLOAK_*
and SHC_INGRESS_OPENOBSERVE_*, read by systemApp()) and it serves the
same content on a second host rather than redirecting. It does not apply to a
catalogue stack like the marketplace, and it is not a 301.
BUILT, 2026-08-20, in this repo, same day, later than the paragraphs
below, which are kept as the decision record. The storefront now ships the
middleware dormant: apps/marketplace/routes/_middleware.ts (HTTP surface)
over features/marketplace/src/seo/hostCanon.ts (the decision and its three
refusals, unit-tested in hostCanon.spec.ts), fed by
MARKETPLACE_RETIRED_HOSTS → retiredHosts in
deploy/shc/marketplace/{vars,compose}.yaml, empty by default; nothing
redirects until the cutover deploy sets it. The bats lane refuses a
deployfile that lists the canonical host as retired. Step 4’s “ship the
middleware” is therefore already done; the cutover only sets the var.
The options as they were weighed:
-
Traefik middleware: would need a new render capability (
RedirectRegex, permanent,^https://marketplace\.(.*)→https://apps.$1). Correct long-term, but it is a platform feature with its own tests, not a cutover step. -
★ In the storefront itself.
oneshipscreateMiddleware(node_modules/one/dist/esm/createMiddleware.mjs) and every route in the built manifest carries amiddlewares: []slot. A middleware that reads theHostheader, and on the old host answers301tohttps://apps.selfhostedcloud.org+ the same path and query, is ~15 lines, ships with the image, and needs no platform change. Path parity is exact because the middleware only rewrites the authority.This is the same mechanism the
/apps→/redirect already added on this branch uses (apps/marketplace/routes/apps/index+api.ts), one layer up.
Both hosts must bind the storefront service for the middleware to see the old host at all. That is why steps 2 and 8 are separate: the old surface stays bound, serving nothing but redirects, indefinitely.
301, not 302: the judgement is permanent, and permanence is the point: it
passes ranking signal to the new host, which a 302 does not. Note this is the
opposite of the choice .gitlab-ci.yml:4048-4051 made for the apex /apps
stub, and deliberately so; that comment says 302 because “the marketplace
storefront is still coming up … and a 301 is cached by browsers more or less
forever.” Here, forever is what we want.
6. Order of operations
Section titled “6. Order of operations”No step leaves either host 404ing.
- DNS: create
apps.selfhostedcloud.org→ the same target asmarketplace.. Verify it resolves. - Add the new surface, keep the old:
deploy/marketplace.shc.yamlgains- marketplace:3000@apps.{host}alongside the existing line. Deploy. Cert issues via DNS-01 (§4). Both hosts now serve the store identically. - Verify
https://apps.selfhostedcloud.org/returns 200 with a valid chain, and that/apps/nextcloud,/sitemap.xmland/robots.txtanswer. At this point canonicals still namemarketplace., correct and intended; the new host is not yet the canonical one, so there is no duplicate-content window. - Flip
bench.allowCorstohttps://apps.selfhostedcloud.organd deploy. ⚠ This is the one step with a real gap: between this deploy and step 5, the store served onmarketplace.cannot read the catalogue cross-origin. Do steps 4 and 5 in one deploy, not two. - Flip
siteUrltohttps://apps.selfhostedcloud.orgin the same commit as step 4, and setretiredHosts: marketplace.selfhostedcloud.orgbeside it. Every canonical,og:urland sitemap<loc>now namesapps., and the old host starts answering 301s; the middleware already ships in the image (§5), dormant until this line. - Flip the inbound links:
features/portal/src/ClustersScreen.tsx:17,frappe/apps/portal/portal/www/clusters.py:111,features/console/src/MarketplaceScreen.tsx:51. - Flip the apex
_redirectstarget in.gitlab-ci.yml:4052-4053, and updatetests/unit/ci/pages_redirects_test.go:84with it. - Retire the old surface? NO. Leave
marketplace:3000@marketplace.{host}bound permanently. Old console builds inside customer estates carry the old URL (see §3a), search engines take months to migrate, and external links never expire. The surface costs one router and one cert. Flip.gitlab-ci.yml:1658’s environment URL at this point; that is cosmetic. - Submit the new sitemap in Search Console and leave the old property registered so the 301s are observed.
Already-indexed pages 301 cleanly
Section titled “Already-indexed pages 301 cleanly”The live sitemap is 172 <loc> entries (167 app pages, 2 collections, 3
static) all under /apps/…, /apps/collection/…, /feeds, /about and
/. The middleware in §5 rewrites authority only, so every one of those 172
URLs has an exact 1:1 target. There is no path remapping in this rename and
therefore no redirect-chain or redirect-to-404 risk.
Commit B carries one credentialed chore: the portal subtree pin
Section titled “Commit B carries one credentialed chore: the portal subtree pin”Commit B edits frappe/apps/portal/portal/www/clusters.py, which moves the
portal subtree’s tree object, and frappe/docker/Dockerfile pins that tree
(TestInRepoFrappeAppPinsMatchTheirSubtrees holds the pair). The refresh is
one command that needs a registry credential this dev box does not hold:
run it wherever a token lives (a CI job token, or
SHC_REGISTRY_AUTH_HEADER='PRIVATE-TOKEN: …'):
SHC_FRAPPE_SUBTREE=frappe/apps/portal SHC_FRAPPE_MODULE=portal \ sh scripts/publish-frappe-apps.sh . <pkg>then paste the printed url + sha256 into PORTAL_URL / PORTAL_SHA256 in
frappe/docker/Dockerfile, in the same change as Commit B. DONE
2026-08-20: published as shc_portal 0.0.0-fb922276…/shc_portal-0d2da5eec753.tar
(the script’s anonymous-serve floor verified), pin pasted, and
TestInRepoFrappeAppPinsMatchTheirSubtrees is green on the branch. (The two other reds go test ./tests/unit/ci shows on this branch,
the coded-registry guard and arch-fitness, are measured RED ON MAIN too,
2026-08-20: relocation/host-alias lane debt, not this branch’s.)
7. Open: owner ruling owed
Section titled “7. Open: owner ruling owed”og:site_nameand the store’s spoken name: RULED 2026-08-20: KEEP “SHC Marketplace”. The host is an address, the name is a brand; the tags, the<h1>andmarketplace.appNameall stay as they are, and the SERP site name survives the host move unchanged. No copy churn rides the cutover.api.marketplace.: RULED 2026-08-20: becomesapi.selfhostedcloud.org, alias-first, site name never moves. Full design in §3b. Nothing on this page remains owner-owed.
8. Not applicable
Section titled “8. Not applicable”Keycloak needs no change. The storefront does not authenticate; it has no
keycloak block and no OIDC client, and the marketplace service’s environment
carries no identity configuration at all. The realm’s portal client allows
exactly two exact redirect URIs, both on the PORTAL origin
(scripts/ensure-portal-keycloak-client.sh:131,
["${portal_origin}/*", "${portal_origin}"]), and portal_origin is
my.selfhostedcloud.org, which this rename does not touch. Login is initiated
on the portal host, always.
9. Rollback
Section titled “9. Rollback”Every step is reversible and none destroys state.
- After steps 1–3: delete the
apps.surface line and redeploy, or simply leave it. Nothing referenced it yet; there is no rollback to perform. - After steps 4–5 (the real cutover): revert the commit:
siteUrlandbench.allowCorsreturn tomarketplace., and the redirect middleware leaves the image. One deploy. Canonicals revert on the next render, before most crawlers have re-fetched. Theapps.surface can stay bound; it simply stops being canonical. - After steps 6–7: ordinary revert; these are link strings.
- The irreversible part is not in this repo. A 301 is cached hard by
browsers, and search engines begin consolidating within days. Rolling back
after the 301 has been live for a week means clients that already cached it
keep going to
apps.regardless of what we serve. Treat step 5 as the point of no easy return, and hold at step 3 for as long as anyone wants to think.
The guard that makes a half-rollback loud: the bats assertion added in §2
reds if siteUrl and the storefront surface ever name different hosts, so a
partial revert cannot ship silently.