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

> Clone macro-inc/macro and run the project locally. Enter the Nix shell with nix develop and use just run_local to launch the full Docker stack with Postgres Redis Rust and SolidJS.

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

---

**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`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) and [`docker/docker-compose-databases.yml`](https://github.com/macro-inc/macro/blob/main/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:

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

```bash
nix develop .#tauri-linux

```

### Verify Your Environment (Optional)

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

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

```bash
just run_local --no-doppler

```

This command performs several actions defined in [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) and [`docker/docker-compose-databases.yml`](https://github.com/macro-inc/macro/blob/main/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:

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

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

```bash

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

```bash
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`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) and [`docker/docker-compose-databases.yml`](https://github.com/macro-inc/macro/blob/main/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.