docs(floxhub-onprem): scaffold the on-prem section

[imkarrer]

Scaffolds a FloxHub on-prem section in the sidebar — 33 pages across
installation, reference architectures, administration, and upgrades — and
writes the first four.

What to review: the section structure (docs.json), and the four pages
that carry real content:

Page	Issue
floxhub-onprem/intro — what the offering is, how it differs from hosted FloxHub, and what the operator is responsible for	ENT-338
.../administration/monitoring/health-check — every service's health endpoint, how to probe it, and what a 200 does and does not prove	ENT-350
.../administration/users/identity — attaching an identity provider, with working connector examples	ENT-361
.../administration/users/overview — how a person becomes a user, and which operator controls exist	ENT-360

The remaining 29 are placeholders carrying an under-construction banner and a
short statement of planned scope. Each commit cites the sub-issue it closes.

Tracked by ENT-151.

Targets docs/floxhub-onprem, the integration branch for this section, not
main. Merging here publishes nothing: the section reaches flox.dev/docs
only when that branch merges to main, once on-prem is ready to be public.

Why a skeleton first

The section is thirty-odd cross-linked pages accumulating on an integration
branch. Landing them one at a time without an agreed tree means every page
either links to nothing or invents a path the next page has to match. Putting the structure in first makes the
page naming reviewable while it is still cheap to change, lets each
subsequent page land as its own small PR, and makes the two landing pages
(introduction and reference architectures) writable against something real
instead of guesswork.

The placeholders are deliberate rather than empty: each states what the page
will cover, so the scope of the section is reviewable now.

Structure and where it comes from

The tree mirrors the GitLab documentation's split between
installation and
administration, which is the
structure ENT-151 asks for. Page-for-page, each placeholder corresponds to a
sub-issue of ENT-151.

The group sits directly after Imageless Kubernetes, the site's other
self-hosted-product section, rather than under Customer — that section is
three standalone pages, not a product tree.

Health check sits under Administer → Monitoring, matching GitLab's
/administration/monitoring/health_check/. The Configure page links to it.

How the health check page was written

Every endpoint, port, and path was read out of the service source rather than
inferred, including the mount prefixes that determine the full paths. Notable
findings that shaped the page:

• Only two endpoints do real work. catalog-server's /status/healthcheck
  runs a show, a search, and a resolve against the database and reports
  per-operation timings; build-coordinator's /health returns 503 naming
  any background loop that has exited. Everything else returns a fixed
  literal.
• The /ready paths on accounts, factory, and build-coordinator check
  nothing. They are documented as placeholders rather than as readiness
  signals, because treating them as readiness is the mistake this page exists
  to prevent.
• web-bff's /api/health/details reports no dependencies on-prem — its
  only dependency check targets a service on-prem deployments do not use — so
  it is documented as a second liveness probe.
• Through the front door only /web-bff/api/health/status and the two
  discovery documents answer without a credential. Everything else returns
  401, which is a useful signal about the front door and no signal at all
  about the service behind it.

The Limits section is as much of the page as the endpoint list, because
the failure mode in practice is reading a 200 as "the deployment works".

How the Users pages were written

Sourced from the deployment's own connector guide and the accounts service,
with the endpoint and provisioning behavior read from the code rather than
inferred.

Three findings drove how the pages are organized:

• The handle is derived, not chosen. It comes from the
  preferred_username claim (falling back to name), sanitized to the handle
  grammar. So a provider sending neither cannot have its users provisioned, and
  two usernames that sanitize to the same handle block the second person's
  sign-in with no self-service way out. Both are documented as pre-rollout
  checks, because they are cheap to check and expensive to hit during a
  rollout.
• The external URL is load-bearing. It is baked into every token the
  deployment issues and advertised as the broker's issuer, so it has to be
  correct before the first sign-in. That is stated before the connector
  instructions rather than after.
• Several expected controls do not exist — no invite flow, no user
  deactivation, no organization deletion, no directory group links, no
  administrative user listing. These are recorded explicitly so an operator
  plans around them instead of hunting for a setting. Revocation belongs at the
  identity provider, and does not reach tokens already issued.

Organization and membership management is named but deliberately left to the
follow-up scoped to it, matching how ENT-360 is written.

Verification

• vale — clean across all 33 pages. liveness, Entra, Okta,
  lowercased, misconfigured, and rollout added to the project vocabulary;
  two phrasings reworded rather than adding a word for them.
• mint broken-links — no broken links introduced. The three reported are
  pre-existing changelog/rss.xml references.
• mint dev — every new page returns 200 locally, confirming the MDX and
  the components parse.
• llms.txt regenerated with scripts/generate-llms-txt.sh, as
  check-llms-txt requires.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
flox	🟢 Ready	View Preview	Sep 28, 2026, 2:34 PM

💡 Tip: Enable Automations to automatically generate PRs for you.