Docker Desktop Guide — KubeBolt Docs

This page is about running KubeBolt in containers against Docker Desktop’s built-in Kubernetes. If you install with Homebrew or krew, KubeBolt runs on the host, reaches 127.0.0.1:6443 like any other tool, and none of this applies.

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 localhost is the container itself, so KubeBolt cannot reach the cluster.

The Solution

The helper script copies your kubeconfig to /tmp/docker-kubeconfig and rewrites 127.0.0.1 and localhost to kubernetes.docker.internal, which Docker Desktop resolves to the host:

Both the helper and the compose file are files in the git repository, so the Compose path starts with a clone:

# 1. Enable Kubernetes in Docker Desktop → Settings → Kubernetes → Enable
# 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. Switch context
kubectl config use-context docker-desktop

# 4. Generate the container-compatible kubeconfig
./deploy/docker-kubeconfig.sh

# 5. Start
cd deploy && docker compose up -d

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.

The same applies to the single-container image, which also needs the rewritten file — and therefore the checkout for the helper too. The image runs as a non-root user, so mount the file somewhere readable and point KUBECONFIG at it rather than mounting under /root:

./deploy/docker-kubeconfig.sh
docker run -p 3000:3000 \
  -v /tmp/docker-kubeconfig:/kubeconfig:ro -e KUBECONFIG=/kubeconfig \
  ghcr.io/clm-cloud-solutions/kubebolt:latest

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"

Set your own with KUBEBOLT_ADMIN_PASSWORD before the first start — simpler than reading the log. 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

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, so it is the one that keeps 30 days of history. The Homebrew 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.

Metrics Server

Docker Desktop does not ship Metrics Server. It is recommended, not required: without it the live commitment bars on Overview read “no data”, and historical CPU and memory still work through the agent. Install it with:

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

The --kubelet-insecure-tls patch you may have seen elsewhere is a kind and k3d workaround, not a Docker Desktop one.

Do I need the agent?

No. With a kubeconfig KubeBolt talks to the cluster directly. The agent exists for clusters whose API server you cannot reach, which is not the case on your own machine.

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).