Skip to main content

​
Prerequisites

Before you begin, ensure you have:
  • Docker Desktop running (for Docker Compose or Kind)
  • Git installed
  • Terminal with bash or zsh
You don’t need to install Go, Node.js, or other tools manually - Nix will handle all dependencies automatically!

​
Setup Instructions

1

Install Nix and direnv

Install the Determinate Nix installer and direnv for automatic environment setup:
curl -fsSL https://install.determinate.systems/nix | sh -s -- install
nix profile install nixpkgs#direnv nixpkgs#nix-direnv
Add direnv hook to your shell (choose your shell):
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
source ~/.zshrc
Nix provides reproducible development environments. The Determinate installer makes setup seamless on macOS and Linux.
2

Clone the Repository

Clone the repository and navigate to the directory:
git clone https://github.com/hackz-megalo-cup/microservices-infra
cd microservice-app
Allow direnv to activate the Nix environment:
direnv allow
The first direnv allow may take 5-10 minutes as it downloads and installs all development tools (Go, Node.js, buf, kubectl, tilt, etc.). Subsequent uses are instant.
Once complete, you’ll have access to all project commands:
go version        # Go 1.21+
node --version    # Node.js 20+
buf --version     # Protocol Buffers tooling
tilt version      # Kubernetes development tool
3

Configure Environment Variables

Copy the example environment files:
cp .env.example .env
cp frontend/.env.example frontend/.env
Default values work out of the box for local development. You can customize them later if needed.
The .env file contains configuration for all services:
.env
# PostgreSQL
POSTGRES_USER=devuser
POSTGRES_PASSWORD=devpass

# Services
CALLER_BASE_URL=http://caller:8081
EXTERNAL_API_URL=https://httpbin.org/get
GREETER_DATABASE_URL=postgresql://devuser:devpass@postgres:5432/greeter_db

# Auth
JWT_SECRET=dev-secret

# Frontend
VITE_API_BASE_URL=http://localhost:30081
VITE_USE_MOCK=false
4

Choose Your Development Mode

You have three options for running the platform:Fastest way to get started. No Kubernetes complexity.
docker compose up
Access points:
This mode runs all services but without the observability stack (Prometheus, Grafana, etc.).

​
Option 2: Kubernetes with Tilt (Lightweight)

Local Kubernetes with Kind, without heavy monitoring infrastructure.
# Clone and setup infrastructure repo
git clone https://github.com/hackz-megalo-cup/microservices-infra
cd microservices-infra
direnv allow
bootstrap  # Creates lightweight Kind cluster

# Return to app repo and start Tilt
cd ../microservice-app
tilt up
Access the Tilt UI at http://localhost:10350 to monitor service status.

​
Option 3: Kubernetes with Full Observability (For advanced users)

Complete setup with Prometheus, Grafana, Loki, and Tempo.
# Clone and setup infrastructure repo
git clone https://github.com/hackz-megalo-cup/microservices-infra
cd microservices-infra
direnv allow
full-bootstrap  # Requires 8GB+ RAM

# Return to app repo and start Tilt
cd ../microservice-app
tilt up
The full observability stack requires significant resources (8GB+ RAM recommended). Use bootstrap for a lighter setup.
Access points:
Run Tilt in the background: tilt up > /dev/null 2>&1 &
5

Verify the Installation

Test that services are responding:
# Check Traefik (API gateway)
curl http://localhost:30081

# Test the greeter service via Traefik
curl -X POST http://localhost:30081/greeter.v1.GreeterService/Greet \
  -H "Content-Type: application/json" \
  -d '{"name": "Developer"}'
Expected response:
{
  "message": "Hello Developer from greeter-service!",
  "externalStatus": 200,
  "externalBodyLength": 350
}
If using Tilt, check the health-check resource in the Tilt UI at http://localhost:10350 for service status.

​
Next Steps

Frontend Development

Learn how to run the React frontend in development mode

Architecture Overview

Understand how the microservices communicate

Adding Services

Create new Go or Node.js microservices

Protocol Buffers

Work with proto definitions and code generation

​
Troubleshooting

Ensure you have admin/sudo access. On macOS, you may need to grant Full Disk Access to your terminal in System Preferences > Security & Privacy.Try the official installer as an alternative:
sh <(curl -L https://nixos.org/nix/install) --daemon
Make sure you added the direnv hook to your shell configuration:
# Check if hook is loaded
type direnv

# If not found, add the hook and reload
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc
Check Docker Desktop is running and you have sufficient resources allocated:
docker info
docker compose logs <service-name>
Common issues:
  • Port conflicts (5432, 30081 already in use)
  • Insufficient memory (allocate at least 4GB to Docker)
  • Network issues (firewall blocking containers)
Ensure Kind cluster is running:
kind get clusters
kubectl cluster-info
If the cluster is missing, create it:
kind create cluster --name microservice-app
Check Tilt logs for specific errors:
tilt down
tilt up
Regenerate proto files:
buf generate
If buf is not found, ensure direnv is activated:
direnv allow
which buf  # Should show path in /nix/store

​
Development Commands

Once set up, you have access to these helper commands:
CommandDescription
fmtFormat all code (Go, TypeScript, Nix) and stage changes
lintRun linters across all languages
buf-checkLint Protocol Buffers and check for breaking changes
gen-manifestsRegenerate Kubernetes manifests from nixidy modules
debug-k8sShow pod status and recent events
debug-grpcTest gRPC endpoints with grpcurl
test-smokeRun smoke tests against running services
new-service go <name>Generate new Go service scaffold
new-service custom <name>Generate new Node.js service scaffold
Run these commands from the project root after direnv allow has activated the environment.

Build docs developers (and LLMs) love

Get started for freeTalk to us