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.20+ with the Meshnet CNI plugin installed.
  • A valid kubeconfig with a cluster context.
  • Docker & Docker Compose (for production deployment).
  • Optional: QEMU support for VM-based node types (requires /dev/kvm).

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.0.0 (defaults to latest). 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 6 reference deployments under deploy/examples/ - from a basic hosts-and-switches topology to a full 5G core with Open5GS. Start with 1-test-small and work up.

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.