Skip to main content
The microservices-app uses Nix and devenv to provide a reproducible development environment with all necessary tools pre-installed.

​
Prerequisites

  • Docker (for running services locally)
  • Git
  • macOS or Linux

​
Installation

1

Install Nix with Determinate Systems installer

The Determinate Systems installer provides a production-ready Nix setup with sensible defaults.
curl -fsSL https://install.determinate.systems/nix | sh -s -- install
2

Install direnv and nix-direnv

These tools automatically activate the development environment when you enter the project directory.
nix profile install nixpkgs#direnv nixpkgs#nix-direnv
3

Configure direnv shell hook

Add the following to your shell configuration file:
eval "$(direnv hook zsh)"
Then reload your shell:
source ~/.zshrc  # or ~/.bashrc for bash
4

Clone the repository

git clone https://github.com/hackz-megalo-cup/microservices-infra
cd microservice-app
5

Activate the development environment

Allow direnv to load the environment:
direnv allow
The first time you run this, devenv will download and install all required tools including Go 1.26, Node.js 24, kubectl, Tilt, buf, and more. This may take several minutes.
6

Copy environment files

Create local environment configuration:
cp .env.example .env
cp frontend/.env.example frontend/.env
The default values work out of the box for both Docker Compose and Tilt/Kubernetes setups.

​
Included Tools

Once the devenv shell is activated, you’ll have access to the following tools:

​
Core Development

ToolVersionPurpose
go1.26Go compiler and toolchain
nodejs24Node.js runtime for frontend and Node.js services
bufLatestProtocol Buffers toolchain
gitLatestVersion control

​
Kubernetes & Cloud Native

ToolVersionPurpose
kindLatestLocal Kubernetes clusters
kubectlLatestKubernetes CLI
helmLatestKubernetes package manager
tiltLatestLocal Kubernetes development environment

​
Debugging & Utilities

ToolVersionPurpose
grpcurlLatestgRPC debugging CLI
protobufLatestProtocol Buffers compiler
watchexecLatestFile watching utility
skopeoLatestContainer image operations

​
Code Quality

ToolVersionPurpose
golangci-lintLatestGo linter (installed on first use)
goimportsLatestGo import formatter (installed on first use)
treefmtLatestMulti-language formatter
Tools like golangci-lint and goimports are automatically installed to .devenv/go-bin/ when you first enter the shell. This ensures they’re built with the same Go version as your project.

​
Custom Commands

devenv provides custom scripts for common tasks:

​
Code Quality

# Format all code (Go, TypeScript, Nix) and stage changes
fmt

# Run all linters (golangci-lint + Biome)
lint

# Check protobuf schemas for lint errors and breaking changes
buf-check

​
Code Generation

# Generate Go and TypeScript code from Protocol Buffers
buf generate

# Generate Kubernetes manifests from nixidy modules
gen-manifests

​
Kubernetes Development

# Build and load microservice images into Kind cluster
load-microservice-images

# Watch nixidy modules and auto-apply changes to k8s
watch-manifests

# Fix empty chartHash in nixidy modules
fix-chart-hash

​
Debugging

# Check Kubernetes pod status and recent events
debug-k8s

# Test gRPC endpoints with grpcurl
debug-grpc

# Run smoke tests against running services
test-smoke

# Verify Nix expressions evaluate correctly
nix-check

​
Service Scaffolding

# Create a new Go microservice
new-service go <name> [port]

# Create a new Node.js microservice
new-service custom <name> [port]

​
Pre-commit Hooks

devenv automatically configures Git pre-commit hooks that run on every commit:
HookDescription
treefmtFormats Nix, Go, and TypeScript files
golangci-lintRuns Go linter on Go files
goimportsOrganizes Go imports
biomeRuns Biome linter on TypeScript/TSX files
go testRuns Go unit tests
If any hook fails, the commit will be blocked. Run fmt and lint to fix issues before retrying.

​
Environment Variables

The development environment uses the following environment variable files:

​
Root .env

Used by Docker Compose and shared services: 
# PostgreSQL
POSTGRES_USER=devuser
POSTGRES_PASSWORD=devpass

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

# caller service
CALLER_DATABASE_URL=postgresql://devuser:devpass@postgres:5432/caller_db

# gateway service
CUSTOM_LANG_BASE_URL=http://custom-lang-service:3000
GATEWAY_DATABASE_URL=postgresql://devuser:devpass@postgres:5432/gateway_db

# custom-lang-service
LANG_DATABASE_URL=postgresql://devuser:devpass@postgres:5432/lang_db

# auth-service
JWT_SECRET=dev-secret
AUTH_DATABASE_URL=postgresql://devuser:devpass@postgres:5432/auth_db

# frontend
VITE_API_BASE_URL=http://localhost:30081
VITE_USE_MOCK=false

​
Frontend .env

Frontend-specific configuration in frontend/.env: 
VITE_API_BASE_URL=http://localhost:30081  # Traefik API gateway URL
VITE_USE_MOCK=false                       # Enable MSW mock mode
All environment variables prefixed with VITE_ are exposed to the frontend application at build time.

​
Troubleshooting

​
Shell activation fails

If direnv allow fails to activate the environment: 
# Check direnv status
direnv status

# Manually reload
direnv reload

​
Tool not found after activation

Some tools are installed lazily on first use. Try running the tool directly: 
# This will trigger installation
golangci-lint --version
goimports -h

​
Pre-commit hooks causing issues

You can bypass hooks temporarily (not recommended for normal development): 
git commit --no-verify -m "message"
Or disable specific hooks in .pre-commit-config.yaml.

​
Next Steps

Docker Compose

Run services with Docker Compose

Kubernetes + Tilt

Set up local Kubernetes development

Frontend Development

Start frontend development

Build docs developers (and LLMs) love

Get started for freeTalk to us