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

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:

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

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

nix --version
docker compose version

The 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:

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.

nix develop

If you encounter experimental feature errors, enable them explicitly:

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 under the platform-specific shells section.

---

Step 4: Start the Local Macro Stack

Run the complete local environment with a single command:

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:

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:

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:

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

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 for automated setup:

#!/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	Canonical local development guide
justfile	Root command definitions (run_local, seed-scenario, doctor-local)
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 to your orchestration platform (Kubernetes, ECS, etc.).

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