How to Set Up the Macro Development Environment: A Complete Guide

Install Nix and Docker, clone the macro-inc/macro repository, run nix develop, then execute just run_local --no-doppler to orchestrate Postgres, Redis, Kafka, and FusionAuth locally.

Macro is a Rust-based, multi-service workspace that combines email, chat, documents, tasks, and CRM into a bidirectional-graph-driven system. Setting up the Macro development environment requires orchestrating a complex local stack including OpenSearch, LocalStack (S3), and FusionAuth alongside the Cargo workspace. This guide provides the exact commands and file paths from the official repository to get you running locally.

Prerequisites

Before cloning the repository, install the foundational tooling that manages the entire toolchain.

• Nix – The package manager provides just, Cargo, Rust, Bun, Zig, and cargo-zigbuild through a declarative shell. Install via nix.dev.
• Docker with Compose v2 – Required for the Postgres, Redis, OpenSearch, Kafka, and FusionAuth containers. Docker Desktop, OrbStack, or Colima are all compatible.

Ensure the Docker daemon is running before proceeding.

Initial Setup

Clone the Repository and Enter the Nix Shell

Clone the repository and enter the reproducible development environment:

git clone https://github.com/macro-inc/macro.git
cd macro
nix develop

If nix develop fails, enable experimental features for that session:

nix develop --extra-experimental-features nix-command --extra-experimental-features flakes

To make these features permanent, add experimental-features = nix-command flakes to ~/.config/nix/nix.conf.

Platform-Specific Tauri Setup (Optional)

For desktop or mobile development, load the platform-specific Nix shell:

# Linux desktop

nix develop .#tauri-linux

# Android on x86_64 Linux

nix develop .#tauri-android

Start the Local Stack

Launch the full development stack without external secrets:

just run_local --no-doppler

The justfile recipe performs the following actions:

1. Builds all Rust services in the services/ directory.
2. Spins up Docker containers defined in docker/docker-compose.yml for Postgres, Redis, LocalStack, OpenSearch, Kafka, and FusionAuth.
3. Launches the proxy and SolidJS frontend located in apps/web/.
4. Attaches an interactive session for hot-reloading.

Verify and Seed Data

Health Checks

Before interacting with the UI, confirm the stack is healthy:

just doctor-local

The doctor-local command verifies Docker connectivity, port availability, and service responsiveness.

Seeding Realistic Test Data

Populate the database with users, teams, channels, and documents:

just seed-scenario apply --file seed/scenarios/team-perms.json

This creates FusionAuth accounts for test personas and prints login URLs such as http://alice.localhost:3000/app/login?email=alice@seed.macro.local. Open these URLs in separate browser tabs to simulate multi-user collaboration.

Development Workflows

Hot-Reloading Changes

While just run_local is attached, use the interactive controls:

• Press r – Rebuild any changed Rust services and reload them.
• Press q – Gracefully stop the stack, removing containers and volumes.

Running Multiple Isolated Instances

Test different branches or features simultaneously using separate Docker Compose projects:

# Default instance

just run_local --instance agent-a

# Separate instance with isolated volumes and networks

just run_local --instance agent-b

If you encounter port conflicts, shift the entire port range:

just run_local --port-base 41000

Headless Operation (CI/Automation)

For automated testing or scripts, use the stack commands without the interactive loop:

just stack up           # Launch services

just stack status --json   # Machine-readable health status

just stack update       # Rebuild changed services (equivalent to pressing 'r')

just stack down         # Clean shutdown

Enabling Real Third-Party Integrations

To test with live APIs (Google OAuth, GitHub, Stripe), create a local.env file with real credentials:

# local.env

GOOGLE_CLIENT_ID=your_real_id
GITHUB_CLIENT_ID=your_real_id
STRIPE_SECRET_KEY=your_real_key

Launch the stack with your overrides:

just run_local --no-doppler --env-file ./local.env

Only the keys you supply override the stub values; internal secrets remain configured for local defaults.

Key Files in the Repository

Understanding these paths accelerates debugging and customization:

• README.md – High-level architecture overview and contributor entry point.
• docs/RUNNING_LOCALLY.md – Detailed troubleshooting and advanced configuration.
• justfile – Contains all orchestration recipes including run_local, seed-scenario, and doctor-local.
• docker/docker-compose.yml – Defines the Postgres, Redis, OpenSearch, Kafka, and FusionAuth services.
• crates/macro_db_client/ – Central PostgreSQL client with SQLx queries and migrations.
• services/ – Individual microservices (e.g., document_storage_service, email_service).
• apps/web/ – SolidJS frontend and Tauri desktop entry point.
• infra/local/generated/ – Auto-generated network configs and port mappings for each named instance.

Summary

• Install Nix and Docker as the foundation for the toolchain.
• Enter the reproducible shell with nix develop to receive just, Rust, and Bun.
• Launch the stack via just run_local --no-doppler to orchestrate all backend services.
• Verify health with just doctor-local and seed data using just seed-scenario.
• Use interactive hotkeys (r to rebuild, q to quit) during active development.
• Isolate instances with --instance <name> or --port-base <N> for parallel testing.

Frequently Asked Questions

Do I need Doppler to run Macro locally?

No. Use the --no-doppler flag with just run_local to run entirely with local defaults. Doppler is only required for just run_dev, which connects to cloud-hosted resources rather than the Docker Compose stack.

Can I run a single service without the full stack?

Yes. If you have Doppler access, use just run_dev to run a specific backend binary against shared development resources. This skips the Docker orchestration and is faster for iterating on a single crate in services/.

Why does the build require Nix instead of just Rust?

Nix provides exact versions of cargo-zigbuild, sqlx, Bun, Zig, and just in a reproducible shell that matches the CI environment. This eliminates "works on my machine" issues across the crates/ and services/ workspace boundaries.

How do I debug port conflicts when running multiple instances?

Macro automatically assigns deterministic port ranges per instance. If the default ports (starting at 3000/5432/etc.) are occupied, launch with just run_local --port-base 41000 to shift the entire stack to 41000-range ports, or use --instance <name> to create completely isolated Docker networks and volumes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}