Skip to main content

Getting started

This page summarizes how to run KubeNDT. For the authoritative, always up-to-date instructions see the project README.

Requirements​

  • Kubernetes 1.25+ (1.30+ recommended) with the Meshnet CNI plugin installed, and a kubelet that allows the IPv4 and IPv6 forwarding sysctls (see Cluster setup).
  • A valid kubeconfig with a cluster context.
  • Docker & Docker Compose (for production deployment).
  • Optional: QEMU support for VM-based node types (requires /dev/kvm).

Any image whose main process keeps running can be a node. Without startup commands a node runs its image's entrypoint with a tty, so a plain alpine or ubuntu stays up as it is; commands replaces the entrypoint and has to stay in the foreground, or the deploy fails and rolls back. The tools the platform needs in the node's network namespace (ip, bridge, tc, iptables) come from a toolbox container when the image lacks them, and a node whose startup installs or starts something can declare a readiness command the deploy waits for. Details in the README.

For local development you also need Go 1.26+ (CGO enabled) and Node.js 24 LTS.

Don't have a cluster yet?

See Cluster setup for how to bootstrap one (Minikube, kind, or kubeadm) and install the required Meshnet CNI.

Run with Docker Compose​

Run the published images (nothing to compile):

curl -O https://raw.githubusercontent.com/emigcm98/kubendt/main/docker-compose.prod.yml
docker compose -f docker-compose.prod.yml up -d

Pin a release with KUBENDT_TAG=1.7.0 (defaults to latest); see the changelog for every published version. Or build from source instead:

git clone https://github.com/emigcm98/kubendt.git
cd kubendt
docker compose up --build

Either way, open http://localhost in your browser.

Authentication​

The dashboard and API require login. The compose files ship a default password admin123 - override it with KUBENDT_ADMIN_PASSWORD before any real use. For scripts and CI, create an API token in the dashboard and send it as Authorization: Bearer <token>. To run without auth on a trusted network, set KUBENDT_AUTH_DISABLED=true. Full reference in the deployment guide.

Run from source (development)​

Backend:

cd backend
go run .
# serves the API on http://localhost:8080

Frontend (in a second terminal):

cd frontend
npm ci
npm start
# serves the dashboard on http://localhost:3000

Your first topology​

  1. Create a namespace in the KubeNDT dashboard.
  2. Import a topology JSON (topology-network-*.json).
  3. Apply a network configuration JSON (network_conf.json).
  4. Open shells into nodes and test connectivity.

KubeNDT ships reference deployments under deploy/examples/, numbered in the order worth trying them - from a basic hosts-and-switches topology to OSPF and RIP routing, dual stack, VyOS and a full 5G core with Open5GS. Start with 1-test-small and work up. The examples table in the README says what each one needs beyond the cluster (KVM and the VyOS image, an external uplink).

Talking to the API​

Every dashboard action is backed by the REST API. Once the backend is running, explore the endpoints interactively in the API Reference - each operation includes a "Try it" panel and ready-to-copy curl / Go / Python / JavaScript snippets.

Something not working?

See the troubleshooting guide in the repository, and Operations for what KubeNDT recovers from on its own and what needs a hand.