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

> Easily set up a Macro development environment locally. Install Nix and Docker, run nix develop, then just run_local to launch the full stack with Postgres, Redis, Kafka, and more.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: getting-started
- Published: 2026-08-14

---

**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](https://github.com/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](https://nix.dev/install-nix).

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

## Step 1: Clone the Repository

```bash
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

```bash
nix develop

```

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

If the command fails, enable experimental features temporarily:

```bash
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`](https://github.com/macro-inc/macro/blob/main/justfile) orchestrates the entire Macro development environment. For local development without cloud secrets:

```bash
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)](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:

```bash
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:

```bash
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:

```bash
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:

```bash
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/`](https://github.com/macro-inc/macro/tree/main/infra/local/generated).

## Enabling Third-Party Integrations

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

```bash
GOOGLE_CLIENT_ID=your_client_id
GITHUB_CLIENT_ID=your_github_id
STRIPE_SECRET_KEY=your_stripe_key

```

Launch with the custom environment:

```bash
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:

```bash
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)](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)](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md) | Detailed setup guide and troubleshooting |
| [`justfile`](https://github.com/macro-inc/macro/blob/main/justfile) | All `just` recipes and task definitions |
| [[`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/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/`](https://github.com/macro-inc/macro/tree/main/crates/macro_db_client) | Central PostgreSQL client with SQLx migrations |
| [`services/*`](https://github.com/macro-inc/macro/tree/main/services) | Individual microservice implementations |
| [`apps/web/`](https://github.com/macro-inc/macro/tree/main/apps/web) | SolidJS frontend source |
| [[`seed/scenarios/team-perms.json`](https://github.com/macro-inc/macro/blob/main/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

```bash

# 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`](https://github.com/macro-inc/macro/blob/main/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.