Install docs

Get Berth running

Berth ships as a single container (or a single binary). Pick the way that fits you, all three end with the dashboard on http://localhost:8081. No prior Berth knowledge needed.

How it works

Berth is one process: a web UI baked into a small Go binary that talks to the Kubernetes API. It runs in one of two modes:

remotecluster, talks to a cluster using your local ~/.kube/config. Best for trying it on your laptop (the binary and Docker methods).
incluster, runs as a pod and uses its ServiceAccount. This is what the Helm chart deploys.

Viewing is always free, no key needed. A license key only unlocks changes (create/edit/delete). Grab a free Community key any time from your account, see Apply your key.

Prerequisites

A Kubernetes cluster you can reach. Anything works, a cloud cluster, or local kind/minikube/k3d.
kubectl configured for it. Check with kubectl get nodes, if that lists nodes, you're set.
For the Helm method: Helm 3.8+. For Docker: any recent Docker/Podman.
Optional: metrics-server for CPU/memory graphs. Berth degrades gracefully without it.

1 · Run the binary

The fastest way to look at a cluster. One file, no install, uses your kubeconfig.

Download the build for your OS and architecture from the downloads page. Or pull it from the command line (Linux x86-64 shown):

curl -sSLO https://github.com/unishsys/berth/releases/download/v0.4.1/berth-linux-amd64
curl -sSLO https://github.com/unishsys/berth/releases/download/v0.4.1/SHA256SUMS

Verify and make it executable. The checksum step is optional but recommended.

shasum -a 256 -c SHA256SUMS --ignore-missing   # optional integrity check
chmod +x berth-linux-amd64

macOS may quarantine the download, clear it with xattr -d com.apple.quarantine berth-darwin-*.

Run it against your current kubeconfig context, then open the dashboard.

export AUTH_TOKEN="$(openssl rand -hex 32)"
./berth-linux-amd64 remotecluster
# now open http://localhost:8081

Local mode binds to loopback and requires a token of at least 32 characters. Paste the generated AUTH_TOKEN into the dashboard when prompted. The token is kept in this tab’s session storage when available. Closing the tab clears it; blocked storage also clears it on reload.

2 · Run with Docker

Same as the binary, but containerized, mount your kubeconfig read-only and Berth uses it.

Run the signed image with your kubeconfig mounted at the location the nonroot user expects:

export AUTH_TOKEN="$(openssl rand -hex 32)"
docker run --rm -p 127.0.0.1:8081:8081 \
  -e AUTH_TOKEN -e AUTH_MODE=token -e BIND_ADDRESS=0.0.0.0 \
  -v "$HOME/.kube/config:/home/nonroot/.kube/config:ro" \
  ghcr.io/unishsys/berth:0.4.1 remotecluster
# open http://localhost:8081

Cluster reachable from the container? If your kubeconfig points at 127.0.0.1 (common with kind/minikube), add --network host (Linux) or use the host gateway so the container can reach the API server.

Verify the image (optional). Images are cosign-signed with GitHub OIDC, no keys to manage:

cosign verify ghcr.io/unishsys/berth:0.4.1 \
  --certificate-identity-regexp 'https://github.com/unishsys/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

3 · Install with Helm

The production path: deploys Berth inside the cluster with RBAC and a generated auth token. The chart is an OCI artifact on GHCR.

Install the chart into a berth namespace. upgrade --install is idempotent, the same command installs the first time and upgrades after:

helm upgrade --install berth oci://ghcr.io/unishsys/charts/berth \
  --namespace berth --create-namespace \
  --version 0.4.1

Already have a key? Apply it in the same step by adding --set license.key='<YOUR_KEY>' (see Apply your key). --version pins a reproducible install; omit it to take the latest stable.

Read the auth token the chart generated (token auth is the secure default):

kubectl -n berth get secret berth-secrets \
  -o jsonpath='{.data.AUTH_TOKEN}' | base64 -d ; echo

Open it via a port-forward (or set up an Ingress, see below):

kubectl -n berth port-forward svc/berth 8081:8081
# open http://localhost:8081 and paste the token

Apply your license key

Berth is free to view. To make changes, add a license key: a freeCommunity key (up to 10 nodes) or an Enterprise key (node allowance agreed for your deployment). Get yours from your license account, it's verified offline, so it works in air-gapped clusters.

Helm

helm upgrade --install berth oci://ghcr.io/unishsys/charts/berth --reuse-values \
  --namespace berth \
  --set license.key='<YOUR_KEY>'

Binary or Docker

Set it as an environment variable:

LICENSE_KEY='<YOUR_KEY>' ./berth-linux-amd64 remotecluster
# Docker: add  -e LICENSE_KEY='<YOUR_KEY>'  to the docker run command

Logged-in users get copy-paste commands with the key already filled in on the in-app guide.

Verify it works

Open the dashboard, the license banner should show your tier and node cap, and Create/Edit actions are enabled once a key is applied. From the command line:

curl -s http://localhost:8081/api/v1/license \
  -H "Authorization: Bearer <AUTH_TOKEN>"
# token only needed when AUTH_MODE=token (the Helm default)

Expose it on a hostname (optional)

For a Helm install, turn on the Ingress and TLS instead of port-forwarding:

helm upgrade --install berth oci://ghcr.io/unishsys/charts/berth --reuse-values \
  --namespace berth \
  --set ingress.enabled=true \
  --set ingress.className=nginx \
  --set ingress.host=berth.your-domain.com \
  --set ingress.tls.enabled=true \
  --set ingress.tls.secretName=berth-tls

Berth has cluster-wide access, treat dashboard access as cluster access. Never run AUTH_MODE=none on a shared or exposed cluster, and always serve it over HTTPS.

Troubleshooting

The chart uses one replica, Recreate upgrades and persistent local RWO storage. Confirm your cluster has a suitable storage class. Review older Helm overrides before upgrading; shared RWX storage and multiple replicas are unsupported.

"Binary exits immediately." It needs a mode: run remotecluster (laptop) or incluster (pod).
CPU/memory graphs are blank. Your cluster has no metrics-server. Everything else still works.
Gateways / certificates show "not installed." Those CRDs (Gateway API, cert-manager) aren't present, expected, Berth degrades gracefully.
401 from the API. AUTH_MODE=token is on but no token was sent. Read it from the berth-secrets Secret (Helm step 2).
Docker can't reach the cluster. Your kubeconfig points at 127.0.0.1; add --network host or use the host gateway.

Need more than the Community node cap? See Enterprise. Prefer to grab a build first? Download Berth.