How to Run the Macro Project Locally After Cloning macro-inc/macro

To run the Macro project locally after cloning, enter the Nix development shell with nix develop, then execute just run_local --no-doppler to orchestrate the full Docker-based stack including Postgres, Redis, Rust microservices, and the SolidJS frontend.

Macro is a Rust-based microservice workspace that ships a full-stack SaaS product. When you run the Macro project locally after cloning the macro-inc/macro repository, you spin up a complete development environment that mirrors production using Docker containers for all infrastructure dependencies. The repository provides a Nix-based development shell and Just-based task runner to automate the complex orchestration of databases, message queues, and backend services.

Architecture Overview for Local Development

Before executing commands, understand the stack components defined in the source code:

• Nix Development Shell (nix/tauri-dev-shells.nix): Supplies reproducible build tools including just, Cargo, Bun, sqlx, and Zig without polluting your host system.
• Justfile Orchestration (justfile): Defines tasks like run_local, seed-scenario, and doctor-local to manage Docker Compose, migrations, and builds.
• Docker Compose Stack (docker/docker-compose.yml and docker/docker-compose-databases.yml): Declares infrastructure containers for Postgres, Redis, LocalStack, OpenSearch, Kafka, and FusionAuth.
• Rust Microservices (crates/*/src/...): Individual services compiled via cargo zigbuild and hot-reloaded during development.
• Frontend Client (apps/web/): SolidJS application served by the local proxy with Vite hot-reload configuration.

Step-by-Step Local Setup Guide

Clone the Repository and Enter the Nix Shell

First, clone the repository and enter the reproducible development environment:

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

For platform-specific dependencies like Tauri desktop builds, use the specialized shell defined in nix/tauri-dev-shells.nix:

nix develop .#tauri-linux

Verify Your Environment (Optional)

Run the pre-flight check to validate Docker availability, required ports, and Nix installation:

just doctor-local

This command, defined in the justfile, ensures your system meets all prerequisites before attempting to start the stack.

Start the Full Stack

Execute the primary run command, using the --no-doppler flag if you do not have access to the team's Doppler secret store:

just run_local --no-doppler

This command performs several actions defined in docker/docker-compose.yml and docker/docker-compose-databases.yml:

• Spins up Postgres, Redis, LocalStack, OpenSearch, Kafka, and FusionAuth containers
• Compiles Rust services using cargo zigbuild
• Mounts native binaries into containers
• Starts the local proxy serving the SolidJS frontend

Once startup completes, the terminal displays the local URL, typically http://localhost:3000/app/.

Access the Application and Configure Authentication

Navigate to the printed URL in your browser. Register a new user with any email address. Macro uses a passwordless login flow that sends one-time codes to Mailpit at http://localhost:8025 instead of actual email servers, allowing immediate local testing.

Seed Realistic Demo Data

Populate the environment with a complete workspace including users, teams, channels, documents, and tasks:

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

The seed-scenario command, implemented in tooling/seed_cli/, generates login links for seeded personas like alice@seed.macro.local. Open these links in separate browser tabs to test multi-user interactions on your local stack.

Advanced Local Development Workflows

Hot-Reload During Active Development

While the stack runs attached to your terminal, use these hotkeys:

• Press r to rebuild only changed Rust services and reload them without restarting the entire stack
• Press q to gracefully stop all containers and clean up resources

Run Multiple Isolated Stacks

Test different configurations simultaneously by using the --instance flag to create parallel environments:

just run_local --instance demo-a --no-doppler

If default ports conflict with existing local services, adjust the port window with --port-base.

Enable Real Third-Party Integrations

For testing OAuth or external APIs, create a local.env file with real credentials:

# local.env

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET_KEY=your_secret
GITHUB_CLIENT_ID=your_github_id
GITHUB_CLIENT_SECRET=your_github_secret

Start the stack with your custom environment:

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

Summary

• Enter the Nix shell (nix develop) to obtain all build tools including just, Cargo, and Bun without system-wide installation.
• Run the stack with just run_local --no-doppler to orchestrate Docker containers for Postgres, Redis, Kafka, OpenSearch, and Rust microservices.
• Access Mailpit at http://localhost:8025 to retrieve passwordless login codes during user registration.
• Seed data using just seed-scenario apply to generate realistic demo workspaces with tooling/seed_cli/.
• Use hotkeys (r for rebuild, q for quit) and instance flags (--instance) for efficient iterative development on the macro-inc/macro codebase.

Frequently Asked Questions

Do I need Doppler secrets to run Macro locally?

No. Use the --no-doppler flag with just run_local to run the stack with stubbed or default configurations. Doppler is only required for accessing production-equivalent secrets; local development functions fully without it by using Mailpit for email and LocalStack for AWS services.

What ports does Macro use for local development?

The default configuration exposes ports defined in docker/docker-compose.yml and docker/docker-compose-databases.yml, including 3000 for the frontend proxy, 8025 for Mailpit, 5432 for Postgres, and 6379 for Redis. Use --port-base when running just run_local to shift the entire port window if conflicts occur.

How do I rebuild only the Rust services without restarting everything?

While the stack is attached to your terminal, press the r key. This triggers cargo zigbuild for only the changed crates under crates/ and reloads the services in their Docker containers while keeping databases and other infrastructure running.

Can I run the stack in the background without an attached terminal?

Yes. Use just stack up to start all services detached, then check status with just stack status --json or tear down with just stack down. These commands provide headless operation suitable for CI pipelines or when you need your terminal free for other tasks.

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