From 97b54512fca9e948dd4c021b7d4771758a0dcd09 Mon Sep 17 00:00:00 2001 From: Isaac Karrer Date: Mon, 28 Sep 2026 09:33:00 -0500 Subject: [PATCH 1/7] docs(floxhub-onprem): scaffold the on-prem section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a `FloxHub on-prem` navigation group covering installation, reference architectures, administration, and upgrades, with a page per planned topic. Two pages carry real content: - `floxhub-onprem/intro` — what the offering is, how it differs from hosted FloxHub, and which responsibilities belong to the operator. - `floxhub-onprem/administration/monitoring/health-check` — the health endpoint each service exposes, how to probe it from the host and through the front door, and what a `200` does and does not prove. The rest are placeholders marked under construction. They exist so the navigation tree and cross-links are complete while the remaining pages are written, rather than landing thirty pages of links to nowhere. `liveness` joins the Vale vocabulary. Co-Authored-By: Claude Opus 5 --- docs.json | 73 ++++++ .../administration/base-catalog.mdx | 15 ++ floxhub-onprem/administration/configure.mdx | 15 ++ .../administration/environment-upgrades.mdx | 15 ++ .../administration/environment-variables.mdx | 15 ++ floxhub-onprem/administration/factory.mdx | 15 ++ floxhub-onprem/administration/get-started.mdx | 15 ++ floxhub-onprem/administration/logs.mdx | 15 ++ .../maintain/backup-restore.mdx | 15 ++ .../administration/maintain/overview.mdx | 15 ++ .../administration/maintain/restart.mdx | 15 ++ .../maintain/troubleshooting.mdx | 16 ++ .../monitoring/health-check.mdx | 210 ++++++++++++++++++ .../administration/monitoring/overview.mdx | 15 ++ .../administration/object-storage.mdx | 15 ++ floxhub-onprem/administration/overview.mdx | 15 ++ floxhub-onprem/administration/postgresql.mdx | 15 ++ floxhub-onprem/administration/security.mdx | 15 ++ .../administration/users/identity.mdx | 15 ++ .../administration/users/overview.mdx | 15 ++ floxhub-onprem/install/flox-environment.mdx | 16 ++ floxhub-onprem/install/methods.mdx | 15 ++ floxhub-onprem/install/next-steps.mdx | 15 ++ floxhub-onprem/install/offline.mdx | 15 ++ floxhub-onprem/install/overview.mdx | 15 ++ floxhub-onprem/install/requirements.mdx | 15 ++ floxhub-onprem/intro.mdx | 94 ++++++++ .../reference-architectures/overview.mdx | 15 ++ .../reference-architectures/single-host.mdx | 16 ++ floxhub-onprem/upgrade/before-you-upgrade.mdx | 15 ++ floxhub-onprem/upgrade/instance.mdx | 15 ++ floxhub-onprem/upgrade/maintenance-policy.mdx | 15 ++ floxhub-onprem/upgrade/overview.mdx | 15 ++ .../upgrade/troubleshooting-and-rollback.mdx | 15 ++ llms.txt | 57 +++++ styles/config/vocabularies/Flox/accept.txt | 1 + 36 files changed, 903 insertions(+) create mode 100644 floxhub-onprem/administration/base-catalog.mdx create mode 100644 floxhub-onprem/administration/configure.mdx create mode 100644 floxhub-onprem/administration/environment-upgrades.mdx create mode 100644 floxhub-onprem/administration/environment-variables.mdx create mode 100644 floxhub-onprem/administration/factory.mdx create mode 100644 floxhub-onprem/administration/get-started.mdx create mode 100644 floxhub-onprem/administration/logs.mdx create mode 100644 floxhub-onprem/administration/maintain/backup-restore.mdx create mode 100644 floxhub-onprem/administration/maintain/overview.mdx create mode 100644 floxhub-onprem/administration/maintain/restart.mdx create mode 100644 floxhub-onprem/administration/maintain/troubleshooting.mdx create mode 100644 floxhub-onprem/administration/monitoring/health-check.mdx create mode 100644 floxhub-onprem/administration/monitoring/overview.mdx create mode 100644 floxhub-onprem/administration/object-storage.mdx create mode 100644 floxhub-onprem/administration/overview.mdx create mode 100644 floxhub-onprem/administration/postgresql.mdx create mode 100644 floxhub-onprem/administration/security.mdx create mode 100644 floxhub-onprem/administration/users/identity.mdx create mode 100644 floxhub-onprem/administration/users/overview.mdx create mode 100644 floxhub-onprem/install/flox-environment.mdx create mode 100644 floxhub-onprem/install/methods.mdx create mode 100644 floxhub-onprem/install/next-steps.mdx create mode 100644 floxhub-onprem/install/offline.mdx create mode 100644 floxhub-onprem/install/overview.mdx create mode 100644 floxhub-onprem/install/requirements.mdx create mode 100644 floxhub-onprem/intro.mdx create mode 100644 floxhub-onprem/reference-architectures/overview.mdx create mode 100644 floxhub-onprem/reference-architectures/single-host.mdx create mode 100644 floxhub-onprem/upgrade/before-you-upgrade.mdx create mode 100644 floxhub-onprem/upgrade/instance.mdx create mode 100644 floxhub-onprem/upgrade/maintenance-policy.mdx create mode 100644 floxhub-onprem/upgrade/overview.mdx create mode 100644 floxhub-onprem/upgrade/troubleshooting-and-rollback.mdx diff --git a/docs.json b/docs.json index c789284..5df6c35 100644 --- a/docs.json +++ b/docs.json @@ -109,6 +109,79 @@ "imageless-kubernetes/config" ] }, + { + "group": "FloxHub on-prem", + "pages": [ + "floxhub-onprem/intro", + { + "group": "Install", + "pages": [ + "floxhub-onprem/install/overview", + "floxhub-onprem/install/requirements", + "floxhub-onprem/install/methods", + "floxhub-onprem/install/flox-environment", + "floxhub-onprem/install/offline", + "floxhub-onprem/install/next-steps" + ] + }, + { + "group": "Reference architectures", + "pages": [ + "floxhub-onprem/reference-architectures/overview", + "floxhub-onprem/reference-architectures/single-host" + ] + }, + { + "group": "Administer", + "pages": [ + "floxhub-onprem/administration/overview", + "floxhub-onprem/administration/get-started", + "floxhub-onprem/administration/configure", + "floxhub-onprem/administration/environment-variables", + { + "group": "Monitoring", + "pages": [ + "floxhub-onprem/administration/monitoring/overview", + "floxhub-onprem/administration/monitoring/health-check" + ] + }, + "floxhub-onprem/administration/logs", + "floxhub-onprem/administration/object-storage", + "floxhub-onprem/administration/postgresql", + "floxhub-onprem/administration/base-catalog", + { + "group": "Maintain", + "pages": [ + "floxhub-onprem/administration/maintain/overview", + "floxhub-onprem/administration/maintain/backup-restore", + "floxhub-onprem/administration/maintain/restart", + "floxhub-onprem/administration/maintain/troubleshooting" + ] + }, + "floxhub-onprem/administration/security", + { + "group": "Users", + "pages": [ + "floxhub-onprem/administration/users/overview", + "floxhub-onprem/administration/users/identity" + ] + }, + "floxhub-onprem/administration/factory", + "floxhub-onprem/administration/environment-upgrades" + ] + }, + { + "group": "Upgrade", + "pages": [ + "floxhub-onprem/upgrade/overview", + "floxhub-onprem/upgrade/before-you-upgrade", + "floxhub-onprem/upgrade/instance", + "floxhub-onprem/upgrade/troubleshooting-and-rollback", + "floxhub-onprem/upgrade/maintenance-policy" + ] + } + ] + }, { "group": "Concepts", "pages": [ diff --git a/floxhub-onprem/administration/base-catalog.mdx b/floxhub-onprem/administration/base-catalog.mdx new file mode 100644 index 0000000..f55ee37 --- /dev/null +++ b/floxhub-onprem/administration/base-catalog.mdx @@ -0,0 +1,15 @@ +--- +title: "Base catalog" +description: "Populating and refreshing the package catalog." +--- + + + **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. + + +## Planned contents + +Initial population, periodic refresh, upstream dependencies, supported +configuration, and recovery from an interrupted update. diff --git a/floxhub-onprem/administration/configure.mdx b/floxhub-onprem/administration/configure.mdx new file mode 100644 index 0000000..4cc496c --- /dev/null +++ b/floxhub-onprem/administration/configure.mdx @@ -0,0 +1,15 @@ +--- +title: "Configure FloxHub" +description: "Where site configuration lives and how to apply 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. + + +## Planned contents + +Links to environment variables, health checks, logs, object storage, and +PostgreSQL. diff --git a/floxhub-onprem/administration/environment-upgrades.mdx b/floxhub-onprem/administration/environment-upgrades.mdx new file mode 100644 index 0000000..32472ea --- /dev/null +++ b/floxhub-onprem/administration/environment-upgrades.mdx @@ -0,0 +1,15 @@ +--- +title: "Automatic environment upgrades" +description: "Keeping managed environments current on a schedule." +--- + + + **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. + + +## Planned contents + +The scheduler, its configuration and cadence, the generations it produces, and +current limitations. diff --git a/floxhub-onprem/administration/environment-variables.mdx b/floxhub-onprem/administration/environment-variables.mdx new file mode 100644 index 0000000..960af11 --- /dev/null +++ b/floxhub-onprem/administration/environment-variables.mdx @@ -0,0 +1,15 @@ +--- +title: "Environment variables" +description: "The site configuration contract and its defaults." +--- + + + **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. + + +## Planned contents + +The site variables, their defaults, the overrides every deployment must set, +secret-file inputs, and how an included environment resolves configuration. diff --git a/floxhub-onprem/administration/factory.mdx b/floxhub-onprem/administration/factory.mdx new file mode 100644 index 0000000..69944a2 --- /dev/null +++ b/floxhub-onprem/administration/factory.mdx @@ -0,0 +1,15 @@ +--- +title: "Factory" +description: "Building and publishing packages inside your deployment." +--- + + + **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. + + +## Planned contents + +The build and publishing workflow, required configuration and credentials, +inspecting results, and the current execution-mode limits. diff --git a/floxhub-onprem/administration/get-started.mdx b/floxhub-onprem/administration/get-started.mdx new file mode 100644 index 0000000..8284cd1 --- /dev/null +++ b/floxhub-onprem/administration/get-started.mdx @@ -0,0 +1,15 @@ +--- +title: "Get started administering FloxHub" +description: "The first checks after installation and the routine operator tasks." +--- + + + **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. + + +## Planned contents + +Verifying services, inspecting logs, monitoring the catalog, and preparing +backups. diff --git a/floxhub-onprem/administration/logs.mdx b/floxhub-onprem/administration/logs.mdx new file mode 100644 index 0000000..7d4d82c --- /dev/null +++ b/floxhub-onprem/administration/logs.mdx @@ -0,0 +1,15 @@ +--- +title: "Log system" +description: "Where each service writes its logs and how to read them." +--- + + + **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. + + +## Planned contents + +Log locations, access commands, the fields worth knowing, and how to correlate +a failure across services. diff --git a/floxhub-onprem/administration/maintain/backup-restore.mdx b/floxhub-onprem/administration/maintain/backup-restore.mdx new file mode 100644 index 0000000..f12aeeb --- /dev/null +++ b/floxhub-onprem/administration/maintain/backup-restore.mdx @@ -0,0 +1,15 @@ +--- +title: "Back up and restore" +description: "Protecting deployment state and recovering 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. + + +## Planned contents + +The database and file backup and restore commands, their prerequisites, +consistency requirements, and which persistent state is not covered. diff --git a/floxhub-onprem/administration/maintain/overview.mdx b/floxhub-onprem/administration/maintain/overview.mdx new file mode 100644 index 0000000..a009d80 --- /dev/null +++ b/floxhub-onprem/administration/maintain/overview.mdx @@ -0,0 +1,15 @@ +--- +title: "Maintain FloxHub" +description: "Routine and recovery procedures for a running deployment." +--- + + + **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. + + +## Planned contents + +Links to backup and restore, service restart, and installation +troubleshooting, and when to use each. diff --git a/floxhub-onprem/administration/maintain/restart.mdx b/floxhub-onprem/administration/maintain/restart.mdx new file mode 100644 index 0000000..d99359f --- /dev/null +++ b/floxhub-onprem/administration/maintain/restart.mdx @@ -0,0 +1,15 @@ +--- +title: "Restart FloxHub" +description: "Stopping and starting services safely." +--- + + + **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. + + +## Planned contents + +The stop, start, and restart procedure, the status to expect, and the checks +to run afterwards. diff --git a/floxhub-onprem/administration/maintain/troubleshooting.mdx b/floxhub-onprem/administration/maintain/troubleshooting.mdx new file mode 100644 index 0000000..18f5936 --- /dev/null +++ b/floxhub-onprem/administration/maintain/troubleshooting.mdx @@ -0,0 +1,16 @@ +--- +title: "Troubleshoot an installation" +description: "Diagnose and recover from common failures." +--- + + + **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. + + +## Planned contents + +Observed failures as symptom, diagnostic command, cause, and recovery, +covering configuration, database connectivity, identity, catalog population, +and storage. diff --git a/floxhub-onprem/administration/monitoring/health-check.mdx b/floxhub-onprem/administration/monitoring/health-check.mdx new file mode 100644 index 0000000..f170dbc --- /dev/null +++ b/floxhub-onprem/administration/monitoring/health-check.mdx @@ -0,0 +1,210 @@ +--- +title: "Health check" +description: "The HTTP health endpoints each FloxHub service exposes, how to call them, and what each one proves." +--- + +Most FloxHub services expose an HTTP health endpoint, and most of those are +liveness probes: they tell you the process is up and its HTTP stack is +serving, and they make no call to the database or to any other service. The +few that report more are called out below, as are the components that report +nothing at all. + +Read this page alongside +[Monitor FloxHub](/floxhub-onprem/administration/monitoring/overview) for the +wider set of signals — logs, catalog freshness, and background jobs. + +## Endpoints + +The ports below are the defaults. If you have overridden the matching +`FLOXHUB_SITE_*` variable, probe your own value instead. + +| Service | Port | Path | +| --- | --- | --- | +| `catalog-server` | `8010` | `/api/v1/catalog/status/healthcheck` | +| `catalog-server` | `8010` | `/api/v1/catalog/status/catalog` | +| `catalog-server` | `8010` | `/api/v1/catalog/status/service` | +| `floxem` | `8040` | `/health` | +| `floxem-gitolite` | `8050` | `/health` | +| `accounts` | `8071` | `/api/v1/accounts/health` | +| `factory` | `8030` | `/api/v1/factory/health` | +| `build-coordinator` | `8031` | `/v1/coordinator/health` | +| `web-bff` | `8070` | `/api/health/status` | +| `web-bff` | `8070` | `/api/health/details` | +| `openfga` | `8060` | `/healthz` | + +`/health`, `/healthz`, and `/api/health/status` are liveness probes: a `200` +means the process is up and its HTTP stack is serving, and nothing more. The +`accounts` and `factory` responses carry the service version, which is what +tells you which generation is running after an upgrade. + +Three paths report more than liveness — `catalog-server`'s +`/status/healthcheck` and `/status/catalog`, and `build-coordinator`'s +`/health`. One reports less than it appears to: `web-bff`'s +`/api/health/details`. All four are described below. + +`accounts`, `factory`, and `build-coordinator` also expose a `/ready` path +beside their `/health` path. It returns `{"status": "ready"}` unconditionally +and checks nothing; see [Limits](#limits). + +`dex` has no health endpoint. Probe its OIDC discovery document instead: + +```bash +curl -fsS "${FLOXHUB_SITE_URL}/dex/.well-known/openid-configuration" +``` + +`nginx` has no dedicated health route. Any successful response through the +front door shows that it is serving. + +`floxem-scheduler` and the catalog updater expose nothing: both are loops +rather than servers, so no probe reports on them. The updater records each +successful run as a Unix timestamp, which is the only positive signal it +emits: + +```bash +flox activate -- date -d "@$(cat "$CATALOG_DATA/last-update-success")" +``` + +The scheduler leaves only its log output. For both, see +[Log system](/floxhub-onprem/administration/logs). + +### Checks that do real work + +**`catalog-server`'s `/api/v1/catalog/status/healthcheck`** runs a package +show, a search, and a resolve as the anonymous user, and reports each one's +outcome with its elapsed time in milliseconds: + +```json +{ + "search_ok": true, + "search_elapsed_ms": 12, + "resolve_ok": true, + "resolve_elapsed_ms": 48, + "show_ok": true, + "show_elapsed_ms": 9 +} +``` + +The timings make it worth polling: a catalog that is answering but slow shows +up here and nowhere else. + +**`catalog-server`'s `/api/v1/catalog/status/catalog`** returns the catalog +database's status counts, and `500` when the database does not answer. It is +the cheapest proof that `catalog-server` has a working database connection. + +**`build-coordinator`'s `/v1/coordinator/health`** returns `503`, naming the +finished tasks, when any background loop has exited: + +```json +{ + "status": "unhealthy", + "version": "…", + "dead_tasks": ["…"] +} +``` + +Those loops are meant to run until shutdown cancels them, so a finished one +means the coordinator can no longer observe builds. Only a restart brings it +back. + +### web-bff details + +`/api/health/details` is guarded by HTTP basic auth, and returns `503` when +any dependency is unhealthy. + +On-prem it reports no dependencies. Its only dependency check is against a +service the on-prem deployment does not use, so the endpoint answers `200` +with an empty `dependencies` list on every on-prem deployment, whatever the +state of the identity or database components. Treat it as a second liveness +probe, not a dependency report. + +## Check from the host + +Every service answers on `FLOXHUB_SITE_BIND_HOST` (`127.0.0.1` by default), +so you can reach the complete set from inside an activation: + +```bash +flox activate -- bash -c ' +for probe in \ + "$FLOXHUB_SITE_CATALOG_PORT/api/v1/catalog/status/healthcheck" \ + "$FLOXHUB_SITE_FLOXEM_PORT/health" \ + "$FLOXHUB_SITE_GITOLITE_PORT/health" \ + "$FLOXHUB_SITE_ACCOUNTS_PORT/api/v1/accounts/health" \ + "$FLOXHUB_SITE_FACTORY_PORT/api/v1/factory/health" \ + "$FLOXHUB_SITE_BUILD_COORDINATOR_PORT/v1/coordinator/health" \ + "$FLOXHUB_SITE_WEB_BFF_PORT/api/health/status" \ + "$FLOXHUB_SITE_OPENFGA_PORT/healthz" +do + port=${probe%%/*}; path=/${probe#*/} + printf "%-6s %-48s " "$port" "$path" + curl -so /dev/null -w "%{http_code}\n" --max-time 5 \ + "http://${FLOXHUB_SITE_BIND_HOST}:${port}${path}" || echo "unreachable" +done +' +``` + +This is the authoritative check. It reaches every service directly, including +the ones the front door does not route. + +## Check through the front door + +One health endpoint is reachable without a credential: + +```bash +curl -fsS "${FLOXHUB_SITE_URL}/web-bff/api/health/status" +``` + +So are the two discovery documents, which show that the front door is serving +and that sign-in is available: + +```bash +curl -fsS "${FLOXHUB_SITE_URL}/dex/.well-known/openid-configuration" +curl -fsS "${FLOXHUB_SITE_URL}/.well-known/oauth-protected-resource" +``` + +The second is served from a rendered file rather than proxied, so it answers +even when the identity broker is stopped. A `404` there means your deployment +has the broker disabled, which the Flox CLI reads as "no login here". + +The catalog, factory, environment, and account prefixes all sit behind the +front door's authentication check. An unauthenticated probe of those paths +returns `401`. That `401` is itself useful — it shows the front door is +serving and the credential resolver answered — but it tells you nothing about +the service behind the prefix. + +`build-coordinator`, `openfga`, `floxem-gitolite`, and the credential +verification routes are not routed through the front door at all. Probe them +on the host. + +## Limits + + + A `200` from most of these endpoints means only that a process is running. + Do not treat it as confirmation that the deployment is working. + + +**A `200` is not readiness.** Most endpoints return a fixed literal. They +prove the process is running and its HTTP stack answers; they do not prove +the database is reachable, that migrations have run, or that any downstream +service is up. The `/ready` paths on `accounts`, `factory`, and +`build-coordinator` are placeholders that return `ready` unconditionally — +they carry no more information than `/health`. + +**`factory` answers healthy before it can build.** It depends on the base +catalog being populated. Until that has happened, +`/api/v1/factory/health` returns `200` while builds fail. Catalog freshness +is a separate signal; see +[Monitor FloxHub](/floxhub-onprem/administration/monitoring/overview). + +**A disabled component refuses connections by design.** Several components +are gated on site configuration, and one whose gate is off idles instead of +serving. Connection refused on its port is the expected state for a component +you have turned off, not a failure. + +**Process supervision is a separate question.** `flox services status` tells +you whether each service process is running, which is not what these +endpoints answer. A service can be `Running` with its HTTP listener broken, +and a service that crashed answers nothing at all. + +**Startup is not reported.** Several services wait on PostgreSQL and run +migrations before they bind. During that window the port refuses connections, +which looks identical to a service that failed to start. diff --git a/floxhub-onprem/administration/monitoring/overview.mdx b/floxhub-onprem/administration/monitoring/overview.mdx new file mode 100644 index 0000000..f614991 --- /dev/null +++ b/floxhub-onprem/administration/monitoring/overview.mdx @@ -0,0 +1,15 @@ +--- +title: "Monitor FloxHub" +description: "The signals available for watching a running deployment." +--- + + + **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. + + +## Planned contents + +Health, log, catalog-freshness, and background-job checks, what each one tells +you, and how to read them together. diff --git a/floxhub-onprem/administration/object-storage.mdx b/floxhub-onprem/administration/object-storage.mdx new file mode 100644 index 0000000..e83b59d --- /dev/null +++ b/floxhub-onprem/administration/object-storage.mdx @@ -0,0 +1,15 @@ +--- +title: "Object storage" +description: "Configuring an S3-compatible store for published packages." +--- + + + **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. + + +## Planned contents + +Ingress and egress URLs, publisher credentials, signing keys, consumer read +access and trust, and how to verify that publishing and installation work. diff --git a/floxhub-onprem/administration/overview.mdx b/floxhub-onprem/administration/overview.mdx new file mode 100644 index 0000000..5b1c460 --- /dev/null +++ b/floxhub-onprem/administration/overview.mdx @@ -0,0 +1,15 @@ +--- +title: "Administer FloxHub" +description: "Operate, configure, and maintain a FloxHub on-prem deployment." +--- + + + **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. + + +## Planned contents + +Links to getting started, configuration, maintenance, monitoring, security, +and user administration. diff --git a/floxhub-onprem/administration/postgresql.mdx b/floxhub-onprem/administration/postgresql.mdx new file mode 100644 index 0000000..83a04d3 --- /dev/null +++ b/floxhub-onprem/administration/postgresql.mdx @@ -0,0 +1,15 @@ +--- +title: "PostgreSQL" +description: "The databases FloxHub uses and how they are configured." +--- + + + **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. + + +## Planned contents + +Service databases, roles and permissions, connection settings, persistence, +and setup checks. diff --git a/floxhub-onprem/administration/security.mdx b/floxhub-onprem/administration/security.mdx new file mode 100644 index 0000000..781dceb --- /dev/null +++ b/floxhub-onprem/administration/security.mdx @@ -0,0 +1,15 @@ +--- +title: "Secure FloxHub" +description: "The security model of a FloxHub deployment." +--- + + + **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. + + +## Planned contents + +TLS setup, public and internal network boundaries, the identity and +authorization model, secret storage, and artifact-signing trust. diff --git a/floxhub-onprem/administration/users/identity.mdx b/floxhub-onprem/administration/users/identity.mdx new file mode 100644 index 0000000..a74e16b --- /dev/null +++ b/floxhub-onprem/administration/users/identity.mdx @@ -0,0 +1,15 @@ +--- +title: "User identity" +description: "Connecting FloxHub to your identity provider." +--- + + + **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. + + +## Planned contents + +The identity components, connector configuration, the browser login flow, +issuer and callback settings, identity mapping, and troubleshooting. diff --git a/floxhub-onprem/administration/users/overview.mdx b/floxhub-onprem/administration/users/overview.mdx new file mode 100644 index 0000000..c3c8ebe --- /dev/null +++ b/floxhub-onprem/administration/users/overview.mdx @@ -0,0 +1,15 @@ +--- +title: "Administer users" +description: "Provisioning and managing the people who use your deployment." +--- + + + **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. + + +## Planned contents + +Account provisioning, identity resolution, namespace ownership, access +behavior, and the operator-facing controls available. diff --git a/floxhub-onprem/install/flox-environment.mdx b/floxhub-onprem/install/flox-environment.mdx new file mode 100644 index 0000000..52ba49e --- /dev/null +++ b/floxhub-onprem/install/flox-environment.mdx @@ -0,0 +1,16 @@ +--- +title: "Install FloxHub using a Flox environment" +description: "The end-to-end installation procedure." +--- + + + **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. + + +## Planned contents + +Obtaining the packages, composing the site environment, configuring the +database and TLS, provisioning secrets, initializing the services, populating +the catalog, and verifying the result. diff --git a/floxhub-onprem/install/methods.mdx b/floxhub-onprem/install/methods.mdx new file mode 100644 index 0000000..8e5fe22 --- /dev/null +++ b/floxhub-onprem/install/methods.mdx @@ -0,0 +1,15 @@ +--- +title: "Installation methods" +description: "How FloxHub on-prem is installed and who supplies each component." +--- + + + **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. + + +## Planned contents + +Installing through a site Flox environment that includes the published base +environment. diff --git a/floxhub-onprem/install/next-steps.mdx b/floxhub-onprem/install/next-steps.mdx new file mode 100644 index 0000000..0e9dd53 --- /dev/null +++ b/floxhub-onprem/install/next-steps.mdx @@ -0,0 +1,15 @@ +--- +title: "Steps after installing" +description: "Connect a client and confirm the deployment works end to end." +--- + + + **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. + + +## Planned contents + +Installing the CLI, pointing it at your deployment, logging in, and completing +a first environment push, pull, and activation. diff --git a/floxhub-onprem/install/offline.mdx b/floxhub-onprem/install/offline.mdx new file mode 100644 index 0000000..4b78250 --- /dev/null +++ b/floxhub-onprem/install/offline.mdx @@ -0,0 +1,15 @@ +--- +title: "Offline and disconnected operation" +description: "What a FloxHub deployment can do without external network access." +--- + + + **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. + + +## Planned contents + +Which host and client operations reach the public internet, what a locally +mirrored deployment can do, and the current limits of disconnected operation. diff --git a/floxhub-onprem/install/overview.mdx b/floxhub-onprem/install/overview.mdx new file mode 100644 index 0000000..2445897 --- /dev/null +++ b/floxhub-onprem/install/overview.mdx @@ -0,0 +1,15 @@ +--- +title: "Install FloxHub on-prem" +description: "Start here to install FloxHub in your own infrastructure." +--- + + + **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. + + +## Planned contents + +Links to the requirements, installation methods, offline limitations, +reference architectures, post-installation steps, and instance upgrades. diff --git a/floxhub-onprem/install/requirements.mdx b/floxhub-onprem/install/requirements.mdx new file mode 100644 index 0000000..80259cf --- /dev/null +++ b/floxhub-onprem/install/requirements.mdx @@ -0,0 +1,15 @@ +--- +title: "Installation requirements" +description: "Host and client prerequisites for a FloxHub on-prem deployment." +--- + + + **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. + + +## Planned contents + +Platform constraints, network access, DNS and TLS, database and storage +requirements, and the credentials to have ready before you install. diff --git a/floxhub-onprem/intro.mdx b/floxhub-onprem/intro.mdx new file mode 100644 index 0000000..0da1036 --- /dev/null +++ b/floxhub-onprem/intro.mdx @@ -0,0 +1,94 @@ +--- +title: "Introduction to FloxHub on-prem" +description: "Run FloxHub inside your own infrastructure: what the offering includes, how it differs from the hosted service, and what you operate yourself." +--- + + + **This section is under construction.** FloxHub on-prem documentation is + being written section by section. Pages marked as placeholders have not + been written yet. + + +[FloxHub](/concepts/floxhub) is normally a cloud service that Flox operates +for you at [hub.flox.dev](https://hub.flox.dev). **FloxHub on-prem** is the +same product running on hardware you control, inside your own network, with +your own identity provider and your own database. + +You reach for it when your environments, packages, or the identity of the +people using them cannot leave your infrastructure — a regulated network, an +air-gapped segment, or a security policy that rules out a third-party service +holding your dependency graph. + +## What you get + +A FloxHub on-prem deployment runs the whole product, not a subset: + +- **A package catalog.** Your deployment holds its own catalog, populated + from upstream and refreshed on a schedule you configure. Clients resolve + and install packages from it without reaching the public internet. +- **Environment hosting.** Users `flox push` and `flox pull` + [environments](/concepts/environments) against your deployment, with the + same [generations](/concepts/generations) and audit trail as the hosted + service. +- **The web UI.** The same interface for browsing environments, packages, + and organization membership. +- **Builds and publishing.** Your users build and + [publish](/tutorials/build-and-publish) packages into your own catalog. +- **Identity and authorization.** Sign-in brokered through your existing + identity provider, with organizations, roles, and per-catalog access + control. + +## How it differs from hosted FloxHub + +| | Hosted FloxHub | FloxHub on-prem | +| --- | --- | --- | +| Where it runs | Flox infrastructure | Yours | +| Sign-in | GitHub, Google, GitLab, or [Enterprise SSO](/concepts/enterprise-sso) | Your identity provider, brokered by the deployment | +| Database | Managed by Flox | You provide and operate PostgreSQL | +| TLS and DNS | Managed by Flox | You provide the certificate and the name | +| Catalog refresh | Continuous, managed by Flox | Scheduled by your deployment | +| Package binaries | Catalog store provided per organization | You supply the object store | +| Upgrades | Continuous, no action from you | You choose when to upgrade | +| Backups | Managed by Flox | Yours to take and to test | + +The client experience is intended to be the same: the same `flox` CLI, the +same commands, pointed at your deployment instead of `hub.flox.dev`. + +## What you operate + +Installing FloxHub on-prem makes you its operator. That means: + +- **The host.** Provisioning it, sizing it, and keeping its operating system + patched. +- **PostgreSQL.** The deployment does not ship a database. You supply one, + and its availability and durability are yours. +- **The external URL, DNS, and TLS.** The URL you choose is baked into the + tokens the deployment issues, so it is a decision to make before the first + login rather than after. +- **Identity.** Connecting your identity provider and keeping that connection + working. +- **Object storage**, where you want published packages to carry binaries. +- **Backups and recovery.** Taking them, storing them, and verifying that + they restore. +- **Upgrades.** Choosing when to move to a new FloxHub generation and running + the upgrade. + +Flox supplies the software, the base environment that composes it, and the +documentation in this section. + +## Next steps + + + + Check your host, network, and database against the prerequisites. + + + See the supported topology before you provision anything. + + + Work through the installation procedure. + + + Configure, monitor, and maintain a running deployment. + + diff --git a/floxhub-onprem/reference-architectures/overview.mdx b/floxhub-onprem/reference-architectures/overview.mdx new file mode 100644 index 0000000..03f4780 --- /dev/null +++ b/floxhub-onprem/reference-architectures/overview.mdx @@ -0,0 +1,15 @@ +--- +title: "Reference architectures" +description: "Supported deployment topologies for FloxHub on-prem." +--- + + + **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. + + +## Planned contents + +The supported topology, what each component is responsible for, and how to +choose between architectures. diff --git a/floxhub-onprem/reference-architectures/single-host.mdx b/floxhub-onprem/reference-architectures/single-host.mdx new file mode 100644 index 0000000..9c6f771 --- /dev/null +++ b/floxhub-onprem/reference-architectures/single-host.mdx @@ -0,0 +1,16 @@ +--- +title: "Single-host deployment" +description: "Every FloxHub service on one host, with the database alongside 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. + + +## Planned contents + +The service topology, PostgreSQL composition, TLS edge, persistent state, +catalog storage, identity components, network boundaries, and what the +operator is responsible for. diff --git a/floxhub-onprem/upgrade/before-you-upgrade.mdx b/floxhub-onprem/upgrade/before-you-upgrade.mdx new file mode 100644 index 0000000..b0b7e7e --- /dev/null +++ b/floxhub-onprem/upgrade/before-you-upgrade.mdx @@ -0,0 +1,15 @@ +--- +title: "Before you upgrade" +description: "Plan an upgrade and confirm you can complete 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. + + +## Planned contents + +Supported source and target generations, client and component compatibility, +backups, migration prerequisites, downtime expectations, and preflight checks. diff --git a/floxhub-onprem/upgrade/instance.mdx b/floxhub-onprem/upgrade/instance.mdx new file mode 100644 index 0000000..f6b324b --- /dev/null +++ b/floxhub-onprem/upgrade/instance.mdx @@ -0,0 +1,15 @@ +--- +title: "Upgrade an instance" +description: "Perform the upgrade." +--- + + + **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. + + +## Planned contents + +The update operation, the migration sequence, expected downtime, and post- +upgrade checks. diff --git a/floxhub-onprem/upgrade/maintenance-policy.mdx b/floxhub-onprem/upgrade/maintenance-policy.mdx new file mode 100644 index 0000000..ddfec39 --- /dev/null +++ b/floxhub-onprem/upgrade/maintenance-policy.mdx @@ -0,0 +1,15 @@ +--- +title: "Releases and maintenance" +description: "Which FloxHub generations are supported and for how long." +--- + + + **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. + + +## Planned contents + +Generation identifiers, release cadence, supported generations, the +maintenance lifecycle, CLI compatibility, and the security-update policy. diff --git a/floxhub-onprem/upgrade/overview.mdx b/floxhub-onprem/upgrade/overview.mdx new file mode 100644 index 0000000..97f426d --- /dev/null +++ b/floxhub-onprem/upgrade/overview.mdx @@ -0,0 +1,15 @@ +--- +title: "Upgrade FloxHub" +description: "Move a deployment to a newer FloxHub generation." +--- + + + **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. + + +## Planned contents + +Links to preparation, the upgrade procedure, troubleshooting and rollback, and +the release maintenance policy. diff --git a/floxhub-onprem/upgrade/troubleshooting-and-rollback.mdx b/floxhub-onprem/upgrade/troubleshooting-and-rollback.mdx new file mode 100644 index 0000000..8a15a91 --- /dev/null +++ b/floxhub-onprem/upgrade/troubleshooting-and-rollback.mdx @@ -0,0 +1,15 @@ +--- +title: "Troubleshooting and rolling back" +description: "Recover from an upgrade that did not complete." +--- + + + **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. + + +## Planned contents + +Failure symptoms, diagnosis, recovery choices, the rollback procedure, and +when restoring the database is required. diff --git a/llms.txt b/llms.txt index 9c3a48b..97f8fc1 100644 --- a/llms.txt +++ b/llms.txt @@ -117,6 +117,63 @@ Key terms: - [GitLab CI](https://flox.dev/docs/imageless-kubernetes/examples/gitlab-ci.md): Demo running GitLab CI with Imageless Kubernetes - [Web server with Redis on kind](https://flox.dev/docs/imageless-kubernetes/examples/kind-demo.md): Demo running a simple web server backed by Redis on kind +## FloxHub on-prem + +- [Introduction to FloxHub on-prem](https://flox.dev/docs/floxhub-onprem/intro.md): Run FloxHub inside your own infrastructure: what the offering includes, how it differs from the hosted service, and what you operate yourself. + +## FloxHub on-prem: Install + +- [Install FloxHub on-prem](https://flox.dev/docs/floxhub-onprem/install/overview.md): Start here to install FloxHub in your own infrastructure. +- [Installation requirements](https://flox.dev/docs/floxhub-onprem/install/requirements.md): Host and client prerequisites for a FloxHub on-prem deployment. +- [Installation methods](https://flox.dev/docs/floxhub-onprem/install/methods.md): How FloxHub on-prem is installed and who supplies each component. +- [Install FloxHub using a Flox environment](https://flox.dev/docs/floxhub-onprem/install/flox-environment.md): The end-to-end installation procedure. +- [Offline and disconnected operation](https://flox.dev/docs/floxhub-onprem/install/offline.md): What a FloxHub deployment can do without external network access. +- [Steps after installing](https://flox.dev/docs/floxhub-onprem/install/next-steps.md): Connect a client and confirm the deployment works end to end. + +## FloxHub on-prem: Reference architectures + +- [Reference architectures](https://flox.dev/docs/floxhub-onprem/reference-architectures/overview.md): Supported deployment topologies for FloxHub on-prem. +- [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 + +- [Administer FloxHub](https://flox.dev/docs/floxhub-onprem/administration/overview.md): Operate, configure, and maintain a FloxHub on-prem deployment. +- [Get started administering FloxHub](https://flox.dev/docs/floxhub-onprem/administration/get-started.md): The first checks after installation and the routine operator tasks. +- [Configure FloxHub](https://flox.dev/docs/floxhub-onprem/administration/configure.md): Where site configuration lives and how to apply it. +- [Environment variables](https://flox.dev/docs/floxhub-onprem/administration/environment-variables.md): The site configuration contract and its defaults. +- [Log system](https://flox.dev/docs/floxhub-onprem/administration/logs.md): Where each service writes its logs and how to read them. +- [Object storage](https://flox.dev/docs/floxhub-onprem/administration/object-storage.md): Configuring an S3-compatible store for published packages. +- [PostgreSQL](https://flox.dev/docs/floxhub-onprem/administration/postgresql.md): The databases FloxHub uses and how they are configured. +- [Base catalog](https://flox.dev/docs/floxhub-onprem/administration/base-catalog.md): Populating and refreshing the package catalog. +- [Secure FloxHub](https://flox.dev/docs/floxhub-onprem/administration/security.md): The security model of a FloxHub deployment. +- [Factory](https://flox.dev/docs/floxhub-onprem/administration/factory.md): Building and publishing packages inside your deployment. +- [Automatic environment upgrades](https://flox.dev/docs/floxhub-onprem/administration/environment-upgrades.md): Keeping managed environments current on a schedule. + +## FloxHub on-prem: Administer: Monitoring + +- [Monitor FloxHub](https://flox.dev/docs/floxhub-onprem/administration/monitoring/overview.md): The signals available for watching a running deployment. +- [Health check](https://flox.dev/docs/floxhub-onprem/administration/monitoring/health-check.md): The HTTP health endpoints each FloxHub service exposes, how to call them, and what each one proves. + +## FloxHub on-prem: Administer: Maintain + +- [Maintain FloxHub](https://flox.dev/docs/floxhub-onprem/administration/maintain/overview.md): Routine and recovery procedures for a running deployment. +- [Back up and restore](https://flox.dev/docs/floxhub-onprem/administration/maintain/backup-restore.md): Protecting deployment state and recovering it. +- [Restart FloxHub](https://flox.dev/docs/floxhub-onprem/administration/maintain/restart.md): Stopping and starting services safely. +- [Troubleshoot an installation](https://flox.dev/docs/floxhub-onprem/administration/maintain/troubleshooting.md): Diagnose and recover from common failures. + +## FloxHub on-prem: Administer: Users + +- [Administer users](https://flox.dev/docs/floxhub-onprem/administration/users/overview.md): Provisioning and managing the people who use your deployment. +- [User identity](https://flox.dev/docs/floxhub-onprem/administration/users/identity.md): Connecting FloxHub to your identity provider. + +## FloxHub on-prem: Upgrade + +- [Upgrade FloxHub](https://flox.dev/docs/floxhub-onprem/upgrade/overview.md): Move a deployment to a newer FloxHub generation. +- [Before you upgrade](https://flox.dev/docs/floxhub-onprem/upgrade/before-you-upgrade.md): Plan an upgrade and confirm you can complete it. +- [Upgrade an instance](https://flox.dev/docs/floxhub-onprem/upgrade/instance.md): Perform the upgrade. +- [Troubleshooting and rolling back](https://flox.dev/docs/floxhub-onprem/upgrade/troubleshooting-and-rollback.md): Recover from an upgrade that did not complete. +- [Releases and maintenance](https://flox.dev/docs/floxhub-onprem/upgrade/maintenance-policy.md): Which FloxHub generations are supported and for how long. + ## Concepts - [What is a Flox environment?](https://flox.dev/docs/concepts/environments.md): Everything you need to know about Flox environments. diff --git a/styles/config/vocabularies/Flox/accept.txt b/styles/config/vocabularies/Flox/accept.txt index fcca5ec..bc0431b 100644 --- a/styles/config/vocabularies/Flox/accept.txt +++ b/styles/config/vocabularies/Flox/accept.txt @@ -62,6 +62,7 @@ IPs json Karpenter libiconv +liveness lockfile lockfiles mailcap From 6fcbbda06c9692fa0d9e1bbcad1bc274a8be3d18 Mon Sep 17 00:00:00 2001 From: Isaac Karrer Date: Mon, 28 Sep 2026 16:36:09 -0500 Subject: [PATCH 2/7] docs(floxhub-onprem): document user identity (ENT-361) Replace the placeholder with the connector configuration an operator needs: the three-step flow for attaching a provider, minimal working examples for Okta, Entra ID, AD FS, and LDAP, and why SAML is not offered. Two facts get prominence because getting them wrong is expensive. The external URL is baked into every token the deployment issues, so it has to be right before the first sign-in rather than after. And the deployment derives a user's handle from the `preferred_username` claim, so a provider that sends neither that nor `name` produces an authenticated identity that cannot be provisioned. Also states what authenticating does not buy: directory group membership does not map to organizations or roles, so a group grant yields a working sign-in and nothing more. `Entra`, `Okta`, `lowercased`, `misconfigured`, and `rollout` join the Vale vocabulary. Co-Authored-By: Claude Opus 5 --- .../administration/users/identity.mdx | 231 +++++++++++++++++- llms.txt | 2 +- styles/config/vocabularies/Flox/accept.txt | 5 + 3 files changed, 228 insertions(+), 10 deletions(-) diff --git a/floxhub-onprem/administration/users/identity.mdx b/floxhub-onprem/administration/users/identity.mdx index a74e16b..f930f22 100644 --- a/floxhub-onprem/administration/users/identity.mdx +++ b/floxhub-onprem/administration/users/identity.mdx @@ -1,15 +1,228 @@ --- title: "User identity" -description: "Connecting FloxHub to your identity provider." +description: "Connect your identity provider to a FloxHub on-prem deployment, and understand the sign-in flow it drives." --- - - **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 FloxHub on-prem deployment holds no passwords. Sign-in is delegated to the +identity provider you already run, through an OIDC broker that ships with the +deployment. -## Planned contents +The broker is what keeps your configuration small. It translates whatever your +provider speaks into one consistent OIDC interface, so the rest of FloxHub is +configured identically on every deployment — including when your provider +already speaks OIDC. All the variation between deployments lives in one +connector file. -The identity components, connector configuration, the browser login flow, -issuer and callback settings, identity mapping, and troubleshooting. +## Before your first sign-in + +The external URL you choose is baked into every token the deployment issues, +and the broker advertises it as its issuer. Set `FLOXHUB_SITE_URL` to the real +external URL **before** anyone signs in, not after — changing it later +invalidates the tokens already issued against the old value. + +See [Environment variables](/floxhub-onprem/administration/environment-variables) +for where that setting lives. + +## Connect your provider + +Three steps, the same for every provider. + +**1. Write the connector.** Create `dex/connectors.yaml` in the deployment's +cache directory, with a top-level `connectors:` key. The examples below give +the minimal shape for each provider. + +**2. Register the callback URL** with your provider: + +```text +${FLOXHUB_SITE_URL}/dex/callback +``` + +**3. Render the configuration and restart the broker:** + +```bash +flox activate -- bash -c 'floxhub-init render && flox services restart dex' +``` + +The connector file is yours to protect — it holds a client secret or a bind +password: + +```bash +chmod 600 "$FLOX_ENV_CACHE/dex/connectors.yaml" +``` + + + Rendering refuses to proceed when a required value is unset or a required + file is missing, and it rejects a broker configuration that does not parse. + Until a render has succeeded, the front door and the broker refuse to start. + Run `floxhub-init check` to see the same report without rendering. + + +### Okta + +Create an **OIDC — Web Application** app integration in the Okta admin +console, with the callback URL as the sign-in redirect URI. + +```yaml +connectors: + - type: oidc + id: okta + name: Okta + config: + issuer: https://.okta.com + clientID: + clientSecret: + redirectURI: https:///dex/callback +``` + +### Entra ID + +Register an application under **App registrations** — web platform, with the +callback URL as the redirect URI — and create a client secret. The `microsoft` +connector handles the Entra specifics. + +```yaml +connectors: + - type: microsoft + id: entra + name: Entra ID + config: + tenant: + clientID: + clientSecret: + redirectURI: https:///dex/callback +``` + +### AD FS + +AD FS 2016 and later expose OIDC directly, so connect through OIDC rather than +SAML. Create an **Application Group** with a Server application, register the +callback URL, and generate a shared secret. + +```yaml +connectors: + - type: oidc + id: adfs + name: AD FS + config: + issuer: https:///adfs + clientID: + clientSecret: + redirectURI: https:///dex/callback +``` + +### LDAP and Active Directory + +The LDAP connector binds with a read-only service account and authenticates +users by search-then-bind. + +```yaml +connectors: + - type: ldap + id: ldap + name: Directory + config: + host: ldap.example.com:636 + bindDN: cn=floxhub,ou=services,dc=example,dc=com + bindPW: + userSearch: + baseDN: ou=people,dc=example,dc=com + filter: "(objectClass=person)" + username: uid # sAMAccountName for Active Directory + idAttr: uid + emailAttr: mail + nameAttr: cn +``` + +Group search is deliberately omitted. Group membership from your directory +does not currently drive authorization in FloxHub; see +[What your provider does not decide](#what-your-provider-does-not-decide). + +### SAML is not supported + +FloxHub does not offer a SAML connector. The upstream implementation is +unmaintained, is documented as likely vulnerable to authentication bypass, and +is under consideration for removal. + +Every provider above — and most providers of the SAML era — also expose OIDC. +Connect through that instead. + +### Other providers + +The four above are the configurations FloxHub documents. The broker supports +more, and options beyond these minimal examples are documented upstream at +[dexidp.io/docs/connectors](https://dexidp.io/docs/connectors/). + +## What the deployment takes from your provider + +On a successful sign-in, the deployment reads three things from the identity +your provider asserts: + +| Claim | What it becomes | +| --- | --- | +| Issuer and subject | The stable link between the person and their FloxHub user | +| `preferred_username`, or `name` if absent | The starting point for their FloxHub handle | +| `email`, `name`, avatar | Their displayed profile | + +Because the issuer and subject are what identify the person, the FloxHub user +survives a change of display name or email address. For how a handle is +derived from that username claim, and what happens when it cannot be, see +[Administer users](/floxhub-onprem/administration/users/overview). + + + Your provider must send `preferred_username` or `name`. An identity carrying + neither cannot be provisioned, and the sign-in fails. + + +## What your provider does not decide + +Authenticating proves who somebody is. It does not grant them anything beyond +their own personal namespace. + +Directory group membership does not currently map to FloxHub organizations or +roles. Organization membership is managed inside FloxHub, and a person's groups +in your directory have no effect on it. Plan for that: adding somebody to a +directory group gets them a working sign-in, not access to a shared namespace. + +## Verify and troubleshoot + +Confirm the broker is answering and advertising the issuer you expect: + +```bash +curl -fsS "${FLOXHUB_SITE_URL}/dex/.well-known/openid-configuration" +``` + +The `issuer` in the response must match `${FLOXHUB_SITE_URL}/dex` exactly. If +it does not, `FLOXHUB_SITE_URL` is wrong — fix it, re-render, and restart. + +Confirm the CLI can discover sign-in: + +```bash +curl -fsS "${FLOXHUB_SITE_URL}/.well-known/oauth-protected-resource" +``` + +A `404` here means the deployment has the broker disabled, which the Flox CLI +reads as "no sign-in available here". + +| Symptom | Where to look | +| --- | --- | +| Broker will not start | `floxhub-init check` — the render is missing or older than its inputs | +| Sign-in reaches your provider but fails on return | The callback URL registered with your provider, and `redirectURI` in the connector | +| Tokens rejected as issued by the wrong issuer | `FLOXHUB_SITE_URL` changed after the first sign-in | +| Sign-in fails for one person only | Their username claim, or a handle already taken — see [Administer users](/floxhub-onprem/administration/users/overview) | + +Broker logs carry the provider's own error responses, which is where a +misconfigured client secret or an unregistered callback shows up. See +[Log system](/floxhub-onprem/administration/logs). + +## Re-render after any change + +The rendered configuration is derived from your settings, your secrets, and +the connector file. Any change to those means rendering again — including +after you upgrade the deployment: + +```bash +flox activate -- bash -c 'floxhub-init render && flox services restart dex' +``` + +Activation warns you when the rendered files are older than their inputs, and +the front door and broker refuse to start until you have re-rendered. diff --git a/llms.txt b/llms.txt index 97f8fc1..a180ce6 100644 --- a/llms.txt +++ b/llms.txt @@ -164,7 +164,7 @@ Key terms: ## FloxHub on-prem: Administer: Users - [Administer users](https://flox.dev/docs/floxhub-onprem/administration/users/overview.md): Provisioning and managing the people who use your deployment. -- [User identity](https://flox.dev/docs/floxhub-onprem/administration/users/identity.md): Connecting FloxHub to your identity provider. +- [User identity](https://flox.dev/docs/floxhub-onprem/administration/users/identity.md): Connect your identity provider to a FloxHub on-prem deployment, and understand the sign-in flow it drives. ## FloxHub on-prem: Upgrade diff --git a/styles/config/vocabularies/Flox/accept.txt b/styles/config/vocabularies/Flox/accept.txt index bc0431b..1382bbd 100644 --- a/styles/config/vocabularies/Flox/accept.txt +++ b/styles/config/vocabularies/Flox/accept.txt @@ -48,6 +48,7 @@ dotenv dotfile dotfiles eksctl +Entra env envs formatters @@ -65,8 +66,10 @@ libiconv liveness lockfile lockfiles +lowercased mailcap manpages +misconfigured monorepo monorepos namespace @@ -76,12 +79,14 @@ Nodejs npm Nvidia nvm +Okta papercuts personalizations postgres rc repo repos +rollout runtimes sandboxed sandboxing From 94fe704671f49a9891e1a002d003954ddf7a9523 Mon Sep 17 00:00:00 2001 From: Isaac Karrer Date: Mon, 28 Sep 2026 16:36:09 -0500 Subject: [PATCH 3/7] docs(floxhub-onprem): document user administration (ENT-360) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the placeholder with how a person becomes a user of a deployment: provisioning as a side effect of a first successful sign-in, how the handle is derived and what grammar it must satisfy, and the single namespace users and organizations share. The failure modes get a section of their own. A handle collision has no self-service resolution, because the handle is derived rather than chosen, so two directory usernames that sanitize to the same handle block the second person's sign-in until the provider sends something different. That is cheap to check before a rollout and expensive to discover during one. Records the operator controls that do not exist — no invite flow, no deactivation, no organization deletion, no directory group links, no administrative user listing — so they are planned around rather than searched for. Revocation belongs at the identity provider, and does not reach tokens already issued. Organization and membership management is named but left to the follow-up that covers it. Co-Authored-By: Claude Opus 5 --- .../administration/users/overview.mdx | 155 +++++++++++++++++- llms.txt | 2 +- 2 files changed, 147 insertions(+), 10 deletions(-) diff --git a/floxhub-onprem/administration/users/overview.mdx b/floxhub-onprem/administration/users/overview.mdx index c3c8ebe..1836eb2 100644 --- a/floxhub-onprem/administration/users/overview.mdx +++ b/floxhub-onprem/administration/users/overview.mdx @@ -1,15 +1,152 @@ --- title: "Administer users" -description: "Provisioning and managing the people who use your deployment." +description: "How people become users of a FloxHub on-prem deployment, what access they get, and which operator controls exist today." --- - - **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. - +There is no screen for creating a user. A person becomes a user of your +deployment by signing in successfully for the first time, through the identity +provider you connected. Provisioning is a side effect of authentication. -## Planned contents +That shapes everything on this page: the control you have over who may use the +deployment lives in your identity provider, not in FloxHub. Read +[User identity](/floxhub-onprem/administration/users/identity) first for how +that connection is configured. -Account provisioning, identity resolution, namespace ownership, access -behavior, and the operator-facing controls available. +## What happens at first sign-in + +The deployment identifies a person by the issuer and subject your provider +asserts. On each sign-in it looks for an existing user holding that pair: + +- **Found.** The sign-in resolves to that existing user. Nothing is created. +- **Not found.** A user is provisioned: a FloxHub identifier is minted, a + handle is claimed, the profile is recorded, and the user is granted ownership + of their personal namespace. + +Because the identifier is minted by FloxHub rather than taken from your +provider, a person's display name or email address can change without +disturbing anything they own. + +## Handles + +A handle is the name that identifies a user across the deployment. It names +their personal namespace, so it appears in every environment reference and +catalog name they own. + +The handle is derived from your provider's `preferred_username` claim, falling +back to `name`. The value is lowercased, every run of characters outside +`a-z0-9` becomes a single hyphen, and leading and trailing hyphens are +dropped. The result must then satisfy the handle grammar: + +| Rule | Value | +| --- | --- | +| Length | 2 to 39 characters | +| Format | Lowercase letters and digits, single hyphens between them | +| Reserved | Names beginning `flox` cannot be claimed | +| Reserved | Anything that parses as a UUID cannot be claimed | + +So `Alice.Smith@example.com` as a username claim becomes the handle +`alice-smith-example-com`. If that is not the shape you want your users to +have, set the claim your provider sends rather than trying to correct it +afterwards. + +Users and organizations draw from **one** namespace. A handle held by an +organization cannot also be held by a user, and comparison ignores case, so +`Alice` and `alice` are the same name. + +## When a first sign-in fails + +The person authenticated correctly and still has no account. Three causes, +distinguishable from the logs: + +| Cause | What the operator does | +| --- | --- | +| The identity carries neither `preferred_username` nor `name` | Configure your provider to send one | +| The derived handle is already taken | Change the username claim your provider sends for that person | +| The derived handle breaks the grammar — too short, or empty after sanitizing | Same: fix the claim at the provider | + + + A handle collision has no self-service resolution. The person cannot be + prompted to pick a different name, because the handle is derived rather than + chosen. Two directory users whose usernames sanitize to the same handle means + the second one cannot sign in until you change what your provider sends. + + +This is worth checking before a large rollout. If your directory usernames are +email addresses, two people at different domains with the same local part +collide. + +## What a new user can do + +A provisioned user owns their personal namespace and its catalog, and nothing +else. They can push, pull, and activate their own environments, and publish +into their own catalog. + +They get no access to another user's namespace, and none to a shared one. +Shared access comes from organization membership, which is managed inside +FloxHub and is not derived from your directory. + +## Organizations and roles + +An organization is the sharing unit: its handle names a namespace and catalog +that its members reach. Members hold one of three roles: + +| Role | Intent | +| --- | --- | +| `owner` | Full control, including managing members and service accounts | +| `writer` | Read and write the organization's environments and catalog | +| `reader` | Read only | + +Two constraints worth knowing before you plan around them: + +- **An organization always keeps at least one owner.** A change or removal that + would leave none is refused. +- **There is no organization deletion.** Deleting one would delete a catalog + and orphan every environment in its namespace, and the rules for who may do + that do not exist yet. + +Full organization and membership management, including the machine identities +an organization can hold, is documented separately as that guidance is +completed. + +## Revoking access + +**Revoke at your identity provider.** Removing or disabling a person there +stops them signing in, which is the control that actually closes the door. + +Two things that revocation does not cover: + +- **Existing tokens.** A personal access token keeps working until it is + revoked or expires, independently of whether its owner can still sign in. + Treat token revocation as a separate step. See + [Personal access tokens](/concepts/personal-access-tokens). +- **What they own.** Environments and published packages in their personal + namespace are unaffected by losing access. + + + FloxHub has no notion of a deactivated user. There is no flag to set and no + suspended state to put somebody in — the account either exists or it does + not. + + +## What does not exist yet + +Plan around these rather than looking for the setting: + +- **No invite flow.** You cannot pre-create an account or send an invitation. + Access begins with a successful sign-in. +- **No deactivation.** As above. +- **No organization deletion.** As above. +- **No directory group links.** Group membership in your provider does not map + to FloxHub organizations or roles. Adding somebody to a directory group gets + them a working sign-in and nothing more. +- **No administrative user browser.** There is no operator screen listing every + user of the deployment. + +## Where to look + +| Question | Where | +| --- | --- | +| Why can this person not sign in at all? | [User identity](/floxhub-onprem/administration/users/identity) | +| Why did this person's first sign-in fail? | [Log system](/floxhub-onprem/administration/logs) | +| What is the authorization model? | [Secure FloxHub](/floxhub-onprem/administration/security) | +| How does a user get set up on their machine? | [Steps after installing](/floxhub-onprem/install/next-steps) | diff --git a/llms.txt b/llms.txt index a180ce6..355fb3b 100644 --- a/llms.txt +++ b/llms.txt @@ -163,7 +163,7 @@ Key terms: ## FloxHub on-prem: Administer: Users -- [Administer users](https://flox.dev/docs/floxhub-onprem/administration/users/overview.md): Provisioning and managing the people who use your deployment. +- [Administer users](https://flox.dev/docs/floxhub-onprem/administration/users/overview.md): How people become users of a FloxHub on-prem deployment, what access they get, and which operator controls exist today. - [User identity](https://flox.dev/docs/floxhub-onprem/administration/users/identity.md): Connect your identity provider to a FloxHub on-prem deployment, and understand the sign-in flow it drives. ## FloxHub on-prem: Upgrade From b9322355c8eced1e5e2aad6286ebd2cf69aae05d Mon Sep 17 00:00:00 2001 From: Isaac Karrer Date: Tue, 29 Sep 2026 08:37:01 -0500 Subject: [PATCH 4/7] docs(floxhub-onprem): document installation requirements (ENT-340) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the placeholder with the hard prerequisites: host platform, the Nix features catalog population needs, the database you supply, the external URL, network egress, the systems your catalog serves, and the identity provider. Three of these are easy to discover too late. The external URL is baked into every token the deployment issues, so it is a decision made before installing rather than after. The front door speaks plain HTTP and holds no certificate, so TLS termination belongs to your own edge. And the Nix feature requirement is retained rather than install-time — every periodic catalog refresh needs it. Sizing is deliberately absent. Stating that it is being measured is more useful than guidance this page cannot yet support, and the follow-up scoped to it will fill it in. `loopback` joins the Vale vocabulary. Co-Authored-By: Claude Opus 5 --- floxhub-onprem/install/requirements.mdx | 161 +++++++++++++++++++-- llms.txt | 2 +- styles/config/vocabularies/Flox/accept.txt | 1 + 3 files changed, 154 insertions(+), 10 deletions(-) diff --git a/floxhub-onprem/install/requirements.mdx b/floxhub-onprem/install/requirements.mdx index 80259cf..aab53a8 100644 --- a/floxhub-onprem/install/requirements.mdx +++ b/floxhub-onprem/install/requirements.mdx @@ -1,15 +1,158 @@ --- title: "Installation requirements" -description: "Host and client prerequisites for a FloxHub on-prem deployment." +description: "Host, database, network, and credential prerequisites for a FloxHub on-prem deployment." --- - - **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. - +Check these before you provision anything. Everything here is a hard +prerequisite: the installation either cannot start or cannot finish without it. -## Planned contents + + This page covers what a deployment **requires**. It does not yet give sizing + guidance — how much CPU, memory, and disk to allocate for a given number of + users or a full catalog. Those figures are being measured and will be + published here once they are. + -Platform constraints, network access, DNS and TLS, database and storage -requirements, and the credentials to have ready before you install. +## Host + +| Requirement | Value | +| --- | --- | +| Platform | Linux on `x86_64` | +| Flox | Installed on the host | +| Nix | Present, with the `nix-command` and `flakes` features enabled | + +A deployment is a Flox environment, so [Flox](/install-flox/install) is the one +piece of tooling you install by hand. Everything else arrives as part of the +environment. + +The Nix feature requirement is not incidental and does not go away after +installation. Populating and refreshing the catalog evaluates flake outputs and +reads store path metadata, so both the first catalog population and every +periodic refresh need those features enabled. + + + Generating a fresh signing key for a binary store does **not** need either + feature, so that step works on a host where they are unavailable. + + +The host platform is separate from the systems your deployment serves. A single +`x86_64` Linux host can serve a catalog for macOS and Linux clients on both +architectures — see [Client systems](#client-systems). + +## Database + +The deployment does not run PostgreSQL. You supply one and you operate it. + +| Requirement | Detail | +| --- | --- | +| A reachable PostgreSQL server | Addressed by host and port in your site configuration | +| A role and password | Supplied to the deployment as a secret file | +| Several databases | Created by the deployment, or pre-created by you | + +Each component keeps its own database. The deployment creates them on first +start **if** the role you gave it may create databases. If your policy does not +allow that, pre-create them and grant the role access instead; the deployment +then migrates its own schema into each one. + +The database is the deployment's durable state. Its availability is your +deployment's availability, and its backups are your deployment's backups. + +## The external URL + +Choose the URL users will reach before you install, not after. + +The URL is baked into every token the deployment issues, and it is what the +deployment advertises to the Flox CLI. Changing it later invalidates the tokens +already issued against the old value, so treat it as a decision made up front. + +You need: + +- **A DNS name** resolving to the host, for the URL you chose. +- **A TLS certificate** for that name. + + + The deployment's front door speaks plain HTTP. It does not terminate TLS, and + it has no certificate configuration. You terminate TLS in front of it and + proxy through — the certificate is held by your own edge, not by FloxHub. + + +## Network access + +By default the deployment binds every component to loopback and exposes only +the front door, so the port you publish is the front door's. + +Outbound, an installation reaches: + +| Destination | What needs it | +| --- | --- | +| A Nix binary cache | Package metadata collection, and fetching the deployment's own packages | +| The upstream package source | Populating and refreshing the catalog | +| FloxHub | Fetching the published base environment your site configuration includes | + +All three are configurable, so a deployment can point at mirrors you host +instead. Doing so does not make the deployment fully disconnected — see +[Offline and disconnected operation](/floxhub-onprem/install/offline) for what +a locally mirrored deployment can and cannot do. + +## Client systems + +Declare which systems your deployment's catalog serves. This is the set your +users can resolve and install packages for, and it is independent of the host's +own platform. + +The four Flox supports are `x86_64-linux`, `aarch64-linux`, `x86_64-darwin`, +and `aarch64-darwin`. Narrowing the list to the systems you actually support +makes catalog population meaningfully cheaper, so set it deliberately rather +than taking the default. + +## Identity provider + +Sign-in is delegated, so you need a provider before anyone can use the +deployment. + +| Requirement | Detail | +| --- | --- | +| An OIDC-capable provider | Okta, Entra ID, AD FS, and LDAP or Active Directory are the documented configurations | +| A registered client | Client ID and secret, or a directory bind account | +| A username claim | The provider must send `preferred_username` or `name` | + +The username claim is easy to overlook and blocks sign-in when it is missing. +See [User identity](/floxhub-onprem/administration/users/identity) for the +connector configuration, and +[Administer users](/floxhub-onprem/administration/users/overview) for how that +claim becomes a user's handle. + +SAML is not supported. Connect through OIDC. + +## Credentials to prepare + +Have these ready before you begin. The installation procedure covers where each +one goes. + +- **The database role's password.** +- **Your identity provider's client secret**, or the bind password for a + directory account. +- **Secrets for the deployment's internal service-to-service calls** and for + signing web session cookies. You generate these; they are not supplied by + anyone. +- **Object store credentials and a signing key**, if you want published + packages to carry binaries. This is optional — a deployment runs without a + binary store, publishing package metadata only. + +## Optional + +| Component | Without it | +| --- | --- | +| An S3-compatible object store | Publishing records package metadata but carries no binaries | +| A package build service | Users cannot build packages inside the deployment | + +## Next + + + + See how the components are laid out before provisioning the host. + + + How a deployment is assembled and who supplies each part. + + diff --git a/llms.txt b/llms.txt index 355fb3b..97e4c9d 100644 --- a/llms.txt +++ b/llms.txt @@ -124,7 +124,7 @@ Key terms: ## FloxHub on-prem: Install - [Install FloxHub on-prem](https://flox.dev/docs/floxhub-onprem/install/overview.md): Start here to install FloxHub in your own infrastructure. -- [Installation requirements](https://flox.dev/docs/floxhub-onprem/install/requirements.md): Host and client prerequisites for a FloxHub on-prem deployment. +- [Installation requirements](https://flox.dev/docs/floxhub-onprem/install/requirements.md): Host, database, network, and credential prerequisites for a FloxHub on-prem deployment. - [Installation methods](https://flox.dev/docs/floxhub-onprem/install/methods.md): How FloxHub on-prem is installed and who supplies each component. - [Install FloxHub using a Flox environment](https://flox.dev/docs/floxhub-onprem/install/flox-environment.md): The end-to-end installation procedure. - [Offline and disconnected operation](https://flox.dev/docs/floxhub-onprem/install/offline.md): What a FloxHub deployment can do without external network access. diff --git a/styles/config/vocabularies/Flox/accept.txt b/styles/config/vocabularies/Flox/accept.txt index 1382bbd..0fb68ae 100644 --- a/styles/config/vocabularies/Flox/accept.txt +++ b/styles/config/vocabularies/Flox/accept.txt @@ -66,6 +66,7 @@ libiconv liveness lockfile lockfiles +loopback lowercased mailcap manpages From ec2b6abf087bd87a77c99ea30c14a1402e2108ac Mon Sep 17 00:00:00 2001 From: Isaac Karrer Date: Tue, 29 Sep 2026 08:37:15 -0500 Subject: [PATCH 5/7] docs(floxhub-onprem): document reference architectures (ENT-344) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the placeholder with the overview: a diagram of where the components sit, a table of what each one is responsible for, and the boundary between what runs on the host and what you supply. States plainly that one topology is documented — a single host — so the question is whether it fits rather than which to choose. Says what it does not give you: no component runs redundantly and an upgrade stops services, so availability rests on the host and database you supply and on your ability to restore from backup. Separated, redundant, and managed-component arrangements are named as undocumented rather than left for a reader to assume either way. 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..dd6db4c 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 | Terminates 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 97e4c9d..66f16f1 100644 --- a/llms.txt +++ b/llms.txt @@ -132,7 +132,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 From 8cd4c253c5bd0bd71cb05a2ca7fe80beadc524f0 Mon Sep 17 00:00:00 2001 From: Isaac Karrer Date: Tue, 29 Sep 2026 10:49:39 -0500 Subject: [PATCH 6/7] docs(floxhub-onprem): document object storage (ENT-352) Replace the placeholder with the per-catalog store configuration: why a new deployment publishes metadata only, the store types and which one on-prem uses, the API call that attaches a store, and the difference between the ingress URI publishing writes through and the egress URL installs read from. Two points get emphasis because they diverge from the hosted service. FloxHub hands a publishing client the bucket URI and nothing else, so whoever publishes must already hold write credentials and there is no per-user scoping inside FloxHub. And consumers substitute nothing unsigned, so a signing key and the trust that clients place in its name are part of making a store useful rather than an afterthought. The verification section insists on two machines. A single-machine publish and install succeeds with no object store at all, because the local store already holds the build, so it proves nothing about the round trip. `substituter` and `unconfigured` join the Vale vocabulary. Co-Authored-By: Claude Opus 5 --- .../administration/object-storage.mdx | 183 +++++++++++++++++- llms.txt | 2 +- styles/config/vocabularies/Flox/accept.txt | 2 + 3 files changed, 177 insertions(+), 10 deletions(-) diff --git a/floxhub-onprem/administration/object-storage.mdx b/floxhub-onprem/administration/object-storage.mdx index e83b59d..31bb5d0 100644 --- a/floxhub-onprem/administration/object-storage.mdx +++ b/floxhub-onprem/administration/object-storage.mdx @@ -1,15 +1,180 @@ --- title: "Object storage" -description: "Configuring an S3-compatible store for published packages." +description: "Configure an S3-compatible store so published packages carry binaries, sign them, and let consumers trust and substitute them." --- - - **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. - +Publishing a package to your deployment records two different things: the +package's metadata in the catalog, and the built binaries themselves. The +catalog always takes the metadata. Binaries need somewhere to go, and that +somewhere is an S3-compatible object store you supply. -## Planned contents +## The default: metadata only -Ingress and egress URLs, publisher credentials, signing keys, consumer read -access and trust, and how to verify that publishing and installation work. +A new deployment has no object store, and catalogs default to **metadata +only**. `flox publish` succeeds against such a catalog, and records everything +the catalog needs to resolve the package — but uploads no binaries, so nothing +can substitute the build. A consumer resolving that package has metadata and no +artifact to fetch. + +That default is deliberate: publishing works out of the box without making you +provision a bucket first. Configure a store when you want published packages to +be installable without rebuilding. + +## Store types + +| Type | Behavior | +| --- | --- | +| `meta-only` | Records metadata, uploads nothing | +| `nix-copy` | Copies the build closure to an S3-compatible store you own | +| `null` | Unconfigured. Publishing is refused until you choose a type | +| `publisher` | A credential-minting service. Not available on-prem | + +`nix-copy` is the type to use. The `publisher` type belongs to the hosted +service, which runs a component your deployment does not. + + + A catalog left `null` refuses publishing with a `422`. The error text names an + internal Flox tool; configure the store with the API call below instead. + + +## Configure a catalog's store + +Store configuration is per catalog, applied over the catalog API. Create the +catalog if it does not exist, then set its store: + +```bash +curl -fsS -X POST --oauth2-bearer "$TOKEN" \ + "${FLOXHUB_SITE_URL}/api/v1/catalog/catalogs/?name=${CATALOG}" +``` + +```bash +curl -fsS -X PUT --oauth2-bearer "$TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "store_type": "nix-copy", + "ingress_uri": "s3://?endpoint=https://", + "egress_uri": "https:///" + }' \ + "${FLOXHUB_SITE_URL}/api/v1/catalog/catalogs/${CATALOG}/store/config" +``` + +Read a catalog's current store back with the same path and `GET`. Setting a +store needs write access to that catalog. + +### Ingress and egress are different URLs + +| Field | Direction | Shape | +| --- | --- | --- | +| `ingress_uri` | Writes, during publish | An `s3://` URI naming the bucket, with the endpoint as a query parameter | +| `egress_uri` | Reads, during install | A plain HTTP URL serving the same bucket as a binary cache | + +They address one bucket by two routes. Publishing uses the S3 protocol and +needs credentials; installing is an ordinary cache read over HTTP. Add +`&scheme=http` to the ingress URI when your endpoint is not TLS-terminated. + +## Credentials belong to whoever publishes + +This is the part that differs most from the hosted service. + +With `nix-copy`, FloxHub hands the publishing client the bucket URI and nothing +else. It does not mint, hold, or proxy object-store credentials. **Whoever +publishes must already be able to write to the bucket**, authenticating with +standard AWS environment variables in their own environment: + +```bash +export AWS_ACCESS_KEY_ID= +export AWS_SECRET_ACCESS_KEY= +``` + + + Distributing write credentials for the store is yours to arrange, and there is + no per-user scoping inside FloxHub. Anyone who can publish to a catalog needs + bucket write access, and holds it directly. + + +Read access is separate and needs no credential if the egress URL serves the +bucket anonymously, which is the simplest arrangement. A private bucket means +every consumer needs read credentials too. + +## Sign what you publish + +Consumers will not substitute an unsigned artifact. Generate a binary cache key +pair once, and keep the private half with your deployment's other secrets: + +```bash +nix-store --generate-binary-cache-key \ + ./catalog-signing-private-key ./catalog-signing-public-key +``` + +```bash +chmod 600 ./catalog-signing-private-key +``` + +Pick a stable ``: it is recorded in every signature, and consumers +trust the name. Changing it invalidates trust for everything already published +under the old one. + +Point publishing at the private key, either once for an account: + +```bash +flox config --set publish.signing_private_key +``` + +or per publish: + +```bash +flox publish --signing-private-key +``` + +The first form is what a deployment's own build machinery uses, so its +publishes are signed without passing the flag each time. + + + Generating a key needs neither the `nix-command` nor the `flakes` feature, so + it works on a host where those are unavailable. + + +## Let consumers trust the key + +A client substitutes from your store only once it trusts the signing key. Add +the **public** key to the client's Nix configuration, alongside the store as a +substituter: + +```text +extra-trusted-public-keys = : +extra-substituters = https:/// +``` + +The value is the contents of the public key file generated above. Distribute it +however you distribute client configuration — it is not secret. + +## Verify it works + +Publishing succeeding is not proof that the store works; a metadata-only +publish also succeeds. Prove the round trip instead, using **two machines** with +independent Nix stores: + +1. On the first, publish a package to the configured catalog with a signing key. +2. On the second — one that has never built the package — install it. + +If the second machine installs without building, the closure reached the store +and came back out of it. Doing this on one machine proves nothing: a local store +already holds the build, so the install would succeed with no object store at +all. + +Check along the way: + +```bash +curl -fsI "https:////nix-cache-info" +``` + +A readable `nix-cache-info` confirms the egress URL is serving as a binary +cache. If publishing fails, the cause is almost always bucket credentials or an +ingress endpoint that does not match your store. + +## Deployment-wide defaults + +Store configuration is per catalog today, so each catalog that should carry +binaries is configured on its own. A deployment-wide default store, so new +catalogs inherit one rather than being configured individually, is being added +and will be documented here. diff --git a/llms.txt b/llms.txt index 66f16f1..d55292e 100644 --- a/llms.txt +++ b/llms.txt @@ -142,7 +142,7 @@ Key terms: - [Configure FloxHub](https://flox.dev/docs/floxhub-onprem/administration/configure.md): Where site configuration lives and how to apply it. - [Environment variables](https://flox.dev/docs/floxhub-onprem/administration/environment-variables.md): The site configuration contract and its defaults. - [Log system](https://flox.dev/docs/floxhub-onprem/administration/logs.md): Where each service writes its logs and how to read them. -- [Object storage](https://flox.dev/docs/floxhub-onprem/administration/object-storage.md): Configuring an S3-compatible store for published packages. +- [Object storage](https://flox.dev/docs/floxhub-onprem/administration/object-storage.md): Configure an S3-compatible store so published packages carry binaries, sign them, and let consumers trust and substitute them. - [PostgreSQL](https://flox.dev/docs/floxhub-onprem/administration/postgresql.md): The databases FloxHub uses and how they are configured. - [Base catalog](https://flox.dev/docs/floxhub-onprem/administration/base-catalog.md): Populating and refreshing the package catalog. - [Secure FloxHub](https://flox.dev/docs/floxhub-onprem/administration/security.md): The security model of a FloxHub deployment. diff --git a/styles/config/vocabularies/Flox/accept.txt b/styles/config/vocabularies/Flox/accept.txt index 0fb68ae..d2e7aa3 100644 --- a/styles/config/vocabularies/Flox/accept.txt +++ b/styles/config/vocabularies/Flox/accept.txt @@ -105,6 +105,7 @@ subproblems subprojects subshell subshells +substituter systemd tcsh toolchain @@ -113,6 +114,7 @@ toplevel transactionally tzdata UIDs +unconfigured uninstallation unintuitive unmerged From 37e46c173b56397ddf7d07a59ef2456f67830f00 Mon Sep 17 00:00:00 2001 From: Isaac Karrer Date: Tue, 29 Sep 2026 11:21:18 -0500 Subject: [PATCH 7/7] docs(floxhub-onprem): reconcile with the existing published guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Comparing the new pages against `customer/signing-keys` and the Flox install instructions turned up three things worth correcting. The object-storage page reimplemented, thinly, what `customer/signing-keys` already covers properly: where trusted keys live for standalone Nix, NixOS, nix-darwin, and home-manager, restarting the daemon on each platform, and verifying a key took effect. It now defers to that page and keeps only what is specific to running your own store. It also states that the private key path must be absolute, which that page warns about and this one had omitted. The requirements page gained the trusted-key prerequisite for the host. It is usually already satisfied, because the Flox installer configures those keys — so it only bites a host where Flox arrived through Nix, and then it presents as the deployment's own packages failing to install. Co-Authored-By: Claude Opus 5 --- .../administration/object-storage.mdx | 26 ++++++++++++++----- floxhub-onprem/install/requirements.mdx | 9 +++++++ 2 files changed, 28 insertions(+), 7 deletions(-) diff --git a/floxhub-onprem/administration/object-storage.mdx b/floxhub-onprem/administration/object-storage.mdx index 31bb5d0..99c5438 100644 --- a/floxhub-onprem/administration/object-storage.mdx +++ b/floxhub-onprem/administration/object-storage.mdx @@ -117,27 +117,33 @@ under the old one. Point publishing at the private key, either once for an account: ```bash -flox config --set publish.signing_private_key +flox config --set publish.signing_private_key /absolute/path/to/private-key ``` or per publish: ```bash -flox publish --signing-private-key +flox publish --signing-private-key /absolute/path/to/private-key ``` The first form is what a deployment's own build machinery uses, so its publishes are signed without passing the flag each time. + + The private key path must be absolute. A relative path is rejected. + + - Generating a key needs neither the `nix-command` nor the `flakes` feature, so - it works on a host where those are unavailable. + `nix-store --generate-binary-cache-key` needs neither the `nix-command` nor + the `flakes` feature, so it works on a host where those are unavailable. + [Signing keys](/customer/signing-keys) shows the equivalent `nix key` + commands, which do need them. ## Let consumers trust the key A client substitutes from your store only once it trusts the signing key. Add -the **public** key to the client's Nix configuration, alongside the store as a +the **public** key to the client's trusted keys, and your store as a substituter: ```text @@ -145,8 +151,14 @@ extra-trusted-public-keys = : extra-substituters = https:/// ``` -The value is the contents of the public key file generated above. Distribute it -however you distribute client configuration — it is not secret. +The value is the contents of the public key file, and it is not secret — +distribute it however you distribute client configuration. + +Where those settings live differs by how the client installed Nix, and applying +them needs the Nix daemon restarted. +[Signing keys](/customer/signing-keys) covers both in full, for standalone Nix, +NixOS, nix-darwin, and home-manager, along with how to verify a key is trusted. +Everything there applies unchanged to an on-prem store. ## Verify it works diff --git a/floxhub-onprem/install/requirements.mdx b/floxhub-onprem/install/requirements.mdx index aab53a8..af3ef6d 100644 --- a/floxhub-onprem/install/requirements.mdx +++ b/floxhub-onprem/install/requirements.mdx @@ -20,11 +20,20 @@ prerequisite: the installation either cannot start or cannot finish without it. | Platform | Linux on `x86_64` | | Flox | Installed on the host | | Nix | Present, with the `nix-command` and `flakes` features enabled | +| Trusted keys | The host must trust the keys FloxHub's own packages are signed with | A deployment is a Flox environment, so [Flox](/install-flox/install) is the one piece of tooling you install by hand. Everything else arrives as part of the environment. +The trusted-keys requirement is easy to miss because it is usually already +satisfied: the Flox installer configures those keys for you. A host where Flox +was installed through Nix instead — `nix profile install`, or a NixOS or +nix-darwin configuration — does not have them, and installing the deployment's +packages fails for want of a trusted key. The +[generic Nix install instructions](/install-flox/install#generic-nix) give the +values to add. + The Nix feature requirement is not incidental and does not go away after installation. Populating and refreshing the catalog evaluates flake outputs and reads store path metadata, so both the first catalog population and every