Development Setup

Nantian Gateway’s control plane is written in Go, the data plane in Rust, and the admin console in Next.js. This page walks you through setting up a local development environment from scratch, covering build, run, and debug workflows.

Prerequisites

Required Tools

Tool	Version	Purpose
Go	≥ 1.26	Control plane compilation
Rust	≥ 1.85	Data plane compilation
Docker	≥ 24.0	Local cluster and containerized execution
kubectl	≥ 1.28	Kubernetes cluster operations
Helm	≥ 3.12	Chart packaging and deployment
protoc	≥ 3.21	Protobuf compilation
Node.js	≥ 18	Admin console and documentation site

Recommended Tools

Tool	Purpose
Kind	Local Kubernetes cluster
just	Command runner (useful for CI and task automation)
golangci-lint	Go code linting
cargo-watch	Rust hot-reload development

Quick Environment Verification

# Verify Go
go version
# Expected: go version go1.26.x ...

# Verify Rust
rustc --version
# Expected: rustc 1.88.x ...

# Verify Docker
docker version

# Verify kubectl
kubectl version --client

# Verify Helm
helm version

# Verify protoc
protoc --version

# Verify Node.js
node --version

Clone the Repository

# Fork the main repo, then clone your fork
git clone https://github.com/<your-username>/gateway.git
cd gateway

# Add the main repo as upstream
git remote add upstream https://github.com/nantian-gw/gateway.git

Set Up a Local Kubernetes Cluster

For development, we recommend using Kind to create a local cluster:

# Create a Kind cluster
kind create cluster --name nantian-dev

# Verify cluster status
kubectl cluster-info
kubectl get nodes

Install Gateway API CRDs

# Install Gateway API v1.5.1 CRDs
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml

Build and Run the Control Plane

The control plane is written in Go, with its entry point at gateway/cmd/manager/main.go.

# Enter the control plane directory
cd gateway

# Install dependencies
go mod download

# Build the control plane
go build -o bin/manager ./cmd/manager

# Run the control plane locally (install Nantian Gateway CRDs first)
kubectl apply -f deploy/crds/
./bin/manager \
  --metrics-bind-address=:8080 \
  --health-probe-bind-address=:8081 \
  --xds-bind-address=:9090 \
  --leader-elect=false

Control Plane CLI Flags

Flag	Default	Description
--metrics-bind-address	:8080	Prometheus metrics port
--health-probe-bind-address	:8081	Health check and admin API port
--xds-bind-address	:9090	gRPC xDS server port
--leader-elect	true	Enable leader election
--leader-elect-namespace	Current namespace	Namespace for leader election
--gateway-class-name	nantian-gw	GatewayClass name to claim

Local Development Tip

When developing locally, set --leader-elect=false to skip leader election so you can run a single control plane instance directly. In production, keep the default true.

Build and Run the Data Plane

The data plane is written in Rust, located in the dataplane/ directory.

# Enter the data plane directory
cd dataplane

# Build the data plane (debug mode)
cargo build

# Build the data plane (release mode, optimized)
cargo build --release

# Run the data plane
cargo run -- \
  --node-id dataplane-dev-0 \
  --controlplane-addr http://localhost:9090 \
  --cluster kind \
  --admin-bind-address 0.0.0.0:8082 \
  --metrics-bind-address 0.0.0.0:9091

Data Plane CLI Flags

Flag	Default	Description
--node-id	Auto-generated	Node identifier
--controlplane-addr	http://localhost:9090	Control plane gRPC address
--cluster	kind	Cluster name
--admin-bind-address	0.0.0.0:8082	Admin API address
--metrics-bind-address	0.0.0.0:9091	Prometheus metrics port

Compile Protobuf

After modifying .proto files in the proto/ directory, regenerate the Go and Rust code:

# Generate Go code
cd proto
buf generate

# Generate Rust code (from the dataplane directory)
cd ../dataplane
# Code generation is integrated into the dataplane's build.rs
cargo build

Run the Admin Console

The admin console is a Next.js web application:

cd dashboard

# Install dependencies
npm install

# Run in development mode
npm run dev

# Open http://localhost:3000 in your browser

Run the Documentation Site

The documentation site uses Astro + Starlight:

cd website

# Install dependencies
npm install

# Run in development mode
npm run dev

# Open http://localhost:4321 in your browser

One-Click Startup with Docker Compose

The project provides a docker-compose.yml for quickly launching a complete development environment:

docker compose up -d

This starts:

• A control plane instance
• A data plane instance
• The admin console

Debugging Tips

Go Control Plane Debugging

Use Delve to debug Go code:

# Install Delve
go install github.com/go-delve/delve/cmd/dlv@latest

# Run the control plane in debug mode
dlv debug ./cmd/manager -- \
  --leader-elect=false \
  --xds-bind-address=:9090

VS Code users can install the Go extension and configure debug targets in .vscode/launch.json.

Rust Data Plane Debugging

The Rust data plane supports the RUST_LOG environment variable to control log levels:

# Enable verbose logging
RUST_LOG=debug cargo run -- --node-id dataplane-dev-0

# View logs for a specific module only
RUST_LOG=nantian_dataplane::proxy=trace cargo run -- --node-id dataplane-dev-0

Common log levels: error, warn, info, debug, trace.

Inspecting xDS Communication

During development, you can inspect the xDS communication between the control plane and data plane to verify that configuration is being transmitted correctly:

# View xDS client status from the control plane Admin API
curl http://localhost:8081/api/v1/clients | jq

# View xDS connection status from the data plane Admin API
curl http://localhost:8082/api/v1/xds/status | jq

Next Steps

• See Testing Guide to learn how to run tests
• See Architecture Overview to understand the system design
• See Contributing Overview to understand the contribution workflow