Skip to main content

Getting Started

Development Environment​

Recommended: macOS or Linux for ⍼ Angzarr development.

Dev containers are fully supported and work well on Linux. However, the author has experienced issues with dev containers on Windows with JetBrains IDEs—if you're on Windows, consider using WSL2 or a Linux VM.

Prerequisites​

  • Rust 1.70+
  • Container runtime: Podman or Docker
  • Kind - local Kubernetes clusters
  • Skaffold - Kubernetes development workflow
  • just - command runner
  • Helm - Kubernetes package manager
  • uv - Python package manager (for scripts)
  • mold - fast linker (recommended)
  • sccache - compilation cache (recommended)
  • grpcurl (optional, for debugging)

Container Runtime: Podman or Docker​

⍼ Angzarr works with either Podman or Docker—they're fully compatible.

Podman is recommended because:

  • Daemonless architecture (no background service required)
  • Rootless by default (better security)
  • No licensing concerns for commercial use
# Debian/Ubuntu
sudo apt install podman

# Fedora
sudo dnf install podman

# macOS
brew install podman
podman machine init && podman machine start

# Optional: alias docker to podman
alias docker=podman

Install mold and sccache for significantly faster builds:

# Debian/Ubuntu
sudo apt install mold clang

# Fedora
sudo dnf install mold clang

# Install sccache
cargo install sccache

# Enable sccache (add to ~/.bashrc or ~/.zshrc)
export RUSTC_WRAPPER=sccache

Expected speedups:

  • mold linker: 50-80% faster linking
  • sccache: Near-instant rebuilds on cache hits

Development Options​

The project includes a complete dev container configuration:

# VS Code
# 1. Install "Dev Containers" extension
# 2. Open project folder
# 3. Click "Reopen in Container" when prompted

Dev containers also work with JetBrains IDEs, though the author found them slow and cumbersome on Windows.

The dev container includes:

  • Rust toolchain with rust-analyzer
  • Container runtime (Docker-in-Docker) for Kind
  • kubectl and Helm
  • sccache pre-configured
  • All VS Code extensions pre-installed

Option 2: Local Setup​

# Install just
cargo install just

# Install other tools (see Prerequisites above)

Quick Start​

Clone and Build​

git clone https://github.com/benjaminabbitt/angzarr
cd angzarr

# Build the framework
just build

# Run unit tests
just test

One-Time Setup​

Before first deployment, configure Podman/Skaffold for the local registry:

just skaffold-init

Deploy to Local Kubernetes​

# Full deployment: create cluster, build images, deploy via Skaffold
just deploy

# Watch pods come up
kubectl get pods -n angzarr -w

This creates a Kind cluster with a local registry, builds all images via Skaffold, and deploys the example application.

Development Workflow​

# Watch mode: auto-rebuild and redeploy on file changes
just dev

# Or for faster iteration without file watching:
just deploy  # After making changes

Clean Slate​

# Tear down and rebuild everything from scratch
just nuke-deploy

Port Standards​

Infrastructure Ports​

ServicePortNodePortDescription
Aggregate Coordinator131031310Command handling per domain
Stream gRPC134031340Event streaming
Topology REST9099-Topology visualization API

Business Logic Ports​

Each language gets a port block:

LanguageRangeExample Assignments
Rust50000-50099player: 50035, table: 50045
Go50200-50299player: 50203, table: 50204
Python50300-50399player: 50303, table: 50304

See Port Conventions for the full scheme.

CLI Reference​

All commands use just. Run just with no arguments to see available commands.

Core Commands​

CommandDescription
just buildBuild the framework (includes proto generation)
just checkFast compile check
just testRun unit tests
just fmtFormat code
just lintRun clippy lints
just watchStart bacon (background code checker)

Cluster Management​

CommandDescription
just cluster-createCreate Kind cluster with local registry
just cluster-statusShow cluster and registry status
just cluster-deleteDelete Kind cluster
just cluster-delete-allDelete Kind cluster and registry
just nuke-deployDelete cluster, caches, rebuild from scratch

Infrastructure​

CommandDescription
just infraDeploy local backing services (PostgreSQL, RabbitMQ)
just infra-destroyDestroy local backing services
just skaffold-initOne-time setup for Podman/Skaffold registry

Deployment (Skaffold)​

CommandDescription
just deployFull deployment: cluster + infra + build + deploy
just devWatch mode: auto-rebuild on file changes
just framework-buildBuild framework images (⍼ Angzarr sidecars)
just framework-devWatch and rebuild framework images

Testing​

CommandDescription
just testRun unit tests
just integrationRun integration tests
just acceptanceRun acceptance tests
just test-interfacesRun interface contract tests (SQLite)
just test-interfaces-postgresInterface tests with PostgreSQL (testcontainers)
just test-interfaces-redisInterface tests with Redis (testcontainers)
just test-bus-amqpAMQP bus tests (testcontainers)
just test-bus-kafkaKafka bus tests (testcontainers)

Port Forwarding​

CommandDescription
just port-forward-gatewayGateway port-forward (9084)
just port-forward-grafanaGrafana port-forward (3000)
just port-forward-topologyTopology port-forward (9099)
just port-forward-cleanupKill all angzarr-related port-forwards

Debugging and Observability​

Logging​

⍼ Angzarr uses tracing for structured logging:

# Debug level for angzarr, info for dependencies
ANGZARR_LOG=angzarr=debug just dev

# Trace all SQL queries
ANGZARR_LOG=sqlx=debug,angzarr=info just dev

Inspecting gRPC Services​

# Port forward an aggregate service
kubectl port-forward svc/angzarr-player 1310:1310 -n angzarr &

# List available services
grpcurl -plaintext localhost:1310 list

# Describe a service
grpcurl -plaintext localhost:1310 describe angzarr.AggregateCoordinator

Common Issues​

SymptomCauseFix
"Connection refused"Business logic not runningCheck pod logs, wait for ready
Events not persistingDatabase not readyCheck infra pods
Skaffold build failsRegistry not configuredRun just skaffold-init
Kind cluster issuesStale stateRun just nuke-deploy

Standalone Mode​

For development without Kubernetes. Standalone mode runs angzarr as a single process with in-memory communication.

Quick Start​

# Build with standalone features
cargo build --features standalone

# Start the standalone server
cargo run --features standalone --bin angzarr_standalone

Architecture​

Components​

ComponentStandalone Implementation
StorageSQLite (file-based, zero config)
Event BusChannel bus (in-process, instant delivery)
TransportUnix domain sockets (no network)
ScalingSingle instance

Configuration​

# Environment variables
export ANGZARR_STORAGE_TYPE=sqlite
export ANGZARR_SQLITE_PATH=./data/events.db
export ANGZARR_LOG=angzarr=debug

When to Use​

  • Local development — No Docker/Kubernetes required
  • Unit and integration tests — Fast, deterministic
  • CI pipelines — Minimal dependencies
  • Prototyping — Quick iteration

Comparison with Distributed Mode​

AspectStandaloneDistributed (K8s)
Setupcargo buildKind cluster + Helm
DependenciesNonePostgreSQL, RabbitMQ
PersistenceSQLite filePostgreSQL
Event deliveryInstant (in-process)Network (ms latency)
ScalingSingle instanceHorizontal
Production-readyNoYes

The two modes share the same core code. Only transport, storage, and bus implementations differ.

See OpenTofu for all deployment options.

Configuration Reference​

Storage Backends​

BackendFeature FlagUse Case
SQLitesqliteStandalone dev, testing
PostgreSQLpostgresProduction
RedisredisHigh-throughput
storage:
  type: postgres
  connection_string: "postgres://user:pass@localhost:5432/angzarr"

Messaging Backends​

BackendFeature FlagUse Case
AMQPamqpProduction (RabbitMQ)
KafkakafkaHigh-throughput
ChannelchannelIn-process, standalone
messaging:
  type: amqp
  url: "amqp://guest:guest@localhost:5672"

Next Steps​