Deployment Guides
Docker Desktop Guide
Run the containerised KubeBolt, with Docker Compose or the single image, against Docker Desktop's built-in Kubernetes or a kind cluster.
This page is about running KubeBolt in containers (Docker Compose or the single-container image) against a cluster on your own machine: Docker Desktop’s built-in Kubernetes, or kind. Two other ways to install skip all of it:
- On the host (Homebrew, krew, the single binary): KubeBolt reaches
127.0.0.1:6443like any other tool. - Inside the cluster (the Helm chart):
it uses its own ServiceAccount, and Docker Desktop’s default
hostpathStorageClass covers the chart’s two volumes.
The Problem
Docker Desktop’s Kubernetes publishes its API server at 127.0.0.1:6443. That
address works from your machine, but inside a container 127.0.0.1 is the
container itself, so KubeBolt cannot reach the cluster.
The Solution
deploy/docker-kubeconfig.sh copies your kubeconfig ($KUBECONFIG, or
~/.kube/config) to /tmp/docker-kubeconfig and rewrites every
https://127.0.0.1 and https://localhost server to
https://kubernetes.docker.internal, a name Docker Desktop resolves to the host
from inside containers and that its API server certificate covers. The compose
file mounts that copy, not ~/.kube.
Both the helper and the compose file live in the git repository, so the Compose
path starts with a clone. Compose builds the API and web images from the
checkout, so the first up takes a few minutes:
# 1. Docker Desktop → Settings → Kubernetes → Enable Kubernetes
# 2. Get the repo — deploy/docker-compose.yml and the helper live in it
git clone https://github.com/clm-cloud-solutions/kubebolt.git
cd kubebolt
# 3. Make docker-desktop the current context — KubeBolt opens on it
kubectl config use-context docker-desktop
# 4. Generate the container-compatible kubeconfig
./deploy/docker-kubeconfig.sh
# 5. Start
cd deploy && docker compose up -d
Open http://localhost:3000. The other contexts in the file are in the cluster
switcher, subject to what works inside a container.
The helper is not optional, and not only for Docker Desktop. The compose
file mounts /tmp/docker-kubeconfig, not ~/.kube, so every Compose install
runs the script first. On a remote cluster it rewrites nothing and simply
copies the file.
Keeping the copy current
/tmp/docker-kubeconfig is a snapshot. Run the helper again, then
docker compose restart api, whenever you add or change a context, and after
a reboot clears /tmp.
If you started Compose before ever running the helper, Docker created
/tmp/docker-kubeconfig as an empty directory to satisfy the mount, and the
helper then fails to write it. Remove it and start over:
# from deploy/
docker compose down
rm -rf /tmp/docker-kubeconfig
./docker-kubeconfig.sh
docker compose up -d
Contexts that call a cloud CLI
The helper copies every context, but inside a container only the ones that
authenticate with a certificate or a token work — Docker Desktop, kind, k3d and
minikube all do. The API image Compose builds ships no cloud CLI, so a context
whose user runs aws eks get-token, gke-gcloud-auth-plugin or kubelogin
fails there. The single-container image ships aws-cli only (see the
EKS guide). Run KubeBolt on the host for those
clusters, or connect them with the agent.
The single-container image
It needs the rewritten file too — and therefore the checkout for the helper.
The image runs as a non-root user, so mount the file somewhere readable and
point KUBECONFIG at it rather than mounting under /root. The /data
volume keeps users and settings across container restarts:
./deploy/docker-kubeconfig.sh
docker run -d --name kubebolt -p 3000:3000 \
-v /tmp/docker-kubeconfig:/kubeconfig:ro -e KUBECONFIG=/kubeconfig \
-v kubebolt-data:/data \
ghcr.io/clm-cloud-solutions/kubebolt:latest
API and UI are one process on port 3000. This image carries no time-series store; see Ports.
kind
kind also publishes its API server on 127.0.0.1, but on a random port and with
a certificate that does not cover kubernetes.docker.internal, so the helper’s
rewrite does not help. Write kind’s internal kubeconfig instead, which
addresses the control-plane container by name, and add the kind overlay so the
API container joins kind’s Docker network:
KIND_CLUSTER=kind # the --name you gave `kind create cluster`; kind's default is "kind"
kind get kubeconfig --internal --name "$KIND_CLUSTER" > /tmp/docker-kubeconfig
cd deploy && docker compose -f docker-compose.yml -f docker-compose.kind.yml up -d
The file then holds only that cluster. Do not run docker-kubeconfig.sh
afterwards: it would overwrite it with your full kubeconfig. Pass both -f
files on every later docker compose up, or the API is recreated without the
kind network.
Log in
Authentication is on by default. On first boot KubeBolt seeds an admin user
and prints the generated password once:
docker compose logs api | grep "Generated admin password" # single image: docker logs kubebolt 2>&1 | grep …
Set your own with KUBEBOLT_ADMIN_PASSWORD before the first start — simpler
than reading the log. Export it in the shell that runs docker compose up, or
put it in deploy/.env (start from deploy/.env.example). It only seeds the
first boot; after that, change the password from the Account menu.
Outside Kubernetes there is no Secret to fall back on, so if you lose the password, reset it against the same data volume (the API has to be stopped first — BoltDB is single-writer):
docker compose stop api
docker compose run --rm api --reset-admin-password=NEWPASS
docker compose start api
The run resets the password, prints admin password reset OK and exits. See
Authentication for the Kubernetes
equivalents.
The first admin login opens the Setup Wizard — four optional steps you can skip.
Ports
| Port | Service |
|---|---|
| 3000 | Web UI, the one you open |
| 8080 | Go API, HTTP and WebSocket |
| 9090 | gRPC channel for the agent |
| 8428 | VictoriaMetrics |
Compose is the local option that bundles VictoriaMetrics, with 30 days of
retention (KUBEBOLT_METRICS_RETENTION). The Homebrew, binary and docker run
paths carry no time-series database: live usage from Metrics Server still
shows, but history charts stay empty unless you point
KUBEBOLT_METRICS_STORAGE_URL at a VictoriaMetrics. Either way, what fills
history is the agent.
Metrics Server
Docker Desktop does not ship Metrics Server. Without it, the Overview’s live
usage reads “no data”; resources, events and insights are unaffected. Install
it, then check that kubectl top answers:
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
kubectl top nodes
If kubectl top nodes keeps failing and
kubectl -n kube-system logs deploy/metrics-server shows an x509 error saying
the certificate doesn’t contain any IP SANs, the kubelet’s serving certificate
does not cover the address metrics-server dials. On a local test cluster, let
metrics-server skip that check (kind usually needs the same):
kubectl -n kube-system patch deployment metrics-server --type=json \
-p '[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--kubelet-insecure-tls"}]'
Do I need the agent?
Not to connect: with a kubeconfig KubeBolt talks to the cluster directly. But the agent is what fills history. Without it you get live CPU and memory from Metrics Server, and no history charts, network flows or cost.
The agent runs inside the cluster and dials the API’s gRPC port, which Compose
publishes on the host as 9090. From a cluster on Docker Desktop (kind, k3d and
minikube included) that address is host.docker.internal:9090:
helm install kubebolt-agent \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt-agent \
--namespace kubebolt-system --create-namespace \
--set backendUrl=host.docker.internal:9090
With the kind overlay, the agent can also dial the API by its container
name, deploy-api-1:9090 (<project>-api-1 when the Compose project has
another name). Compose leaves agent authentication off, so no token is needed;
the Setup Wizard’s Agent step and Add cluster print the same command
with the options you pick.
What to expect
Docker Desktop is a documented target, but treat it as a development environment rather than a production one. KubeBolt needs Kubernetes v1.24 or newer for full features, and works with degraded features on v1.20–v1.23 (see Compatibility).