Skip to content
SHC Docs

App buckets

Layer 6. Services. Services

Every app lives in exactly one of FIVE buckets. Nothing sits flat at apps/<name>/, and there is no sixth bucket.

apps/flagship/<app>/ first-class: unlimited users, SSO, plugs, sockets
apps/enterprise/<app>/ requires a licence to run
apps/integrated/<app>/ SSO-capable but short of first-class
apps/standalone/<app>/ no SSO, and where bridges and sidecars go
apps/classic/<app>/ pinned; cannot update past a licence/payment/feature change

apps/ also holds the first-party frontends: apps/console/ and apps/marketplace/. They are not apps and not a sixth bucket; see §9.

“flagship is every first class supported app of which i defined what is needed for that. unlimited users sso plugs sockets etc… for a first class flagship app. enterprise is any app that requires a license to run and then apps that don’t support sso would be standalone”

(owner ruling, 2026-08-11)

“make a folder called classic that we put all classic apps where we can’t update past a point becasue of license or payment or feature changes”

(owner ruling, 2026-08-11)

On bridges, sidecars and brokers, asked directly whether they deserved a home of their own: “they’re not special”. They go in standalone/.

integrated is the fifth name and the only one the owner did not coin. It exists because the ruling’s two ends left a gap: an app can deliver real SSO and still not be first-class, and calling it standalone would be false: the word standalone means no SSO.

PRECEDENCE: when an app qualifies for more than one

Section titled “PRECEDENCE: when an app qualifies for more than one”
classic > enterprise > flagship > integrated > standalone

Read strictly, left wins. A pinned classic line is classic even if it also needs a licence. An app that needs a licence is enterprise even if it has sockets and plugs and would otherwise be first-class.

Every place the precedence changed an answer is recorded in §5.

Terminal window
$ git ls-tree -d --name-only origin/main apps/
apps/classic
apps/console
apps/enterprise
apps/flagship
apps/integrated
apps/marketplace
apps/standalone

Five bucket entries. Not “five concepts”, not “four buckets plus a flat default”: five directory entries, and every one of them holds apps.

The other two are the first-party frontends (§9), named in FRONTEND_APPS in the Makefile. Filter them out and the bucket set is still literally five:

Terminal window
$ git ls-tree -d --name-only origin/main apps/ | grep -Ev '/(console|marketplace)$'
apps/classic
apps/enterprise
apps/flagship
apps/integrated
apps/standalone

The mechanical half is tests/unit/catalog/app_bucket_taxonomy_test.go. This page and that file are two halves of one rule and must agree.


Four attempts. Writing them down is the point: each was a plausible misreading, and each shipped green.

#What was builtWhy it was wrong
1df3a6a13 minted one directory per category:: 28 buckets for ~60 apps, eleven holding a single app.Organised by capability. The directory was welded to category:, so it could only ever re-derive itself.
2A later pass collapsed those into 8 broad topic buckets (ai, business, devops, …).Fewer directories, same mistake: still topic, which is the exact thing the ruling forbids.
3The next pass read “three categories” as three posture buckets with FLAT as the default and moved 60 apps out to apps/<name>/.ls apps/ printed 64 names. “Three folders” means the directory contains three entries.
45ca505199 finally got three directory entries, but with the wrong meanings: flagship was read as the league label, standalone as “everything else”.The owner’s definitions are about capability, not curation: flagship means unlimited users, SSO, plugs, sockets; standalone means no SSO. Under the right meanings three buckets cannot hold the corpus, which is what produced integrated and classic.

★ Attempt 3 also wrote a guard that enshrined it. The taxonomy test carried a floor, if flat < 40 { t.Fatalf(...) }, which required at least forty apps sitting flat. The wrong layout was therefore protected by a passing test, which is why the owner had to ask a third time. That floor is deleted; TestNoAppSitsFlatUnderApps is its exact inverse and requires zero.

The lesson that generalises: a count floor cannot express this rule. A count is what let 64 look like 3. The guard asserts a set equality against five literal names and fails naming the offending directory, with the remedy.


2. The two axes, and why they are not the same axis

Section titled “2. The two axes, and why they are not the same axis”

The single most common way this goes wrong is collapsing the directory into category:. They are different axes with different grain and different consumers.

bucket (the directory)category: (the app.yaml field)
GrainBROAD: exactly five, closed, ruledFINE: free-form, per-app
Axisposture: what it costs and how deeply it integratestopic: what it is about
Who reads ithumans running ls apps/, and the resolvers that walk two levelsce (persists + indexes it), shc search -c, the launcher tile glyphs, the generated catalogue index
Changing ita git mv, invisible to every estatea real change with four consumers

They are allowed to disagree, and mostly do. apps/enterprise/affine declares category: collaboration; apps/standalone/keygen declares category: business; apps/flagship/glitchtip declares category: monitoring. That is the design, not drift.

category: is a CLOSED vocabulary of twelve store sections (ai, business, collaboration, communication, database, development, devops, media, monitoring, productivity, security, storage), enforced by scripts/arch-fitness.sh check 23c. The specific word an app wants (licensing, knowledge-base) belongs in tags:, which is the field for facets. Widening the twelve is a deliberate edit to that check.

The four consumers of category:, none of which reads a bucket:

  1. ce persists it on the app record and indexes it.
  2. shc search -c <category> filters on it.
  3. The launcher tile glyph. traefik/plugin/icons.go keys launcherGlyphs on the category, which the daemon stamps on each apps.json entry from the deployment’s own app.yaml. TestEveryCatalogueCategoryHasAGlyph fails when a package declares a category nobody drew a glyph for.
  4. The marketplace storefront: listings at marketplace.selfhostedcloud.org group by it (the seeder forwards category:). The generated Pages catalogue that used to index the corpus By category was removed 2026-08-14: “everything is through the marketplace”.

★ Never edit category: to make a directory question go away, and never add a directory because a category has no home.


BucketMeansCountMembership test
classicPinned; cannot update past a licence, payment or feature change.3derived: the -classic name suffix, as a biconditional
enterpriseRequires a licence to run.6derived: the declared license.requires_paid_license field, as a biconditional, plus an independent pinned list
flagshipFirst-class: unlimited users, SSO, plugs, sockets.23a pinned named list, plus the one-way flagship: <league> label implication
integratedSSO-capable but short of first-class.13none: residue, with standalone
standaloneNo SSO. Also the owner-ruled home for bridges and sidecars.46none: residue, and deliberately so

The owner’s definition is four nouns, and each is a gate. An app is flagship only when all four hold:

gatemeanshow it is read
unlimited usersno seat cap, no per-user payment, no “the Nth login is refused” in the build we installthe in-app licence/cap record
SSOthe app actually delivers single sign-on: an oidc/saml/ldap plug, a native SSO knob the compose template renders, an sso_redirect: block, or a genuinely userless-and-gated postureapp files
plugs≥ 1 *.plug.yaml: it consumes estate services rather than bundling themapp files
sockets≥ 1 *.socket.yaml: it publishes a provider edge other apps can bindapp files

★ Sockets are the discriminator between flagship and integrated. An app that only consumes is a tenant of the platform; an app that also publishes a protocol-named socket is a member of it.

★ An INERT plug is not SSO. A plug that mints a Keycloak client and sets env nothing reads has not delivered SSO. blockscout (9.0.2: ACCOUNT_KEYCLOAK_* only exists upstream from v10.1.0) and monica (4.1: “THERE IS NO SSO AT THIS PIN AT ALL”) both ship one and both are standalone.

★ A gate in front of an app that has its own login is not SSO either. It double-credentials the user. defectdojo’s own app.yaml is the worked case: “THE GATE IS A WALL, NOT A SIGN-IN.”

flagship the FOLDER is not flagship: the LABEL

Section titled “flagship the FOLDER is not flagship: the LABEL”

These are two different mechanisms and they now measure different things:

the flagship: <league> labelthe apps/flagship/ folder
Meansbest-in-class for one functionfirst-class integration depth
Exclusive?yes, exactly one app per leagueno
Today5 apps23 apps
Ruled by2026-08-062026-08-11

The relationship is a one-way implication, enforced by TestFlagshipLabelLivesInFlagshipBucket: a labelled app must live in apps/flagship/, but not every app in apps/flagship/ carries a label. Keeping the old biconditional would force 21 apps to invent 21 unique league tokens, which destroys what the label means.

★ This implication is load-bearing, not a formality. openreplay, uptime-kuma and superset publish no socket, so the four gates put them in integrated, and all three hold a league label, which holds them in flagship/. See §5.

★ goalert (2026-08-21) is the first label-holder that also clears all four gates. It consumes postgres/oidc/smtp and publishes the goalert socket, so the integration-depth reading and the flagship: oncall label agree; see the oncall league.

★ And the label is no longer only a one-way door out of integrated/. The label half now carries its own floor: scripts/arch-fitness.sh’s flagship-league-roster check pins the OWNER-RULED leagues by name, so a declaration that is deleted, moved to another app, or invented without a ruling fails BY NAME. Before it, the flagship contract check validated only the claims that existed and reported clean over zero of them (half-done sweep F9).

enterprise, and the field that makes it findable

Section titled “enterprise, and the field that makes it findable”

“enterprise is any app that requires a license to run”

Three cases are constantly confused, and only two are enterprise:

Enterprise?
(a)genuinely requires a paid/issued licence to run at allYES
(b)open-core: runs free, but the capability an estate needs (above all SSO) is behind a paid tier with no free equivalentYES
(c)source-available (BSL / SSPL / ELv2 / RSALv2 / FCL): restricts redistribution or resale, free to self-hostNO

★ Class (c) is the trap. Getting it wrong sweeps MongoDB, Redis, Keygen, Dify, Sentry and Huly’s two sidecars into enterprise/, none of which cost a self-hoster a cent. The 2026-08-07 ruling settles it: “A component under SSPL, BSL, ELv2, RSALv2 or FCL never costs an app the flagship label.”

★ The line inside class (b). An app can lack SSO for two different reasons:

  • No SSO at any price: uptime-kuma, agent-canvas, jellyfin, greenbone. Nobody is being asked to pay; the SHC forward-auth gate is the accepted free answer. → not enterprise.
  • SSO exists upstream and costs money: these carry their own user model and login form, so the gate becomes a second door: double login, and still no federated identity. You are being asked to pay. → enterprise (b).
license:
id: AGPL-3.0 # SPDX: what the CODE is under
requires_paid_license: true # ★ does an estate have to PAY?
requires_paid_license_reason: >-
Class (b). SAML, JWT and OIDC SSO are paid-tier Metabase features …

★ Why a new field rather than re-using license.id. Every shippable app already declares license: (arch-fitness.sh’s app-license-declared check enforces it, 88/88). But license.id is an SPDX identifier: it records what licence the code is under, never whether SSO costs money. The two are orthogonal in both directions, with in-catalogue witnesses each way:

  • an AGPL-3.0 app can have a paywalled SSO tier (openreplay upstream);
  • an SSPL-family app can be entirely free to self-host (mongodb).

68 of 88 ids are unverified besides. That orthogonality is exactly why the enterprise bucket was undetectable from metadata and metabase had to be hand-placed. The new field answers this question, so “which apps are enterprise?” is a grep instead of an 88-app research pass.

Absence means false, deliberately: 82 apps would otherwise carry a line saying nothing. What absence cannot do is hide an app inside apps/enterprise/: TestEnterpriseFolderAndDeclaredFieldAgree is a biconditional over folder and field, so each direction fails by name. A bare true with no requires_paid_license_reason: fails too; that was the state that made the bucket unauditable.

integrated: SSO-capable but short of first-class

Section titled “integrated: SSO-capable but short of first-class”

Delivers real SSO but fails one of the other three. All 12 current members fail on sockets alone: every one carries an SSO plug and 2–5 further plugs and publishes nothing, which makes this bucket a roadmap rather than a verdict: each is one socket file away from flagship.

“apps that don’t support sso would be standalone”

standalone is not “apps with no user surface”. It is: F1 fails. It holds four honest groups: infrastructure providers with no login surface at all (external-*, redis, mysql, nginx), the owner-ruled bridges and sidecars, apps whose SSO is inert at the pinned version, and apps with no free upstream SSO.

★ Bridges and sidecars go here by explicit owner ruling: “they’re not special”, even when they are mechanically rich. identity-broker carries 8 plugs, a socket and an oidc plug, which is the richest app in the tree, and it is standalone: it is an in-cluster sidecar, publicUrl is published empty, and no browser ever lands on it.

★ integrated and standalone are deliberately NOT pinned to named lists in the guard. Between them they are the residue: a new app landing in one of them is the correct default outcome, not drift to be caught. Pinning them would mean every new app had to be added to a list in a test file, exactly the friction that pushes the next author to invent a sixth directory.

“where we can’t update past a point becasue of license or payment or feature changes”

Not ordinary staleness. A classic line is pinned because moving forward would lose something:

apppinned atwhich clause
defectdojo-classic2.58feature change: 3.x dropped SSO
midpoint-classic4.8licence change: last dual-licensed line before the EUPL-only relicense

★ A -classic app’s current sibling is NOT classic. Place each by its own posture. defectdojo is enterprise (3.x SSO is Pro-only), while defectdojo-classic is classic.

★ fusionpbx was considered and rejected. Its 2017 image is frozen because “the FusionPBX project publishes no official container”: packaging staleness, not a licence, payment or feature change. It stays standalone.


apps/fixtures/ used to hold test-data, test-simple and whoami. It was an extra directory, and it is gone. It was split by what the apps actually are, which turned out not to be one thing:

PackageWhere it wentWhy
test-data, test-simpletests/fixtures/apps/<app>/, out of apps/ entirelyprivate: true. Never published, no user would install them. Not products, so they have no posture and get no bucket.
whoamiapps/standalone/whoami/Not private. It carries a real version and publishes to the app registry, so it is a product like any other, and it has no SSO, so it is standalone.

★ whoami was the trap. It sat in fixtures/ and reads like test material, but removing it from the catalogue would have dropped a published app from the index, tripping publish-apps-registry.sh’s index-shrink-floor and blocking every app publish until someone declared it retired. See apps/RETIRED for the outage that rule exists to prevent. The fixture/product line is private: true, never the directory something happens to sit in.

The fixtures are still installable, and that is load-bearing

Section titled “The fixtures are still installable, and that is load-bearing”

tests/e2e runs shc install test-simple and shc install test-data. Moving the apps out of apps/ must not break that, so both resolvers span both roots:

Goshell
Resolve one app by namecatalog.AppDirshc_app_dir
Enumerate every appcatalog.AppDirsnone
The rootscatalog.FixturePackagesRootshc_app_package_roots
Stage the flat node treenoneshc_flatten_apps

★ Resolve app directories by SEARCH, never by a remembered path. Every hardcoded apps/<name> and apps/<topic>/<name> literal in this repo has been dead at least once; this move alone invalidated 38 of them. The resolvers above are the only supported spelling.


The two audits behind this layout ran in parallel and were reconciled by the precedence. Every place it was applied, and every place they disagreed:

appintegration-depth readinglicensing readinglandedwhy
affineintegrated (no socket, 10-member cap)enterprise (a)+(b)enterpriseenterprise > integrated
windmillintegrated (has a socket; fails unlimited users)enterprise (b)enterpriseenterprise > integrated. The two audits genuinely disagreed on the classification, not just the rank: one read the 10-SSO-user cap as a cap, the other as a paywall. The paywall reading holds: the counter is not patchable, since the published image is the proprietary CE build whose licence forbids modifying or wrapping it.
planestandalone (no SSO shipped)enterprise (b)enterpriseenterprise > standalone. The app ships no oidc.plug.yaml because SSO is Pro-only; the packaging already reflects the paywall.
docusealstandalone (no SSO shipped)enterprise (b)enterpriseenterprise > standalone
defectdojostandalone (no SSO in 3.x)enterprise (b)enterpriseenterprise > standalone. ⚠ The licensing audit rates this one low confidence: DefectDojo is introducing a free Pro tier for small teams; if that is genuinely free with SSO, defectdojo is not enterprise at all.
defectdojo-classic-not-enterpriseclassicclassic outranks everything
midpoint-classic-not-enterpriseclassicsame
keygen, difystandalonenot enterprise: FCL / modified-Apache are class (c)standaloneflagged as enterprise candidates by the depth audit; the licensing audit owns that question and ruled them free to self-host

Where the audits disagreed on FACT, and who was right

Section titled “Where the audits disagreed on FACT, and who was right”
claimlicensing auditfirst-class auditmeasuredright
apps carrying license.id: unverified676868 (20 carry a real SPDX id; 68 + 20 = 88)first-class audit

Both audits independently corrected the same stale premise in their brief, that “0 apps declare any license field”. All 88 declare one; what they do not declare is whether SSO costs money, which is what §3’s new field adds.

★ Three placements the owner should rule on

Section titled “★ Three placements the owner should rule on”

All three are recorded in the guard rather than silently resolved:

  1. uptime-kuma sits in apps/flagship/ with none of the four gates: no user model (so no “unlimited users”), no SSO at any price, no socket, only matrix + smtp plugs. It holds flagship: uptime by a league-function ruling (2026-08-06), not by integration depth. The label implication holds it in flagship/; the four gates say integrated. The two criteria disagree and neither was invented here. A status-page monitor also has no natural provider surface to publish, so “add a socket” is not a real roadmap item for it.
  2. openreplay passes SSO, plugs and unlimited users but publishes no socket, so the gates say integrated; flagship: replay holds it in flagship/. If “sockets” in the owner’s definition was rhetorical rather than a hard gate, openreplay is flagship on the merits and this resolves itself.
  3. superset is the same shape as openreplay and arrived the same way: SSO (flask-appbuilder AUTH_OAUTH, unpaid), oidc + postgres plugs, unlimited users, no socket, so the gates say integrated, and flagship: analytics holds it in flagship/. Its league was held open by owner directive 2026-08-06 pending a commissioned re-evaluation of metabase’s slot; the BI league pick IS that re-evaluation and it is ACCEPTED. A BI tool has no natural provider surface to publish either, so “add a socket” is not a real roadmap item here.

Either ruling is a one-line edit to flagshipMembers plus, if the label is to be vacated, the league decision doc and the flagship-league-roster row in scripts/arch-fitness.sh. Vacating a league is now a ruling the machine holds you to, not an absence it cannot see.


Walk the precedence in order and stop at the first match:

  1. Is it pinned and unable to move forward because of a licence, payment or feature change? → apps/classic/, and name it <app>-classic.
  2. Does it require a licence to run, outright (a), or because the SSO an estate needs is behind a paid tier with no free equivalent (b)? → apps/enterprise/. Declare license.requires_paid_license: true with a requires_paid_license_reason:, and add it to enterpriseMembers in the guard, same commit. (Source-available ≠ enterprise: see §3 class (c).)
  3. Does it have unlimited users AND SSO AND ≥1 plug AND ≥1 socket? → apps/flagship/, and add it to flagshipMembers, same commit.
  4. Does it deliver SSO but miss one of the other three? → apps/integrated/. No ruling needed, no list to update.
  5. Otherwise (no SSO, or it is a bridge/sidecar/broker) → apps/standalone/. No ruling needed. This is the answer for the plurality of apps.

Is it a private: true test fixture rather than a product? Then it is not a catalogue app at all: it goes in tests/fixtures/apps/, not apps/.

There is no step that creates a directory. If you are reaching for one, re-read §1: that is the move that has now been made and reverted three times.


The bucket set is closed to five names, and the guard enforces it as a set equality:

  • a sixth directory under apps/ fails TestAppsDirHoldsExactlyTheFiveBuckets, by name, with a message that distinguishes a topic grouping from a non-product tree and from a first-party frontend (§9);
  • an app sitting flat at apps/<name>/ fails the same test by name and prints the five-way decision, and independently fails TestNoAppSitsFlatUnderApps;
  • a missing bucket fails too: a tree with only four has lost one;
  • two directories claiming one app name fails, because the flattened tree a node runs is keyed by leaf name, so one would shadow the other.

All four failure directions are proven by mutation, because a taxonomy guard that has never been seen red is a taxonomy guard nobody has tested.

To land a sixth bucket: get an owner ruling, then write it here and in appBuckets in the guard, in the same commit. A bucket that exists in the tree but not in that map is unrepresentable: the guard derives its closed set from the map, so a directory cannot justify itself simply by existing. That self-justification is exactly what produced 28 buckets.


Identity is name-keyed, never path-keyed. The published name is app.yaml name:; the archive is <name>.app; the installed node’s tree is flattened by leaf name. A git mv between buckets therefore renames no app and is invisible to every estate and every pin.

The depth is load-bearing at exactly 2. apps/<bucket>/<name>/ is what the on-disk resolvers walk (ce core/appcatalog.MaxDepth, guarded by tests/unit/ci/app_resolver_agreement_test.go). Depth-1 resolvers 404’d every bucketed app once already (ce 4da4fde). A third level buys nothing and breaks the one-name-one-app invariant. Adding buckets does not change the depth, which is why the five-folder move needed no resolver change.

The five built-ins are exempt and stay flat at apps/<name>. postgres, keycloak, openobserve, traefik and branding are not committed here at all: they are build products of make modules/stage, and .gitignore, goreleaser’s src: and the deb payload checks all pin those paths at the root. A worktree that has run make configure therefore carries them physically under apps/, which is why the guard exempts them by name, read from apps/BUILTINS, never restated. git ls-tree never sees them, which is why the acceptance test above is stated against origin/main.

The three corpus ledgers stay at apps/ root. apps/RETIRED, apps/FRESHNESS_UNVERIFIABLE and apps/VERSION_IMAGE_DIVERGENCE are registers about the catalogue, not apps in it, and they name apps by bare name. They are files, not directories, so they do not affect the five-line acceptance test.


“let’s just merge it with the apps folder. there won’t be a collision becasue it will contain my runtimes and frontends like console and marketplace as well as the categories of apps i publish”

(owner ruling, 2026-08-13)

apps/ holds two kinds of thing, and one file tells them apart:

PathWhat it isHas app.yaml
apps/<bucket>/<app>/a catalogue app: installable, publishable, bucketed by postureyes
apps/console/, apps/marketplace/a multiplatform.one workspace: the SHC console and the app marketplaceno

A frontend has no app.yaml, and that absence is load-bearing rather than incidental. Every enumerator that matters keys on app.yaml, so catalog.AppDirs, shc catalog build and all of the count floors walk past a frontend without seeing it. Nothing installs one, and the publisher never forms an index entry for it. The exemption costs those checks nothing because of that, which is why the guard verifies the absence rather than trusting it: a frontend that grows an app.yaml fails by name.

The set is defined once, at FRONTEND_APPS := in the Makefile, and read from there by TestAppsDirHoldsExactlyTheFiveBuckets exactly as apps/BUILTINS is. Do not restate the names in the guard or on this page: a second copy is the drift this rule exists to prevent.

What this ruling does not open. It is not a sixth bucket, and it is not a way to park an app flat. Anything carrying an app.yaml still belongs in one of the five, and adding a name to FRONTEND_APPS that carries one is a hard failure rather than an exemption.

One name to keep clear. apps/flagship/frappe is the catalogue’s Frappe app and is unrelated to any bench a frontend runs against. Leaf names are the identity space for apps (§8), so a frontend must never take the name of one.