Skip to content

Kubernetes installation

Install Umbod from its OCI Helm chart. Start with kind for a local evaluation, or use the chart on an existing Kubernetes cluster.

Requirements

  • Kubernetes 1.25 or newer
  • Helm 3
  • kubectl
  • Docker and kind for the recommended local installation

Create a local cluster

Create a disposable cluster:

kind create cluster --name umbod --wait 2m
kubectl cluster-info --context kind-umbod

Start minikube and select its context:

minikube start --kubernetes-version=stable
kubectl config use-context minikube

Install Umbod locally

Install chart 0.0.1-beta.8 (which deploys core and frontend images 0.0.1-beta.8) with development authentication:

helm upgrade --install umbod \
  oci://ghcr.io/computerlovetech/charts/umbod \
  --version 0.0.1-beta.8 \
  --set config.profile=local \
  --set config.authentication.mode=dev \
  --set-string config.publicOrigins.site=http://localhost:3000 \
  --set-string config.publicOrigins.mcp=http://localhost:8011 \
  --wait --timeout 5m

Forward the frontend Service in one terminal:

kubectl port-forward service/umbod-frontend 3000:3000

In a second terminal, forward the MCP Service:

kubectl port-forward service/umbod-mcp 8011:8011

Open http://localhost:3000 and keep both port-forwards running. In the administration interface, open MCP setup guide to copy http://localhost:8011/mcp and follow the instructions for your desktop agent. Configure it as a remote HTTP MCP server; the agent and the port-forwards must run on the same computer. After configuring a connector, publish its tools and grant access before checking the agent's available tools.

The local setup uses development authentication. Hosted agents cannot reach your computer's localhost; use an HTTPS Ingress and production authentication for agents running elsewhere.

Validate the local installation

Inspect the workloads and run the chart tests:

kubectl get pods,services
helm test umbod --logs --timeout 2m

Configure a shared installation

Create a namespace and the required Secret. Replace the OIDC client secret before running the command:

kubectl create namespace umbod --dry-run=client -o yaml | kubectl apply -f -
ROOT_SECRET="$(openssl rand -hex 32)"
kubectl -n umbod create secret generic umbod-secrets \
  --from-literal=UMBOD_ROOT_SECRET="$ROOT_SECRET" \
  --from-literal=UMBOD_OIDC_CLIENT_SECRET='replace-with-your-client-secret'

Create values.production.yaml:

existingSecret: umbod-secrets

config:
  profile: production
  authentication:
    mode: auth0
    oidc:
      domain: your-tenant.example.com
      clientId: your-client-id
      audience: https://umbod.example.com
      requiredScopes: openid,email,profile,groups
  authorization:
    adminMembershipClaim: https://umbod.example.com/claims/groups
    mcpPermissionClaim: https://umbod.example.com/claims/groups
  publicOrigins:
    site: https://umbod.example.com
    api: https://umbod.example.com
    mcp: https://umbod.example.com

persistence:
  enabled: true
  size: 1Gi

ingress:
  enabled: true
  className: nginx
  host: umbod.example.com

For deployments using S3 for file bytes, follow S3 file-content storage. S3 does not replace the persistent application database.

Review the generated Helm values reference before installing. In particular, confirm the ingress class, public origins, OIDC claims, storage class, and immutable image tags.

Install or upgrade Umbod:

helm upgrade --install umbod \
  oci://ghcr.io/computerlovetech/charts/umbod \
  --version 0.0.1-beta.8 \
  --namespace umbod \
  --values values.production.yaml \
  --wait --timeout 5m

Validate the shared installation:

kubectl -n umbod get pods,services
helm -n umbod test umbod --logs --timeout 2m

Warning

The chart currently runs a single core replica backed by SQLite. Persistent storage preserves data across Pod replacements, but this remains a development and evaluation architecture rather than a production database architecture.

Uninstall

Remove the local release and kind cluster:

helm uninstall umbod
kind delete cluster --name umbod

For a namespaced installation, remove the release without deleting the cluster:

helm --namespace umbod uninstall umbod