# How to Install Macro for macro-inc: Complete Local Setup Guide (Nix + Docker)

> Install Macro for macro-inc locally fast. Clone the repo, enter Nix shell, and run just run_local to launch 40+ Rust microservices with Postgres, Redis, Kafka, and OpenSearch.

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

---

**The fastest way to install Macro for macro-inc locally is to clone the repository, enter the Nix development shell, and run `just run_local --no-doppler` to start the full stack including Postgres, Redis, OpenSearch, Kafka, and 40+ Rust micro-services.**

This guide walks you through installing **Macro**—the open-source, Rust-based collaboration platform from **macro-inc/macro**. Whether you're contributing to the codebase, evaluating the platform, or self-hosting, the Nix-based workflow eliminates dependency hell and gets you running in minutes.

---

## Prerequisites for Installing Macro

Before starting, you'll need **Nix** (the package manager) and **Docker** with Compose v2. These tools are non-negotiable for the reproducible development environment that Macro requires.

Install Nix with the official installer:

```bash
curl -L https://nixos.org/nix/install | sh

```

Then install Docker for your operating system. Once both are available, verify:

```bash
nix --version
docker compose version

```

The [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md) file in the repository contains the canonical requirements section and troubleshooting for edge cases.

---

## Step 1: Clone the macro-inc/macro Repository

Clone the full monorepo (~200 MB) and change into the directory:

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

```

This pulls the complete workspace: SolidJS frontend (`apps/web`), 40+ Rust micro-services (`services/*`), shared libraries (`crates/*`, `packages/*`), and infrastructure definitions (`infra/*`).

---

## Step 2: Enter the Nix Development Shell

The Nix shell automatically provisions all build tools—**Cargo**, **Rust**, **Bun**, **sqlx**, **Zig**, **just**, and more—without polluting your system.

```bash
nix develop

```

If you encounter experimental feature errors, enable them explicitly:

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

```

The shell is defined in the repository's `flake.nix` and loads toolchain versions tested against the codebase. No manual installation of Rust or Node.js is required.

---

## Step 3: Choose Your Platform (Optional)

The default shell excludes the heavy Tauri toolchain. For desktop or mobile builds, use a platform-specific shell:

- **Tauri desktop (Linux):** `nix develop .#tauri-linux`
- **Android (Linux):** `nix develop .#tauri-android`

These variants are documented in [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md) under the platform-specific shells section.

---

## Step 4: Start the Local Macro Stack

Run the complete local environment with a single command:

```bash
just run_local --no-doppler

```

The `--no-doppler` flag skips Doppler secrets management (appropriate for external contributors). This boots Docker containers for:

- **Postgres** – primary database
- **Redis** – caching and session store
- **LocalStack** – AWS service emulation
- **OpenSearch** – full-text search
- **Kafka** – event streaming
- **FusionAuth** – authentication service
- **Mailpit** – email capture for testing

After container startup, the command automatically builds and launches all Rust micro-services. The `justfile` at the repository root defines this `run_local` recipe.

---

## Step 5: Verify Your Macro Installation

Run the pre-flight health check to confirm ports are free and tooling is correct:

```bash
just doctor-local

```

This validates Docker connectivity, port availability, and toolchain versions before you encounter runtime errors.

---

## Step 6: Seed Sample Data (Recommended)

Populate a realistic workspace with users, teams, channels, documents, and tasks:

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

```

The `seed-scenario` command is defined in the root `justfile` and references JSON scenario files in `seed/scenarios/`. This step is optional but highly recommended for meaningful local testing.

---

## Step 7: Access the Macro Web Interface

Once `run_local` completes, the terminal prints a URL like:

```

http://localhost:3000/app

```

Open this in your browser. The SolidJS frontend (`apps/web`) connects through the local proxy to your running backend services.

Create a user by registering with any email address. FusionAuth sends a one-time code that appears in Mailpit at `http://localhost:8025`. This passwordless flow creates your user on-demand.

---

## Handy Variations for Macro Development

### Run Multiple Isolated Instances

Test side-by-side deployments with different port ranges:

```bash
just run_local --instance alice --port-base 31000 --no-doppler

```

### Hot Rebuild While Running

Press **`r`** in the attached terminal to rebuild changed services without restarting the full stack. Alternatively, run `just rebuild-service <service_name>`.

### Stop or Destroy Instances

```bash
just stop_local --instance alice      # graceful shutdown

just destroy_local --instance alice   # remove volumes and networks

```

These commands manage per-instance resources in `infra/local/generated/`.

---

## Complete Macro Installation Script

Save this as [`install-macro.sh`](https://github.com/macro-inc/macro/blob/main/install-macro.sh) for automated setup:

```bash
#!/usr/bin/env bash
set -euo pipefail

# Verify prerequisites

command -v nix >/dev/null || { echo "Install Nix first: https://nixos.org/download.html"; exit 1; }
command -v docker >/dev/null || { echo "Install Docker first: https://docs.docker.com/get-docker/"; exit 1; }

# Clone and enter repository

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

# Enter Nix shell and start services

nix develop --command bash -c '
    just run_local --no-doppler &
    sleep 30  # Wait for stack initialization

    
    just seed-scenario apply --file seed/scenarios/team-perms.json
    
    echo "✅ Macro is running. Check the terminal output above for the UI URL."
    wait
'

```

Run with `bash install-macro.sh` after making it executable.

---

## Key Files in the Macro Repository

| Path | Purpose |
|------|---------|
| [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md) | Canonical local development guide |
| `justfile` | Root command definitions (`run_local`, `seed-scenario`, `doctor-local`) |
| [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) | Service orchestration for local stack |
| `apps/web/` | SolidJS frontend and Tauri desktop client |
| `services/*` | 40+ independent Rust micro-services |
| `crates/*` | Shared Rust libraries (db clients, domain models) |
| `packages/*` | Shared TypeScript packages (`collaboration`, `lexical-core`, `loro-mirror`) |

These paths demonstrate the monorepo structure as implemented in **macro-inc/macro**.

---

## Summary

- **Install Nix and Docker**—the only system-level dependencies required.
- **Clone `macro-inc/macro`** and run `nix develop` for a reproducible toolchain.
- **Start the stack** with `just run_local --no-doppler` to launch all services automatically.
- **Verify with `just doctor-local`** and seed data with `just seed-scenario` for realistic testing.
- **Access the UI** at the printed localhost URL and complete passwordless registration via Mailpit.

The Nix-based workflow eliminates version conflicts and ensures every contributor runs identical environments to the core team.

---

## Frequently Asked Questions

### What is Macro from macro-inc?

Macro is a full-stack, Rust-based collaboration platform combining document editing, task management, and real-time team coordination. It uses a monorepo architecture with SolidJS frontend, 40+ Rust micro-services, and shared libraries for TypeScript and Rust.

### Do I need Doppler to install Macro locally?

No. External contributors should use `just run_local --no-doppler`. The Doppler integration is reserved for core team members who need production secrets. The `--no-doppler` flag fully supports local development and evaluation.

### Why does Macro use Nix instead of manual dependency installation?

Nix provides byte-for-byte reproducible build environments. The `nix develop` command loads exact versions of Rust, Cargo, Bun, sqlx, and Zig—preventing "works on my machine" issues and eliminating manual toolchain setup across Linux, macOS, and WSL2.

### How do I install Macro for production self-hosting?

The repository includes Pulumi infrastructure definitions in `infra/` for AWS deployment. For production, review the Pulumi stacks and adapt the Docker Compose patterns from [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) to your orchestration platform (Kubernetes, ECS, etc.).