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 --config configs/controlplane/config.yaml

The manager binary takes a single flag, --config (path to the YAML config file). All runtime behavior — listen addresses, leader election, and the claimed GatewayClass — is set in that file, not through CLI flags.

Key Control Plane Config Fields

Config field	Default	Description
`grpcAddr`	`:18080`	gRPC xDS server address
`adminAddr`	`:18081`	Admin API / HTTP address
`metricsAddr`	`:18082`	Prometheus metrics address
`healthProbeAddr`	`:18083`	Health and readiness probe address

See the Control Plane Configuration reference for the full schema, including leader election and the GatewayClass name.

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 -p ntgw-app -- --config configs/dataplane/config.yaml

The ntgw-app binary also takes a single --config flag. The node identifier, control plane address, and admin/proxy listen addresses all come from the config file. The node ID can additionally be injected via the NANTIAN_GW_NODE_ID environment variable, which the Helm chart sets from the Pod name.

Key Data Plane Config Fields

Config field	Default	Description
`nodeId`	`dp-local`	Node identifier
`xds.serverAddress`	`http://127.0.0.1:18080`	Control plane gRPC address
`runtime.adminAddress`	`0.0.0.0:19080`	Admin API and metrics address
`runtime.listenAddress`	`0.0.0.0:8080`	HTTP proxy listen address

See the Data Plane Configuration reference for the full schema.

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 -- --config configs/controlplane/config.yaml

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 -p ntgw-app -- --config configs/dataplane/config.yaml

# View logs for a specific module only
RUST_LOG=ntgw_http=trace cargo run -p ntgw-app -- --config configs/dataplane/config.yaml

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 connected data plane nodes from the control plane Admin API
curl http://localhost:18081/v1/nodes | jq

# View node state (including xDS stream status) from the data plane Admin API
curl http://localhost:19080/v1/node | 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