Skip to main content

​
Overview

The microservices-app supports Kubernetes deployment using Kind (Kubernetes in Docker) for local development. Tilt orchestrates the build, deployment, and hot-reload workflow.

​
Prerequisites

  • Docker running
  • Nix with direnv (installed via direnv allow)
  • microservices-infra repository for cluster setup

​
Cluster Setup

The Kind cluster is bootstrapped from the separate microservices-infra repository, which includes:
  • Traefik v3 reverse proxy
  • Observability stack (Prometheus, Grafana, Loki, Tempo)
  • Cilium CNI with Hubble for network visibility
  • ArgoCD for GitOps (optional)

​
Full Bootstrap (Heavy)

Includes the complete observability stack. Recommended if you have sufficient resources (8GB+ RAM): 
git clone https://github.com/hackz-megalo-cup/microservices-infra
cd microservices-infra
direnv allow
full-bootstrap
This creates a Kind cluster named microservice-app with:
  • Control plane + multiple worker nodes
  • Full observability stack (Prometheus, Grafana, Loki, Tempo)
  • Cilium with Hubble UI
  • ArgoCD

​
Light Bootstrap

Minimal cluster without Istio, ArgoCD, and fewer worker nodes: 
cd microservices-infra
bootstrap

​
Starting Tilt

Once the cluster is running, deploy the application services: 
cd microservice-app
tilt up
Background mode: 
tilt up > /dev/null 2>&1 &

​
Tilt Dashboard

Access the Tilt web UI at http://localhost:10350 to monitor:
  • Service build status
  • Pod logs
  • Resource health
  • Hot-reload triggers

​
Accessing Services

URLService
http://localhost:10350Tilt Dashboard
http://localhost:30081Traefik (API Gateway)
http://localhost:30300Grafana (admin/admin)
http://localhost:30090Prometheus
http://localhost:31235Hubble UI
http://localhost:5173Frontend
http://localhost:8080Greeter service
http://localhost:8081Caller service
http://localhost:8082Gateway service
http://localhost:8090Auth service
http://localhost:3000Custom-lang service

​
Tilt Configuration

The Tiltfile orchestrates:

​
1. Cluster Bootstrap

local_resource(
    'cluster-up',
    cmd='kind create cluster --name microservice-app 2>/dev/null || true',
    trigger_mode=TRIGGER_MODE_AUTO,
    labels=['bootstrap'],
)
Skip cluster creation: Set TILT_SKIP_CLUSTER_UP=true if the cluster already exists.

​
2. Manifest Generation

local_resource(
    'gen-manifests',
    cmd='bash scripts/gen-manifests.sh',
    deps=['deploy/nixidy/env/local.nix', ...],
    resource_deps=cluster_bootstrap_deps,
)
Generates Kubernetes manifests from Nixidy modules (see Nixidy).

​
3. Protocol Buffer Generation

local_resource(
    'buf-generate',
    cmd='buf generate',
    deps=['proto/', 'buf.yaml', 'buf.gen.yaml'],
)

​
4. Go Service Builds

Two build modes: Nix mode (USE_NIX=true): 
custom_build(
    'greeter',
    'nix build .#greeter-image && kind load docker-image greeter:latest --name microservice-app',
    deps=compile_deps,
    skips_local_docker=True,
)
Standard mode (default): 
local_resource(
    'greeter-compile',
    'CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o greeter/build/greeter ./cmd/greeter',
    deps=compile_deps,
)
docker_build_with_restart(
    'greeter',
    'services/greeter',
    entrypoint='/greeter',
    live_update=[sync('services/greeter/build/greeter', '/greeter')],
)

​
5. Node.js Services

docker_build(
    'auth-service',
    context='.',
    dockerfile='deploy/docker/auth-service/Dockerfile',
)

​
6. Resource Dependencies

k8s_resource('greeter-service',
    port_forwards=8080,
    resource_deps=['cluster-up', 'gen-manifests', 'buf-generate', 'greeter-compile']
)
Ensures services wait for:
  • Cluster creation
  • Manifest generation
  • Code generation
  • Binary compilation

​
Health Checks

Run the built-in health check: 
tilt trigger health-check
This verifies:
  • Cluster connectivity
  • Pod status
  • Service endpoints
  • HTTP health checks for greeter, gateway, frontend, and Traefik

​
Debugging

See the debugging guide for common issues and debugging commands.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us