Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mikronita/mikrom/llms.txt

Use this file to discover all available pages before exploring further.

Mikrom’s local development environment is orchestrated through a Makefile that wraps Docker Compose, cargo watch, and a tmux session manager. Whether you want the full observability stack or just a minimal Postgres and NATS pair, the commands below get you to a working environment quickly. Before starting, make sure all prerequisites are installed.

​
Prerequisites

You need the following tools on your PATH before running any make target:
ToolPurpose
Rust stable toolchainCompiling all workspace crates
Docker and Docker ComposeRunning Postgres, NATS, BuildKit, and observability
Node.js and pnpmBuilding and running mikrom-app
Dagger CLIRequired for all make ci-* targets
protocGenerating Rust code from .proto files
The Makefile automatically looks for protoc at /tmp/opencode/protoc/bin/protoc and falls back to whatever is on your system PATH. You do not need to set PROTOC manually — the PROTOC_ENV variable is injected for every build that needs it.
The fastest path to a running development environment uses make up-full to start all infrastructure and make dev to open a tmux session with every service watching for file changes.
1

Start the full infrastructure stack

Launch Postgres, NATS, BuildKit, and the Grafana/Prometheus/Loki/Tempo observability bundle in the background:
make up-full
This runs Docker Compose with both the buildkit and observability profiles active. All containers start detached and health-checked before the command returns.
2

Open the tmux development session

Attach to (or create) the mikrom tmux session. Each service gets its own named window running cargo watch:
make dev
The session opens four windows: api, scheduler, builder, and app. If the session already exists, make dev reattaches instead of creating a duplicate.
3

Develop and iterate

Make changes to any Rust service or to mikrom-app. cargo watch rebuilds on save. The SvelteKit dev server at port 3001 also hot-reloads automatically.
4

Stop the session when done

Kill the tmux windows without touching the Docker containers:
make dev-stop
5

Tear down infrastructure

Stop and remove all Docker Compose containers:
make down-full
This calls dev-stop first, then shuts down the Compose stack.

​
Infrastructure Setup Options

Includes Postgres, NATS, BuildKit, and the full LGTM observability suite (Grafana on port 3000, Prometheus on 9090, Loki on 3100, Tempo on 3200, and OTLP endpoints on 4317/4318):
make up-full      # start everything (detached)
make down-full    # stop everything
Useful when you are working on metrics, traces, or log aggregation in addition to core service functionality.

​
Optional Infrastructure Components

You can start BuildKit and the observability stack independently if you need only one of them: 
# BuildKit — for local OCI image builds
make up-buildkit
make logs-buildkit

# Grafana / Prometheus / Loki / Tempo
make up-observability
make logs-observability
Both are Docker Compose profiles (buildkit and observability) so they share the same network bridge as the core stack.

​
Running Individual Services

Instead of the tmux session, you can start individual services in separate terminals. Each command uses cargo watch so the binary restarts on source changes: 
make run-api        # mikrom-api on port 5001
make run-scheduler  # mikrom-scheduler
make run-builder    # mikrom-builder
make run-agent      # mikrom-agent (also sets up Ceph lib symlinks)
make run-router     # mikrom-router (Pingora)
make run-app        # mikrom-app SvelteKit dev server on port 3001
To install the mikrom CLI binary into ~/.cargo/bin so it is available on your PATH: 
make install-cli

​
Environment Files

Every service reads its configuration from a .env file in its own directory. Copy the provided example and fill in the required secrets before running: 
cp mikrom-api/.env.example mikrom-api/.env
cp mikrom-scheduler/.env.example mikrom-scheduler/.env
cp mikrom-builder/.env.example mikrom-builder/.env
cp mikrom-agent/.env.example mikrom-agent/.env
cp mikrom-router/.env.example mikrom-router/.env
cp mikrom-app/.env.example mikrom-app/.env
At minimum, mikrom-api requires DATABASE_URL, NATS_URL, JWT_SECRET, and MASTER_KEY. See configuration/api for the full variable reference.

​
Protobuf Code Generation

mikrom-proto contains shared .proto definitions that are compiled into Rust during the normal Cargo build. No manual protoc invocation is needed — the Makefile passes PROTOC="<path>" automatically to every build target that depends on generated code.
If protoc is not on your system PATH and you are not using the bundled binary at /tmp/opencode/protoc/bin/protoc, install it via your system package manager (apt install -y protobuf-compiler on Debian/Ubuntu) or download a release binary and add it to your PATH.

​
Ceph Libraries (Agent with RBD Support)

The mikrom-agent crate optionally links against librados and librbd for Ceph RBD block storage. These libraries are only required when building or running agent RBD integration tests. To set up the symlinks in target/ceph-libs/: 
make ceph-libs
This creates target/ceph-libs/librados.so and target/ceph-libs/librbd.so pointing at the system-installed Ceph client libraries. The run-agent and Ceph-related build targets set LIBRARY_PATH and RUSTFLAGS automatically to pick up these symlinks.
If the host Ceph libraries (/usr/lib/x86_64-linux-gnu/librados.so.2 and librbd.so.1) are absent, make ceph-libs will silently skip the symlinks and Ceph-dependent builds will fail at link time. Install librbd-dev and librados-dev from your package manager first.

Build docs developers (and LLMs) love

Get started for freeTalk to us