Skip to content
SHC Docs

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.org to apps.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 at feat/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.

#ThingWhere it livesWas it configurable?
1Where traefik answersdeploy/marketplace.shc.yaml:221, marketplace:3000@marketplace.{host}yes, deployfile
2What the bench admits as a CORS origindeploy/marketplace.shc.yaml, bench.allowCorsyes, deployfile
3What the store says its own address isfeatures/marketplace/src/catalog/serverCatalog.ts:234NO, 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-235
export 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 from input.siteOrigin
  • seo/homeSeo.ts: homeCanonical(), same
  • seo/sitemap.ts: buildSitemapXml(origin, …) and buildRobotsTxt(origin)
  • catalog/serverCatalog.ts:434,442,509: passes siteOrigin() into both page loaders
  • collections/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: declares siteUrl: "", defaulting empty exactly like the sibling apiUrl. Empty means the code’s own fallback answers, which is what a hand-run or local bench wants.
  • deploy/shc/marketplace/compose.yaml: passes MARKETPLACE_SITE_URL: "{{ vars.siteUrl }}" into the storefront service, beside the MARKETPLACE_API_URL it already passed.
  • deploy/marketplace.shc.yaml: sets siteUrl: https://marketplace.selfhostedcloud.org. The same string the hardcoded fallback produced, so production renders byte-identically.
  • deploy/shc/marketplace/tests/tests.bats: asserts that siteUrl’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.


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:lineWhatAction
features/marketplace/src/catalog/serverCatalog.ts:234siteOrigin() fallbacknow overridable by MARKETPLACE_SITE_URL (§2). Leave the literal as the local-dev default; flip the deployfile instead.
features/marketplace/src/listing/model.ts:298defaultSiteOrigin, used only when a caller omits siteOriginlow risk; ListingFrame always passes the loader’s value. Update at leisure; it is a dev-path default.
features/portal/src/ClustersScreen.tsx:17storefrontHref, the portal SPA’s link to the storemust flip, step 6
frappe/apps/portal/portal/www/clusters.py:111context.storefront_href, server-rendered portal pagemust flip, step 6
features/console/src/MarketplaceScreen.tsx:51MARKETPLACE_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.
File:lineWhatAction
deploy/marketplace.shc.yaml:221surface marketplace:3000@marketplace.{host}add apps.{host}, then remove the old (steps 2 and 8)
deploy/marketplace.shc.yaml bench.allowCorshttps://marketplace.selfhostedcloud.orgmust 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 siteUrlnew, §2must flip, step 5
.gitlab-ci.yml:1658environment.url for marketplace-catalogflip with step 8
.gitlab-ci.yml:4052-4053the apex _redirects, /apps and /apps/* → the store, 302flip 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:

  1. DNS record for api.selfhostedcloud.org (same zone, same DNS-01 cert story as §4, issuable before anything resolves).
  2. bench.aliasHosts gains api.selfhostedcloud.org (space-separated list), and the bench’s ingress surface gains the host. The bats guard that pins aliases == ['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.
  3. apiUrl flips to https://api.selfhostedcloud.org; that key feeds both the browser’s bench origin and bench.allowCors “from one file so they cannot drift”, so the flip carries CORS with it.
  4. 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.

~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.

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.

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. one ships createMiddleware (node_modules/one/dist/esm/createMiddleware.mjs) and every route in the built manifest carries a middlewares: [] slot. A middleware that reads the Host header, and on the old host answers 301 to https://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.


No step leaves either host 404ing.

  1. DNS: create apps.selfhostedcloud.org → the same target as marketplace.. Verify it resolves.
  2. Add the new surface, keep the old: deploy/marketplace.shc.yaml gains - marketplace:3000@apps.{host} alongside the existing line. Deploy. Cert issues via DNS-01 (§4). Both hosts now serve the store identically.
  3. Verify https://apps.selfhostedcloud.org/ returns 200 with a valid chain, and that /apps/nextcloud, /sitemap.xml and /robots.txt answer. At this point canonicals still name marketplace., correct and intended; the new host is not yet the canonical one, so there is no duplicate-content window.
  4. Flip bench.allowCors to https://apps.selfhostedcloud.org and deploy. ⚠ This is the one step with a real gap: between this deploy and step 5, the store served on marketplace. cannot read the catalogue cross-origin. Do steps 4 and 5 in one deploy, not two.
  5. Flip siteUrl to https://apps.selfhostedcloud.org in the same commit as step 4, and set retiredHosts: marketplace.selfhostedcloud.org beside it. Every canonical, og:url and sitemap <loc> now names apps., and the old host starts answering 301s; the middleware already ships in the image (§5), dormant until this line.
  6. Flip the inbound links: features/portal/src/ClustersScreen.tsx:17, frappe/apps/portal/portal/www/clusters.py:111, features/console/src/MarketplaceScreen.tsx:51.
  7. Flip the apex _redirects target in .gitlab-ci.yml:4052-4053, and update tests/unit/ci/pages_redirects_test.go:84 with it.
  8. 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.
  9. Submit the new sitemap in Search Console and leave the old property registered so the 301s are observed.

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.)

  • og:site_name and 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> and marketplace.appName all 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: becomes api.selfhostedcloud.org, alias-first, site name never moves. Full design in §3b. Nothing on this page remains owner-owed.

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.


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: siteUrl and bench.allowCors return to marketplace., and the redirect middleware leaves the image. One deploy. Canonicals revert on the next render, before most crawlers have re-fetched. The apps. 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.