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.6 (which deploys core and frontend images 0.0.1-beta.4) with development authentication:

helm upgrade --install umbod \
  oci://ghcr.io/computerlovetech/charts/umbod \
  --version 0.0.1-beta.6 \
  --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

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.6 \
  --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