Install on Kubernetes

Grounded ships a generic Kustomize base, optional components and two example overlays in the repository's deploy/kubernetes/. Your install writes its own overlay, in its own repository, that sets the namespace, pins the image, patches the settings, provides the secrets and picks components. Nothing specific to your organisation belongs in the Grounded repository.

Check the requirements first.

1. Write an overlayCopy Anchor Link

Reference the base and the components you need at a release tag. A small install:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: grounded

resources:
  - namespace.yaml   # your namespace, labelled for the restricted Pod Security Standard
  - https://github.com/ncecere/grounded//deploy/kubernetes/base?ref=v0.2.1

components:
  - https://github.com/ncecere/grounded//deploy/kubernetes/components/postgres-single?ref=v0.2.1
  - https://github.com/ncecere/grounded//deploy/kubernetes/components/valkey-single?ref=v0.2.1
  - https://github.com/ncecere/grounded//deploy/kubernetes/components/backup-pgdump?ref=v0.2.1
  - https://github.com/ncecere/grounded//deploy/kubernetes/components/ingress?ref=v0.2.1

images:
  - name: ghcr.io/ncecere/grounded
    newTag: v0.2.1             # informational
    digest: sha256:<digest>    # what is deployed

configMapGenerator:
  - name: grounded-config
    behavior: merge
    literals:
      - APP_URL=https://grounded.example.org
      - S3_ENDPOINT=https://s3.example.org
      - S3_BUCKET=grounded
      - OIDC_ALLOWED_EMAIL_DOMAINS=example.org
      - CRAWL_ALLOWLIST_SEED=*.example.org
      - TRUSTED_PROXIES=10.0.0.0/8

Copy example-small or example-ha from the repository as a starting point. Flux and Argo CD both build remote bases. Keep ?ref= on a tag, and bump it together with the image digest.

ComponentsCopy Anchor Link

2. Create the secretsCopy Anchor Link

The base references secrets by name only. Create them with your secrets operator or by hand.

A development-only example with random values:

ns=grounded
pg=$(openssl rand -hex 24); vk=$(openssl rand -hex 24)
kubectl -n $ns create secret generic grounded-runtime \
  --from-literal=ENCRYPTION_KEY="$(openssl rand -base64 32)" \
  --from-literal=API_KEY_PEPPER="$(openssl rand -base64 32)" \
  --from-literal=POSTGRES_PASSWORD="$pg" \
  --from-literal=DATABASE_URL="postgres://grounded:$pg@grounded-postgres:5432/grounded?sslmode=disable" \
  --from-literal=VALKEY_PASSWORD="$vk" \
  --from-literal=VALKEY_URL="redis://:$vk@grounded-valkey:6379/0" \
  --from-literal=OIDC_ISSUER=https://idp.example.org \
  --from-literal=OIDC_CLIENT_ID=grounded \
  --from-literal=OIDC_CLIENT_SECRET=change-me
kubectl -n $ns create secret generic grounded-s3 --from-literal=access_key=... --from-literal=secret_key=...

• Back up ENCRYPTION_KEY in your secret store. It encrypts the stored gateway, SMTP and moderation credentials; losing it makes them unreadable. Changing API_KEY_PEPPER without keeping the old value invalidates every API key. To change either, rotate.
• grounded-runtime is loaded as environment variables, so any other setting can live there too (for example BOOTSTRAP_ADMIN_SUBJECT). A key in the secret overrides the same key in grounded-config.
• With postgres-cnpg, leave DATABASE_URL and POSTGRES_PASSWORD out: the component takes the URL from the operator's secret.
• URL-encode passwords inside URLs, or generate them from a URL-safe alphabet (openssl rand -hex 24). Use rediss:// for a TLS Valkey endpoint.

3. Set the configurationCopy Anchor Link

Non-secret settings live in the grounded-config ConfigMap, generated from the base's config.env with a hash in its name. A configuration change therefore rolls the pods; there's nothing to restart by hand. Merge your keys with a configMapGenerator using behavior: merge (as above) or a patch on grounded-config. Don't create a plain grounded-config ConfigMap, and don't disable the name hash: the pods would keep the old settings.

Secrets aren't hashed: after changing one, run kubectl -n grounded rollout restart deploy/grounded-api deploy/grounded-worker.

Usually set: APP_URL, the S3 endpoint and bucket, OIDC_ALLOWED_EMAIL_DOMAINS, TRUSTED_PROXIES (the ingress controller's addresses, so client IPs and rate limits are right), your identity (INSTANCE_NAME, ORG_NAME, UI_LOGO_URL, SUPPORT_URL, TEAM_REQUEST_URL), CRAWL_ALLOWLIST_SEED if teams will crawl websites, and the SMTP settings. The configuration reference lists everything.

Safety checksCopy Anchor Link

Every process refuses to start on a non-loopback APP_URL when:

• ENCRYPTION_KEY or API_KEY_PEPPER is the public example value from .env.example;
• DEV_AUTH is on;
• APP_URL is http://.

The error names each setting. In a pod, kubectl logs <pod> -c migrate shows it first, since the init container stops the rollout. Settings that are allowed but deserve attention (an empty crawl allowlist, public agents without moderation, no SMTP, no email-domain restriction, SSO group rules without a groups claim) are logged at startup, listed under Needs attention in the admin portal, and printed by grounded doctor.

4. Apply and checkCopy Anchor Link

Apply the overlay, or commit it for your GitOps tool. Migrations run in each pod's migrate init container under a Postgres advisory lock, so concurrent pods are safe and only the first does the work. Then:

kubectl -n grounded exec deploy/grounded-api -c api -- /grounded doctor
kubectl -n grounded exec deploy/grounded-worker -c worker -- /grounded doctor --mode worker

grounded doctor checks the configuration and every dependency (Postgres, Valkey, object storage, the OIDC issuer and each model connection), with timings, and names what fails. The image is distroless: there's no shell, and the binary is /grounded.

5. The first platform adminCopy Anchor Link

Grounded has no default admin account. The first admin is named by their OIDC subject:

kubectl -n grounded exec -it grounded-postgres-0 -- psql -U grounded -d grounded \
  -c "SELECT email, oidc_subject FROM users ORDER BY created_at"

6. Set up the platformCopy Anchor Link

In the admin portal (its Overview has a setup checklist):

1. Add a model connection, a chat model and an embedding model, and an embedding profile.
2. Write the classification levels' descriptions and set each model's maximum classification.
3. Add crawl allowlist patterns if teams will crawl websites.
4. Set up a moderation policy before you turn public agents on.
5. Create the first team.
6. Set retention periods only after your records management has confirmed them. Until then Grounded keeps everything except anonymous conversations and evaluation runs.

To see the install working before any team exists, seed the demo.

Resource names and portsCopy Anchor Link

Overlays patch these names; they're stable through 0.x.

Every resource carries app.kubernetes.io/name: grounded and, per workload, app.kubernetes.io/component (api, worker, postgres, valkey, backup, tika, ocr). NetworkPolicies select on these labels.

Scheduling and security defaultsCopy Anchor Link

• API replicas spread across nodes with a hard topology spread constraint; workers with a soft one. Both PodDisruptionBudgets allow one pod down at a time and never let an unready pod block a node drain.
• Pods run non-root with a read-only root filesystem, no capabilities, no privilege escalation, seccomp RuntimeDefault, /tmp on an emptyDir and no service account token. Everything meets the restricted Pod Security Standard.
• NetworkPolicies deny everything in the namespace, then allow DNS, ingress to the API on 8080 from the ingress controller's namespace (grounded-api-ingress: patch the placeholder namespace), egress to Postgres and Valkey in the namespace, to in-cluster S3 on 9000, and to 443 and 80 anywhere (gateways, OIDC, external S3, the crawler). Add egress in your overlay for anything else: a managed database outside the namespace, SMTP (587/465), or model servers on other ports.
• The crawler's own address checks still refuse private addresses, whatever the NetworkPolicies allow.

IngressCopy Anchor Link

• The host must match APP_URL, and TLS must terminate at or before the ingress.
• Chat streams over Server-Sent Events. The controller must not buffer responses and must allow reads of a few minutes. Traefik and most Gateway implementations need nothing. For NGINX-based controllers, turn off proxy buffering and raise the read timeout (for example proxy-buffering: "off", proxy-read-timeout: "600"), and allow bodies up to MAX_UPLOAD_BYTES.
• Metrics are served on the internal port 9091, never through the Ingress; the public port answers 404 for /metrics.

TroubleshootingCopy Anchor Link