Self-hosting guides for the enterprise delivery

developer-guide/self-hosting/air-gapped.mdx

@@ -0,0 +1,63 @@
+---
+title: "Air-gapped deployments"
+description: "Running Fish Audio Enterprise on a network that cannot reach Fish Audio at all"
+icon: "shield-halved"
+---
+
+Both offline delivery forms make no outbound calls at runtime. Neither one, however,
+installs itself out of thin air: a Helm install pulls container images and the chart
+from a registry, and the appliance needs its image on the host. An air-gapped
+deployment is about getting those artifacts across the boundary.
+
+<Note>
+  Fish Audio does this with you as part of an air-gapped delivery, and the step-by-step
+  procedure is in the deployment runbook for the version you install — see
+  [Releases](/developer-guide/self-hosting/enterprise-releases). This page is what to
+  expect and what to plan for.
+</Note>
+
+## Which form to choose
+
+**The All-in-One appliance** is the straightforward answer to a strict air gap: one
+image with every weight baked in, moved to the disconnected host as a file and loaded
+there. There is nothing else to mirror.
+
+**The Helm chart** is more work, because the release is many images rather than one.
+Every image has to be mirrored into a registry the cluster can reach and the release
+pointed at it, component by component — there is no single switch. Plan for the whole
+set, and expect to do it with your account team rather than alone.
+
+**What you give up either way:** images are pinned to the exact content Fish Audio
+published, so a deployment cannot quietly run anything else. Copying an image into
+another registry drops that pin, so check what you mirrored while both sides are still
+there to compare.
+
+## Offline usage accounting
+
+An offline deployment cannot call a billing service, so it records usage locally
+instead, in a signed ledger on persistent storage. It is durable data rather than
+cache: include it in your backups, and agree a reconciliation cadence with your account
+team. Usage is settled from the ledger files themselves, not from totals compiled off
+them.
+
+Because there is no service to validate a token against, any non-empty bearer token is
+accepted and recorded as the billing identity. Use a stable, distinct token per tenant.
+
+## Proving there is no egress
+
+Regulated deployments usually need evidence rather than a configuration review, and the
+runbook carries the exercise. Two things are worth knowing before you plan it.
+
+It answers two questions, and they need different methods: whether the deployment
+*needs* the internet, and whether it *calls out* when allowed to — the second is what a
+telemetry or data-residency review actually asks.
+
+It is also a cluster-level exercise rather than a namespace one. Confirm early that
+whoever runs your cluster can take part, because a namespace-scoped account cannot
+complete it.
+
+## Next steps
+
+- [Requirements](/developer-guide/self-hosting/requirements) — hardware, platform, and network baselines
+- [All-in-One container](/developer-guide/self-hosting/all-in-one) — the single-container form
+- [Kubernetes deployment](/developer-guide/self-hosting/kubernetes) — the Helm forms

developer-guide/self-hosting/all-in-one.mdx

@@ -0,0 +1,77 @@
+---
+title: "All-in-One container"
+description: "The single-container appliance: what it is, what it cannot do, and what running it involves"
+icon: "box"
+---
+
+The All-in-One image packages the whole speech stack — edge API, model API layer,
+inference router and worker, vocoder, text normalizer, and Redis — into one container,
+with every model weight baked in. Once the image is on the host it runs with no
+Kubernetes and no internet access, which makes it the turnkey option for single-node
+appliances and strict air gaps.
+
+<Note>
+  This page covers what the appliance is and what to plan for. The commands, tuning
+  options, and troubleshooting are in the **All-in-One guide**, which ships in the
+  documentation bundle for the image version you run — see
+  [Releases](/developer-guide/self-hosting/enterprise-releases).
+</Note>
+
+## What it cannot do
+
+The appliance runs one inference worker and one vocoder, a GPU each. It does not
+autoscale, does not shard across more GPUs or nodes, and does not ship the forced
+aligner, so it returns no word or segment timings. It is offline-only — there is no
+hosted-billing variant. For elastic or higher-throughput deployments, use the
+[Kubernetes chart](/developer-guide/self-hosting/kubernetes), which scales replicas
+across all GPUs and nodes.
+
+## What running it involves
+
+One `docker run` on a host that meets the
+[All-in-One host requirements](/developer-guide/self-hosting/requirements#all-in-one-container-host).
+It needs:
+
+- **Two GPUs.** The first runs the inference worker, the second the vocoder.
+- **One exposed port** for the API.
+- **One persistent volume.** Compile caches, the vocoder's built engine, reference
+  voice archives, and the usage ledger all live there. Model weights are in the image,
+  not on the volume.
+
+Everything inside the container runs as a non-root user, so a reused volume or a host
+bind mount has to be writable by it.
+
+**Plan for a slow first start.** The worker compiles its inference graphs and the
+vocoder builds its engine before either serves, and the health endpoint verifies the
+speech backend end to end rather than reporting immediate liveness. Both artifacts are
+cached on the volume, so later starts take minutes. The vocoder engine is specific to
+the GPU model, so moving to different cards rebuilds it once.
+
+## Usage accounting and tenancy
+
+This build records usage to a local, signed, append-only ledger on the volume instead
+of calling a billing service. Two consequences worth designing around:
+
+- **Any non-empty bearer token is accepted**; a missing or empty one is rejected. The
+  appliance has nothing to validate a token against.
+- **The token is recorded verbatim as the billing identity.** Use a stable, distinct
+  token per tenant — two tenants sharing a token are indistinguishable in the ledger.
+
+See [Offline usage accounting](/developer-guide/self-hosting/air-gapped#offline-usage-accounting).
+
+## Capacity
+
+The single worker admits a bounded number of in-flight requests; beyond that, requests
+queue and time-to-first-audio climbs. The ceiling is set by the worker's key-value
+cache VRAM, so larger cards support a higher cap. It is adjustable at launch without
+rebuilding the image. Validate latency and error rate at any new value before
+committing to it.
+
+Reference-id requests resolve only from local archives placed on the volume, one zip
+per voice.
+
+## Next steps
+
+- [Requirements](/developer-guide/self-hosting/requirements#all-in-one-container-host) — host baseline
+- [Registry access](/developer-guide/self-hosting/registry-access) — how your team gets the image
+- [Air-gapped deployments](/developer-guide/self-hosting/air-gapped) — moving the image to a disconnected host