From 37bd474c4bdbdbee1240110fffb3325d2b8f6ba7 Mon Sep 17 00:00:00 2001 From: Isaac Karrer Date: Tue, 29 Sep 2026 08:37:15 -0500 Subject: [PATCH] docs(floxhub-onprem): document reference architectures (ENT-344) Describe the single-host topology, component responsibilities, infrastructure boundaries, and availability limits. Co-Authored-By: Morgan Helton Co-Authored-By: Claude Opus 5 --- .../reference-architectures/overview.mdx | 136 ++++++++++++++++-- llms.txt | 2 +- 2 files changed, 128 insertions(+), 10 deletions(-) diff --git a/floxhub-onprem/reference-architectures/overview.mdx b/floxhub-onprem/reference-architectures/overview.mdx index 03f4780..5505d93 100644 --- a/floxhub-onprem/reference-architectures/overview.mdx +++ b/floxhub-onprem/reference-architectures/overview.mdx @@ -1,15 +1,133 @@ --- title: "Reference architectures" -description: "Supported deployment topologies for FloxHub on-prem." +description: "The supported deployment topology for FloxHub on-prem, what each component does, and where your infrastructure meets it." --- - - **This page is under construction.** FloxHub on-prem documentation is - being written section by section. This page is a placeholder so the - surrounding navigation and links are complete. - +A reference architecture is a layout Flox builds, tests, and supports. It tells +you which components run where, which pieces you supply, and what the +arrangement does and does not give you. -## Planned contents +**One topology is documented today: a single host.** Every component runs on one +machine, with your database and your TLS edge beside it. -The supported topology, what each component is responsible for, and how to -choose between architectures. + + The component topology, network boundaries, persistent state, and operator + responsibilities in detail. + + +## The shape of a deployment + +```mermaid +flowchart TB + subgraph clients [Clients] + cli[Flox CLI] + browser[Browser] + end + + subgraph yours [Your infrastructure] + edge[TLS edge] + idp[("Identity provider")] + db[("PostgreSQL")] + store[("Object store, optional")] + end + + subgraph host [FloxHub host] + door{{"Front door"}} + subgraph web [Web] + ui[Web UI] + bff[Web backend] + end + subgraph core [Core services] + catalog[Catalog] + envs[Environments] + git[("Git storage")] + end + subgraph identity [Identity] + accounts[Accounts] + broker[OIDC broker] + authz[Authorization] + end + subgraph background [Background] + refresh[Catalog refresh] + builds[Builds] + upgrades[Scheduled upgrades] + end + end + + cli --> edge + browser --> edge + edge --> door + door --> web + door --> core + door --> identity + broker --> idp + core --> db + identity --> db + background --> db + builds --> store + catalog --> store +``` + +## What runs on the host + +| Component | Responsibility | +| --- | --- | +| Front door | Receives every client request, authenticates it, and routes it | +| Web UI and backend | The browser interface and the session it runs in | +| Catalog | Resolving and serving packages | +| Environments | Storing environments and their generations | +| Git storage | Backing `flox push` and `flox pull` | +| Accounts | Users, organizations, and tokens | +| OIDC broker | Translating your identity provider into one interface | +| Authorization | Deciding what each identity may reach | +| Catalog refresh | Populating the catalog and keeping it current | +| Builds | Building and publishing packages inside the deployment | +| Scheduled upgrades | Advancing managed environments on a cadence | + +Every component that can be switched off is switched off by configuration +rather than by editing the environment. A component whose gate is off idles, so +turning one on or off is a setting change and a restart. + +## What you supply + +| Piece | Why it is yours | +| --- | --- | +| The host | Provisioning, sizing, and OS patching | +| PostgreSQL | The deployment ships no database; this is its durable state | +| The TLS edge | The front door speaks plain HTTP and holds no certificate | +| An identity provider | The deployment holds no passwords | +| An object store | Optional, and only for carrying published binaries | + +See [Installation requirements](/floxhub-onprem/install/requirements) for the +prerequisites each of these has to meet. + +## Choosing an architecture + +With one documented topology, the question is not which to pick but whether +single-host meets your needs. It does when: + +- One host can carry your users and your catalog. +- Planned downtime for upgrades is acceptable. An upgrade stops services. +- Your availability requirement is met by your own host and database recovery + rather than by redundancy inside FloxHub. + +It does not give you high availability. There is no second host to fail over +to, and no component runs redundantly. Availability comes from the resilience +of the host and the database you supply, plus your ability to restore from +backup — so +[Back up and restore](/floxhub-onprem/administration/maintain/backup-restore) +matters more here than it would in a redundant deployment. + + + Separating components across hosts, running any of them redundantly, or + pointing the deployment at managed equivalents of its bundled pieces are not + documented or supported arrangements today. The single-host topology is what + Flox tests and supports. + + +## Sizing + +How much host to provision for a given number of users and catalog size is +being measured, and will be published alongside the single-host topology once +those figures exist. Until then, treat capacity as something to validate in +your own environment rather than something this page can answer. diff --git a/llms.txt b/llms.txt index c86f63a..e62ee95 100644 --- a/llms.txt +++ b/llms.txt @@ -133,7 +133,7 @@ Key terms: ## FloxHub on-prem: Reference architectures -- [Reference architectures](https://flox.dev/docs/floxhub-onprem/reference-architectures/overview.md): Supported deployment topologies for FloxHub on-prem. +- [Reference architectures](https://flox.dev/docs/floxhub-onprem/reference-architectures/overview.md): The supported deployment topology for FloxHub on-prem, what each component does, and where your infrastructure meets it. - [Single-host deployment](https://flox.dev/docs/floxhub-onprem/reference-architectures/single-host.md): Every FloxHub service on one host, with the database alongside it. ## FloxHub on-prem: Administer