How to Set Up a Macro Development Environment: Complete Local Stack Guide

Install Nix and Docker, run nix develop, then just run_local --no-doppler to launch the full stack with Postgres, Redis, Kafka, and more.

Macro is a Rust-based, multi-service workspace that unifies email, chat, docs, tasks, agents, and CRM. According to the macro-inc/macro source code, the recommended Macro development environment setup uses Nix for toolchain management and Just for task orchestration, with all backing services running via Docker Compose.

Prerequisites: Required Tools

Before setting up the Macro development environment, install two core dependencies:

• Nix — Provides the entire development toolchain including just, Cargo, Rust, Bun, Zig, cargo-zigbuild, and sqlx. Install via nix.dev.

• Docker with Compose v2 — Docker Desktop, OrbStack, or Colima. Ensure the Docker daemon is running before proceeding.

Step 1: Clone the Repository

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

The repository structure follows a Cargo workspace pattern with crates/ (Rust libraries), services/ (microservices), packages/ (shared TypeScript), apps/web/ (SolidJS frontend), and infra/ (infrastructure definitions).

Step 2: Enter the Nix Development Shell

nix develop

This command drops you into a shell with all dependencies pre-configured.

If the command fails, enable experimental features temporarily:

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

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

Platform-Specific Nix Shells

For desktop or mobile development, use specialized shells:

Target	Command
Linux desktop (Tauri)	nix develop .#tauri-linux
Android (x86_64 Linux)	nix develop .#tauri-android

Step 3: Start the Full Local Stack

The just run_local command in the justfile orchestrates the entire Macro development environment. For local development without cloud secrets:

just run_local --no-doppler

This performs several operations:

1. Builds all Rust services in the workspace
2. Spins up Docker containers defined in [docker/docker-compose.yml](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml)
3. Launches backing services: Postgres, Redis, LocalStack (S3), OpenSearch, Kafka, and FusionAuth
4. Starts the proxy and SolidJS frontend

Step 4: Verify Stack Health

Before first use, run the pre-flight check:

just doctor-local

This confirms Docker is reachable, required ports are free, and all services are listening on their expected endpoints.

Step 5: Seed Realistic Test Data

The Macro development environment includes a powerful seeding system. Apply a comprehensive scenario:

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

This creates users, teams, channels, projects, documents, tasks, chats, calls, emails, and messages. It also provisions FusionAuth accounts for each persona.

After seeding, the terminal outputs login URLs like:

http://alice.localhost:3000/app/login?email=alice@seed.macro.local

Open multiple URLs in separate browser tabs to simulate multi-user collaboration.

Step 6: Interact with the Application

Open the frontend URL (typically http://localhost:3000/app) in your browser. The SolidJS UI runs client-side while all backend APIs are served by your local services.

Hot-Reloading and Stack Management

While just run_local is attached, use these interactive commands:

• r — Rebuild changed Rust services and reload them
• q — Gracefully stop the stack, removing containers and volumes

Headless Operation for CI

For automation or CI pipelines, use the stack commands directly:

just stack up              # Launch without interactive loop

just stack status --json   # Machine-readable status

just stack update          # Rebuild changed services

just stack down            # Clean shutdown

Running Multiple Isolated Stacks

Test different branches or configurations simultaneously:

just run_local --instance feature-x    # default ports

just run_local --instance feature-y    # separate port range

Each instance gets its own Docker Compose project, volumes, networks, and deterministic port range. Use --port-base <N> to shift the entire range if you encounter conflicts.

Instance configurations are auto-generated in infra/local/generated/.

Enabling Third-Party Integrations

To test with real external services, create a local.env file with actual credentials:

GOOGLE_CLIENT_ID=your_client_id
GITHUB_CLIENT_ID=your_github_id
STRIPE_SECRET_KEY=your_stripe_key

Launch with the custom environment:

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

Only the keys you supply override stub values. All internal secrets default to functional local values.

Alternative: Single Service Development

For rapid iteration on one backend binary without the full stack:

just run_dev

Note: This requires Doppler access because it connects to cloud-hosted resources rather than local Docker containers defined in [docker/docker-compose.yml](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml).

Key Configuration Files Reference

File	Purpose
[docs/RUNNING_LOCALLY.md](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md)	Detailed setup guide and troubleshooting
justfile	All just recipes and task definitions
[docker/docker-compose.yml](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml)	Service orchestration (Postgres, Redis, Kafka, etc.)
crates/macro_db_client/	Central PostgreSQL client with SQLx migrations
services/*	Individual microservice implementations
apps/web/	SolidJS frontend source
[seed/scenarios/team-perms.json](https://github.com/macro-inc/macro/blob/main/seed/scenarios/team-perms.json)	Sample data for realistic testing

Complete Setup Command Reference

# Full setup sequence

git clone https://github.com/macro-inc/macro.git
cd macro
nix develop
just doctor-local           # Verify prerequisites

just run_local --no-doppler # Start stack

just seed-scenario apply --file seed/scenarios/team-perms.json  # Add test data

# Development workflow

# - Edit code in crates/, services/, or apps/web/

# - Press 'r' in terminal to hot-reload Rust services

# - Open browser to printed localhost URL

# - Press 'q' to stop everything

# Cleanup

just stop_local --instance default

# or: just stack down

Summary

• Nix provides reproducible toolchain management for the Macro development environment
• just run_local --no-doppler launches the complete local stack without cloud dependencies
• Docker Compose orchestrates Postgres, Redis, LocalStack, OpenSearch, Kafka, and FusionAuth
• Hot-reload workflow (r key) enables rapid Rust service iteration
• Multi-instance support (--instance) allows parallel testing environments
• Seeding with team-perms.json creates realistic multi-user scenarios instantly

Frequently Asked Questions

What is Nix and why does Macro require it?

Nix is a declarative package manager that ensures every developer uses identical tool versions. The Macro repository includes a flake.nix that pins Rust, Bun, Zig, just, and other dependencies. This eliminates "works on my machine" problems across the multi-service workspace. Run nix develop to enter a shell with everything pre-configured.

Can I develop Macro without Nix?

Technically possible but not recommended. The repository relies on specific versions of Rust nightly, cargo-zigbuild for cross-compilation, and sqlx-cli for database operations. Manual installation is error-prone and unsupported. If you cannot use Nix, study the flake.nix to replicate the environment manually.

How do I debug port conflicts when running multiple stacks?

Use the --port-base flag with just run_local to shift all service ports by a fixed offset. For example, --port-base 100 moves the default frontend from :3000 to :3100. Each --instance also creates isolated Docker networks and volumes, preventing collisions between different development branches.

What is the difference between just run_local and just run_dev?

just run_local launches the full stack with local Docker services and requires --no-doppler for secret-free operation. just run_dev connects to cloud-hosted resources via Doppler and runs a single service for fast iteration. Use run_local for integration testing and run_dev for isolated backend development.

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