diff --git a/docs.json b/docs.json index f7706aa..42cee04 100644 --- a/docs.json +++ b/docs.json @@ -110,6 +110,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..99c5438 --- /dev/null +++ b/floxhub-onprem/administration/object-storage.mdx @@ -0,0 +1,192 @@ +--- +title: "Object storage" +description: "Configure an S3-compatible store so published packages carry binaries, sign them, and let consumers trust and substitute them." +--- + +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. + +## The default: metadata only + +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 /absolute/path/to/private-key +``` + +or per publish: + +```bash +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. + + + + `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 trusted keys, and your store as a +substituter: + +```text +extra-trusted-public-keys = : +extra-substituters = https:/// +``` + +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 + +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/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..f930f22 --- /dev/null +++ b/floxhub-onprem/administration/users/identity.mdx @@ -0,0 +1,228 @@ +--- +title: "User identity" +description: "Connect your identity provider to a FloxHub on-prem deployment, and understand the sign-in flow it drives." +--- + +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. + +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. + +## 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/floxhub-onprem/administration/users/overview.mdx b/floxhub-onprem/administration/users/overview.mdx new file mode 100644 index 0000000..1836eb2 --- /dev/null +++ b/floxhub-onprem/administration/users/overview.mdx @@ -0,0 +1,152 @@ +--- +title: "Administer users" +description: "How people become users of a FloxHub on-prem deployment, what access they get, and which operator controls exist today." +--- + +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. + +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. + +## 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/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..af3ef6d --- /dev/null +++ b/floxhub-onprem/install/requirements.mdx @@ -0,0 +1,167 @@ +--- +title: "Installation requirements" +description: "Host, database, network, and credential prerequisites for a FloxHub on-prem deployment." +--- + +Check these before you provision anything. Everything here is a hard +prerequisite: the installation either cannot start or cannot finish without it. + + + 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. + + +## Host + +| Requirement | Value | +| --- | --- | +| 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 +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/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..dd6db4c --- /dev/null +++ b/floxhub-onprem/reference-architectures/overview.mdx @@ -0,0 +1,133 @@ +--- +title: "Reference architectures" +description: "The supported deployment topology for FloxHub on-prem, what each component does, and where your infrastructure meets it." +--- + +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. + +**One topology is documented today: a single host.** Every component runs on one +machine, with your database and your TLS edge beside it. + + + 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/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 3689795..9024237 100644 --- a/llms.txt +++ b/llms.txt @@ -118,6 +118,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, 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. +- [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): 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 + +- [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): 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. +- [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): 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 + +- [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..d2e7aa3 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 @@ -62,10 +63,14 @@ IPs json Karpenter libiconv +liveness lockfile lockfiles +loopback +lowercased mailcap manpages +misconfigured monorepo monorepos namespace @@ -75,12 +80,14 @@ Nodejs npm Nvidia nvm +Okta papercuts personalizations postgres rc repo repos +rollout runtimes sandboxed sandboxing @@ -98,6 +105,7 @@ subproblems subprojects subshell subshells +substituter systemd tcsh toolchain @@ -106,6 +114,7 @@ toplevel transactionally tzdata UIDs +unconfigured uninstallation unintuitive unmerged