4_path_localnet

make path_up

Or start with local Helm charts (for Helm chart development)

make path_up_local_helm

The startup process will:

  • Validate your configuration files against the schema

  • Create a Kind Kubernetes cluster

  • Deploy PATH, GUARD, and WATCH using Helm

  • Start Tilt for orchestration and hot reloading

First-time startup may take 3-5 minutes as Docker pulls the required images.

Verify the Setup

Once started, you'll see:

🌿 PATH Localnet started successfully.
  🚀 Send relay requests to: http://localhost:3070/v1

🛠️  Development tools:
  🔧 Open container shell: make localnet_exec
  🔍 Launch k9s for debugging: make localnet_k9s

Test with a simple request:

curl http://localhost:3070/healthz

For more example relay requests, see Example Relays.

Access Development Tools

  • Tilt UI: http://localhost:10350 - Monitor services, view logs, trigger rebuilds

  • Grafana: http://localhost:3003 - View metrics and dashboards

  • PATH API: http://localhost:3070 - Send relay requests

Why PATH Localnet?

The PATH Localnet development container exists to:

  • Minimize Host Dependencies: Only Docker is required on your machine — no need to install Tilt, Helm, Kind, kubectl, or other tools locally

  • Ensure Consistency: All developers work with the same tool versions and configurations

  • Enable Full Stack Development: Run PATH (API Gateway), GUARD (Envoy Gateway), and WATCH (Observability) together

  • Support Hot Reloading: Make code changes and see them reflected immediately without rebuilding containers

  • Simplify Onboarding: New developers can get started in minutes with a single command

Architecture

The PATH Localnet runs as a Docker container that internally manages a complete Kubernetes environment:

┌─────────────────────────────────────────────────────────────┐
│                    Host Machine (Your Computer)             │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐    │
│  │           Docker Desktop / Docker Engine            │    │
│  └─────────────────────────────────────────────────────┘    │
│                            │                                │
│  ┌─────────────────────────────────────────────────────┐    │
│  │         path-localnet Container (Docker-in-Docker)  │    │
│  │                                                     │    │
│  │  ┌────────────────────────────────────────────┐     │    │
│  │  │              Kind Kubernetes Cluster       │     │    │
│  │  │                                            │     │    │
│  │  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  │     │    │
│  │  │  │   PATH   │  │  GUARD   │  │  WATCH   │  │     │    │
│  │  │  │   Pod    │  │  (Envoy) │  │ (Grafana)│  │     │    │
│  │  │  └──────────┘  └──────────┘  └──────────┘  │     │    │
│  │  └────────────────────────────────────────────┘     │    │
│  │                                                     │    │
│  │  ┌────────────────────────────────────────────┐     │    │
│  │  │              Tilt (Orchestrator)           │     │    │
│  │  └────────────────────────────────────────────┘     │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                             │
│  Exposed Ports:                                             │
│  • 3070  → PATH API Gateway                                 │
│  • 10350 → Tilt UI                                          │
│  • 3003  → Grafana Dashboard                                │
└─────────────────────────────────────────────────────────────┘

Components

  • PATH: The API Gateway that handles relay requests

  • GUARD: Envoy Gateway providing authentication, routing, and defense

  • WATCH: Observability stack with Grafana, Prometheus, and metrics collection

  • Tilt: Development orchestrator that manages hot reloading and service lifecycle

  • Kind: Kubernetes-in-Docker providing the cluster environment

Make Targets

The PATH Localnet provides several make targets for managing your development environment.

Core Commands

make path_up

Starts the PATH Localnet environment using remote Helm charts from the official repository.

make path_up

This is the recommended way to start for most development tasks. The container will:

  • Pull the latest ghcr.io/buildwithgrove/path-localnet-env image

  • Mount your local PATH repository for hot reloading

  • Use Helm charts from https://buildwithgrove.github.io/helm-charts/

make path_up_local_helm

Starts the PATH Localnet with local Helm charts, useful when developing Helm chart changes.

make path_up_local_helm

You'll be prompted for the path to your local helm-charts repository. The default is ../helm-charts.

make path_down

Stops and removes the PATH Localnet container.

make path_down

This cleanly shuts down all services by stopping the localnet Docker container.

🌿 Grove employees only 🌿

If changes have been made to the localnet Dockerfile at ./local/Dockerfile.dev, you can build and push the path-localnet-env image to the Grove GHCR:

make build_and_push_localnet_image

This will build the image and push it to ghcr.io/buildwithgrove/path-localnet-env.

Debugging Commands

make localnet_k9s

Launches k9s (https://k9scli.io/), a terminal-based Kubernetes UI, inside the container.

make localnet_k9s

k9s provides an interactive way to:

  • Navigate Kubernetes resources

  • View and follow logs

  • Execute into pods

  • Edit resources

  • Monitor resource usage

k9s running inside the PATH localnet Docker container

k9s Quick Commands

  • :pods - List all pods

  • :svc - List all services

  • l - View logs for selected resource

  • d - Describe selected resource

  • s - Shell into selected pod

  • ctrl+a - Show all namespaces

  • ? - Show help menu

make localnet_exec

Opens an interactive shell inside the running PATH Localnet container.

make localnet_exec

Useful for:

  • Running kubectl commands directly

  • Inspecting logs and configurations

  • Debugging networking issues

  • Managing the Kind cluster

Example session:

$ make localnet_exec
root@path-localnet:/app# kubectl get pods
NAME                           READY   STATUS    RESTARTS   AGE
path-5f7b9c4d6f-abc12         1/1     Running   0          5m
envoy-gateway-xyz789          1/1     Running   0          5m
grafana-6d8f9c7b5-def45      1/1     Running   0          5m

root@path-localnet:/app# kubectl logs path-5f7b9c4d6f-abc12

Container Environment

The PATH Localnet image includes all necessary development tools, meaning you can run PATH, GUARD, and WATCH locally without any additional dependencies.

File Mounts

The container mounts your local PATH repository at /app, enabling:

  • Hot reloading of Go code changes

  • Configuration file updates

  • Access to test data and scripts

Configuration Validation

On startup, the container validates your ./local/.config.yaml against the YAML schema in the PATH repo:

https://github.com/buildwithgrove/path/blob/main/config/config.schema.yaml

Development Workflow

Hot Reloading

1

Make changes

Edit your local PATH repository files.

2

Save

Save the file on your host.

3

Tilt detects changes

Tilt watches the mounted filesystem and detects changes.

4

Rebuild

Tilt triggers a rebuild and produces a new binary or image as configured.

5

Deploy

The new binary is deployed to the Kind cluster and the service restarts with your changes.

Viewing Logs

Multiple ways to view logs:

  • Tilt UI (http://localhost:10350)

    • Real-time log streaming

    • Filtered by service

    • Search functionality

  • Inside the container:

make localnet_exec
kubectl logs -f deployment/path

  • Using k9s:

make localnet_k9s
# Navigate to pod and press 'l'
Previous3_example_requestsNexttesting

Was this helpful?