docs: Astro/Starlight documentation site (supersedes #108)

.github/workflows/docs-preview-cleanup.yml

@@ -0,0 +1,40 @@
+name: Docs preview cleanup
+# When a PR closes (merged or not), delete the Cloudflare Pages preview
+# deployments for that branch. Direct Upload deploys are not tied to the git
+# branch lifecycle, so without this they linger after the branch is gone.
+on:
+  pull_request:
+    types: [closed]
+permissions:
+  contents: read
+concurrency:
+  group: docs-preview-cleanup-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+env:
+  CF_PROJECT: llm-serving-pack
+jobs:
+  cleanup:
+    # Fork PRs never get a preview (deploy is skipped, secrets unavailable),
+    # so there is nothing to clean up for them.
+    if: ${{ github.event.pull_request.head.repo.full_name == github.repository }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Delete this branch's preview deployments
+        env:
+          CF_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CF_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          BRANCH: ${{ github.event.pull_request.head.ref }}
+        run: |
+          set -euo pipefail
+          base="https://api.cloudflare.com/client/v4/accounts/${CF_ACCOUNT_ID}/pages/projects/${CF_PROJECT}/deployments"
+          ids=$(curl -fsS -H "Authorization: Bearer ${CF_API_TOKEN}" "${base}?env=preview&per_page=100" \
+            | jq -r --arg b "$BRANCH" '.result[] | select(.deployment_trigger.metadata.branch == $b) | .id')
+          if [ -z "$ids" ]; then
+            echo "No preview deployments found for branch '$BRANCH'."
+            exit 0
+          fi
+          for id in $ids; do
+            echo "Deleting preview deployment $id (branch '$BRANCH')"
+            curl -fsS -X DELETE -H "Authorization: Bearer ${CF_API_TOKEN}" "${base}/${id}?force=true" >/dev/null
+          done
+          echo "Cleaned up preview deployments for branch '$BRANCH'."

.github/workflows/docs.yml

@@ -0,0 +1,86 @@
+name: Docs
+on:
+  push:
+    branches: [main]
+    paths: ['docs/**', 'scripts/check-links.sh', '.github/workflows/docs.yml']
+  pull_request:
+    paths: ['docs/**', 'scripts/check-links.sh', '.github/workflows/docs.yml']
+  workflow_dispatch:
+permissions:
+  contents: read
+  pull-requests: write
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+env:
+  PACK_SLUG: llm-serving-pack
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install deps
+        working-directory: docs
+        run: npm ci
+
+      - name: Install Playwright (mermaid rendering)
+        working-directory: docs
+        run: npx playwright install --with-deps chromium
+
+      - name: Unit tests
+        working-directory: docs
+        run: npm test
+
+      - name: Compute site, base, and deploy branch
+        id: base
+        env:
+          HEAD_REF: ${{ github.head_ref || github.ref_name }}
+        run: |
+          if [ "${{ github.ref }}" = "refs/heads/main" ]; then
+            echo "site=https://packs.nebari.dev" >> "$GITHUB_OUTPUT"
+            echo "base=/${PACK_SLUG}/" >> "$GITHUB_OUTPUT"
+            echo "branch=main" >> "$GITHUB_OUTPUT"
+          else
+            ALIAS=$(printf '%s' "$HEAD_REF" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g')
+            echo "site=https://${ALIAS}.${PACK_SLUG}.pages.dev" >> "$GITHUB_OUTPUT"
+            echo "base=/" >> "$GITHUB_OUTPUT"
+            echo "branch=${HEAD_REF}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build
+        working-directory: docs
+        env:
+          SITE: ${{ steps.base.outputs.site }}
+          BASE: ${{ steps.base.outputs.base }}
+        run: npm run build
+
+      - name: Check internal links
+        env:
+          BASE: ${{ steps.base.outputs.base }}
+        run: SKIP_BUILD=1 bash scripts/check-links.sh
+
+      # Fork PRs cannot read secrets; skip deploy there (build + link-check still gate).
+      - name: Deploy to Cloudflare Pages
+        id: deploy
+        if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy docs/dist --project-name=${{ env.PACK_SLUG }} --branch=${{ steps.base.outputs.branch }}
+
+      - name: Comment preview URL
+        if: ${{ github.event_name == 'pull_request' && steps.deploy.outcome == 'success' }}
+        uses: thollander/actions-comment-pull-request@v3
+        with:
+          comment-tag: docs-preview
+          message: |
+            📄 **Docs preview** for `${{ github.event.pull_request.head.ref }}`:
+            ${{ steps.deploy.outputs.pages-deployment-alias-url }}

Makefile

@@ -0,0 +1,35 @@
+# nebari-llm-serving-pack
+#
+# Tasks for the Astro/Starlight documentation site (lives in docs/).
+# Run `make help` to list targets.
+#
+# For the local kind dev cluster, see the separate dev/Makefile
+# (`cd dev && make help`). For Go tests, see operator/ and key-manager/.
+
+DOCS_DIR := docs
+
+.DEFAULT_GOAL := help
+.PHONY: help docs docs-install docs-build docs-preview docs-test docs-check-links
+
+help: ## List available targets
+	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| sort \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-16s\033[0m %s\n", $$1, $$2}'
+
+docs: ## Run the docs site dev server with hot reload (installs deps on first run)
+	cd $(DOCS_DIR) && { [ -d node_modules ] || npm install; } && npm run dev
+
+docs-install: ## Install docs site dependencies from the lockfile (npm ci)
+	cd $(DOCS_DIR) && npm ci
+
+docs-build: ## Build the static docs site into docs/dist
+	cd $(DOCS_DIR) && npm run build
+
+docs-preview: ## Serve the built docs/dist locally to preview the production build
+	cd $(DOCS_DIR) && npm run preview
+
+docs-test: ## Run the docs unit tests (vitest)
+	cd $(DOCS_DIR) && npm test
+
+docs-check-links: ## Build the site and verify every internal link resolves
+	bash scripts/check-links.sh

README.md

@@ -2,6 +2,8 @@
 
 A [Nebari](https://github.com/nebari-dev/nebari-infrastructure-core) software pack for serving LLMs. Deploys a Kubernetes operator that manages LLM model serving via [llm-d](https://llm-d.ai), with per-model access control, API key management, and Envoy AI Gateway integration for token counting and rate limiting.
 
+**Documentation:** [https://nebari-dev.github.io/nebari-llm-serving-pack/](https://nebari-dev.github.io/nebari-llm-serving-pack/)
+
 ## What this does
 
 You apply an `LLMModel` custom resource and the operator handles the rest: model download, vLLM serving pods, inference scheduling, routing, and auth.
@@ -19,7 +21,7 @@ Models can be loaded from HuggingFace (default) or mounted as OCI/modelcar image
 - Kubernetes 1.28+ cluster with [Nebari Infrastructure Core](https://github.com/nebari-dev/nebari-infrastructure-core) deployed
 - [nebari-operator](https://github.com/nebari-dev/nebari-operator) running
 - NVIDIA GPU Operator installed (auto-discovers GPU nodes and manages the device plugin). **Note**: nebari-infrastructure-core does not install this automatically yet - tracked in [nebari-dev/nebari-infrastructure-core#232](https://github.com/nebari-dev/nebari-infrastructure-core/issues/232). Until that is done, install it manually as an ArgoCD app (see [examples/nvidia-gpu-operator.yaml](examples/nvidia-gpu-operator.yaml)).
-- **Envoy Gateway installed and configured for AI Gateway integration** - `extensionApis.enableBackend`, `extensionManager` pointing at the AI Gateway controller service, and `backendResources` allowing `inference.networking.k8s.io/InferencePool`. This is a **hard requirement**; without it, the routing layer 404s at runtime. Ready-to-apply example in [`examples/envoy-gateway.yaml`](examples/envoy-gateway.yaml); see [`docs/install-production.md`](docs/install-production.md#6-reconfigure-envoy-gateway-with-ai-gateway-extension-wiring) for details.
+- **Envoy Gateway installed and configured for AI Gateway integration** - `extensionApis.enableBackend`, `extensionManager` pointing at the AI Gateway controller service, and `backendResources` allowing `inference.networking.k8s.io/InferencePool`. This is a **hard requirement**; without it, the routing layer 404s at runtime. Ready-to-apply example in [`examples/envoy-gateway.yaml`](examples/envoy-gateway.yaml); see the [Installation guide](https://nebari-dev.github.io/nebari-llm-serving-pack/installation/#6-reconfigure-envoy-gateway-with-ai-gateway-extension-wiring) for details.
 - Envoy AI Gateway installed (v0.5.0+). **Note**: the `envoyAIGateway.install` flag in this chart is not yet implemented - tracked in [#44](https://github.com/nebari-dev/nebari-llm-serving-pack/issues/44). Until that is done, install it manually as an ArgoCD app (see [examples/envoy-ai-gateway.yaml](examples/envoy-ai-gateway.yaml)).
 - [Gateway API Inference Extension](https://github.com/kubernetes-sigs/gateway-api-inference-extension) (GIE) installed (InferencePool / InferenceModel CRDs).
 - A cert-manager `ClusterIssuer` the operator can use for the shared-hostname Certificate. Default expected name is `letsencrypt-production`; override with `platform.tls.clusterIssuer` in the chart values.
@@ -248,7 +250,7 @@ The pack expects the following to be available on the cluster:
 
 ## Development
 
-See [docs/getting-started.md](docs/getting-started.md) for a full walkthrough of the local dev environment.
+See the [Local Development guide](https://nebari-dev.github.io/nebari-llm-serving-pack/local-development/) for a full walkthrough of the local dev environment.
 
 ```bash
 # Create kind cluster with all dependencies
@@ -281,6 +283,43 @@ cd operator && make test
 cd key-manager && go test ./...
 ```
 
+### Documentation site
+
+The docs site is an [Astro](https://astro.build) + [Starlight](https://starlight.astro.build) project living in [`docs/`](docs/). The common tasks are wrapped in the root `Makefile` (run `make help` to list them):
+
+```bash
+make docs             # dev server with hot reload at http://localhost:4321
+make docs-build       # build the static site into docs/dist
+make docs-preview     # serve the built site to preview the production build
+make docs-test        # run the unit tests (vitest)
+make docs-check-links # build, then verify every internal link resolves
+```
+
+**Add a page:** create a Markdown file under `docs/src/content/docs/`, then add a `sidebar` entry for it in [`docs/astro.config.mjs`](docs/astro.config.mjs). Pages use standard Starlight frontmatter and support Mermaid diagrams (rendered to SVG at build time).
+
+**Add or remove a component:** shared UI lives in `docs/src/components/` (Astro and React). The shadcn-style primitives under `docs/src/components/ui/` are tracked in `docs/components.json`; edit that directory and reference the component from a page or another component.
+
+**Images:** put images in `docs/src/assets/` and reference them with a relative path (for example `../../assets/foo.png`) so Astro optimizes, hashes, and base-path-corrects them at build time. Only genuinely static files such as `favicon.svg` belong in `docs/public/`.
+
+The site is built and deployed to Cloudflare Pages by [`.github/workflows/docs.yml`](.github/workflows/docs.yml); the [CI/CD and Releasing](docs/src/content/docs/cicd-and-releasing.md) page documents the pipeline.
+
+## Known Limitations
+
+This pack is at alpha maturity (`v0.1.0-alpha.x`). The following limitations apply:
+
+- **Single-namespace model:** All LLMModels must be in the operator's own namespace. Per-team isolation requires running separate pack installs (one namespace per team). This is a hard constraint imposed by Envoy Gateway's `apiKeyAuth`, which does not support cross-namespace Secret references.
+- **API keys are not continuously tied to group membership.** Keys are issued based on the user's OIDC groups at creation time. If a user later loses group access, existing keys continue to work. The periodic audit that revokes such keys (default interval: 5 minutes) is **off by default** - it only runs when `keyManager.oidcUserinfoURL` is configured, which ships empty. Without it, keys are never revoked on group change. Even when enabled, this is eventual consistency, not real-time revocation.
+- **JWKS path is Keycloak-specific.** The internal endpoint's JWT SecurityPolicy constructs the JWKS URI as `<issuerURL>/protocol/openid-connect/certs`. Non-Keycloak OIDC providers will not work out of the box. Tracked in [#61](https://github.com/nebari-dev/nebari-llm-serving-pack/issues/61).
+- **NVIDIA GPUs only.** AMD and Intel accelerators are not supported in v0.1.
+- **No scale-to-zero.** Idle model pods are not scaled down automatically.
+- **No per-key rate limiting or token quotas.** Rate limiting is applied at the model level via Envoy AI Gateway, not per individual API key.
+- **No API key expiration.** Keys do not expire on a schedule; revocation requires either manual deletion or - only when the audit is enabled via `keyManager.oidcUserinfoURL` - the audit detecting lost group access.
+- **No team-level shared API keys.** Each key is tied to an individual user's identity.
+- **OCI model loading uses init-container copy.** Kubernetes image volumes (alpha/beta) are not used; every pod start copies files from the OCI image to a shared emptyDir. On pods with `storage.type: emptyDir` and `preload: true`, every restart triggers a full re-download.
+- **API key and metadata storage is limited to ~1 MiB per model** (Kubernetes Secret/ConfigMap size limit). This supports several thousand keys per model; it is a known scaling ceiling for v0.1.
+- **`envoyAIGateway.install` flag is not yet implemented.** Envoy AI Gateway must be installed separately. Tracked in [#44](https://github.com/nebari-dev/nebari-llm-serving-pack/issues/44).
+- **Per-model subdomains are not yet wired into routing.** The `endpoints.external.subdomain` field is validated but unused. All models share `llm.<baseDomain>`; per-model dispatch is by the `model` field in the request body.
+
 ## License
 
 Apache 2.0. See [LICENSE](LICENSE).

docs/.gitignore

@@ -0,0 +1,27 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+
+# bake-off screenshots (local only)
+bakeoff-screenshots/
+
+# Editor
+.vscode/

docs/astro.config.mjs

@@ -0,0 +1,73 @@
+// docs/astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import react from '@astrojs/react';
+import tailwindcss from '@tailwindcss/vite';
+import rehypeMermaid from 'rehype-mermaid';
+import { fileURLToPath } from 'url';
+import path from 'path';
+import remarkBaseLinks from './src/plugins/remark-base-links';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+  // Base defaults to '/' for the local bake-off. Override via BASE env if deployed.
+  base: process.env.BASE || '/',
+  site: process.env.SITE,
+  integrations: [
+    react(),
+    starlight({
+      title: 'LLM Serving Pack',
+      description:
+        'Kubernetes operator for serving LLMs on Nebari via llm-d, with per-model OIDC access control, API key management, and Envoy AI Gateway integration.',
+      logo: {
+        light: './src/assets/logo.svg',
+        dark: './src/assets/logo-dark.svg',
+        replacesTitle: false,
+      },
+      customCss: [
+        '@fontsource-variable/geist',
+        '@fontsource/ibm-plex-mono',
+        './src/styles/nebari-tokens.css',
+        './src/styles/starlight-theme.css',
+      ],
+      components: {
+        SocialIcons: './src/components/SocialIcons.astro',
+      },
+      sidebar: [
+        {
+          label: 'Documentation',
+          items: [
+            { label: 'Quickstart', slug: 'quickstart' },
+            { label: 'Installation', slug: 'installation' },
+            { label: 'Local Development', slug: 'local-development' },
+            { label: 'Shared Storage', slug: 'shared-storage' },
+            { label: 'Troubleshooting', slug: 'troubleshooting' },
+          ],
+        },
+        {
+          label: 'Reference',
+          items: [
+            { label: 'Configuration', slug: 'configuration' },
+            { label: 'Architecture', slug: 'architecture' },
+            { label: 'CI/CD and Releasing', slug: 'cicd-and-releasing' },
+          ],
+        },
+      ],
+    }),
+  ],
+  markdown: {
+    // syntaxHighlight false on mermaid so the plugin sees raw graph source.
+    syntaxHighlight: { type: 'shiki', excludeLangs: ['mermaid'] },
+    remarkPlugins: [[remarkBaseLinks, { base: process.env.BASE || '/' }]],
+    rehypePlugins: [[rehypeMermaid, { strategy: 'inline-svg' }]],
+  },
+  vite: {
+    plugins: [tailwindcss()],
+    resolve: {
+      alias: {
+        '@': path.resolve(__dirname, './src'),
+      },
+    },
+  },
+});

docs/components.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-vega",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/styles/nebari-tokens.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "utils": "@/lib/utils",
+    "hooks": "@/hooks"
+  },
+  "registries": {
+    "@nebari": "https://nebari-dev.github.io/nebari-design/r/{name}.json"
+  }
+}