# How to Set Up a Development Environment for macro-inc/macro: Complete Guide

> Easily set up a development environment for macro-inc/macro. Follow this guide to install Nix Docker clone the repo run nix develop and start the full stack with just run_local.

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

---

**To set up a development environment for macro-inc/macro, install Nix and Docker, clone the repository, run `nix develop` to enter the reproducible shell, then execute `just run_local --no-doppler` to start the full stack.**

The **macro** repository is a Rust-based microservice cloud-storage platform maintained by macro-inc. Setting up a local development environment requires orchestrating multiple backend services, databases, message queues, and a web frontend. The project uses **Nix** for reproducible tooling and **Docker Compose** for infrastructure, making the setup process straightforward once you understand the workflow.

## Prerequisites for Macro Development

Before cloning the repository, ensure you have these core tools installed:

- **Nix** — Provides the reproducible development shell containing `just`, Cargo, Rust toolchain, Bun, `sqlx`, and other dependencies.
- **Docker with Compose v2** — Runs PostgreSQL, Redis, LocalStack, OpenSearch, Kafka, FusionAuth, and all service containers.
- **Git** — For cloning the repository.

You can verify your system readiness at any time by running `just doctor-local` within the Nix shell. This command checks Docker connectivity, port availability, and container health.

## Clone the Repository and Enter the Nix Shell

Start by cloning the source code:

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

```

As documented in [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md) lines 15-17, this pulls the complete monorepo including all Rust crates, Docker configurations, and documentation.

Next, enter the Nix development environment:

```bash
nix develop

```

If you encounter "experimental features not enabled," add the required flags as described in lines 30-34 of the same guide. The Nix shell automatically places all necessary build tools on your `$PATH` — no separate Rust or Node.js installation required.

## Start the Full Local Stack

With the Nix shell active, launch the complete development environment:

```bash
just run_local --no-doppler

```

This command, defined in [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md) lines 45-48, performs three major operations:

1. **Builds all Rust services** using `cargo zigbuild` (`justfile` lines 65-66).
2. **Spins up Docker Compose** with the full infrastructure stack (`justfile` lines 42-46).
3. **Starts the proxy, frontend, and auxiliary services** through the `run_local` recipe.

The `--no-doppler` flag uses built-in stub configuration, enabling development without access to the team's Doppler secrets. Once complete, the frontend is available at `http://localhost:3000/app`.

## Verify and Seed Your Development Environment

Run the health check to confirm everything started correctly:

```bash
just doctor-local

```

This probes Docker connectivity, port availability, and container health. If ports 8080 or 8090 are in use (common on macOS), it suggests alternative base ports.

A fresh stack contains no data. Populate it with realistic demo content:

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

```

As documented in [`RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/RUNNING_LOCALLY.md) lines 87-89, this command:

- Creates FusionAuth accounts for persona users (Alice, Bob, etc.).
- Populates users, teams, channels, projects, documents, chats, calls, and emails.
- Prints login URLs for each persona to test multi-user workflows.

Manage seed state with:

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

```

## Advanced: Multiple Stack Instances

To run multiple isolated environments — useful for testing version-specific migrations — use named instances with custom port ranges:

```bash
just run_local --instance agent-a --port-base 23000 --no-doppler

```

All containers, networks, and volumes receive the instance prefix for complete isolation. See [`RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/RUNNING_LOCALLY.md) lines 48-62 for full details.

## Essential Development Commands

| Command | Purpose |
|---------|---------|
| `just run_dev` | Run a single binary against shared dev resources (requires Doppler). |
| `just stack up` | Start stack without attached terminal (CI-friendly). |
| `just stack update` | Rebuild only changed services. |
| `just stack down` | Tear down all containers and networks. |
| `just build` | Build all services after dependency changes. |
| `just clippy` | Run extended lints and best-practice checks. |
| `just doctor-local` | Full pre-flight health check. |
| `just reset_local --instance <name>` | Drop, recreate, and migrate database for instance. |

All commands are defined in the `justfile`, with the `run_local` recipe starting at line 41.

## Optional: Real Integration Secrets

The stub configuration disables third-party integrations (Google, GitHub, Stripe, CloudFront). To test these flows, create a `local.env` file with your credentials and run:

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

```

These values override built-in defaults. See [`RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/RUNNING_LOCALLY.md) lines 9-15 for supported environment variables.

## Summary

Setting up a macro-inc/macro development environment follows this workflow:

- Install **Nix** and **Docker** as foundational tools.
- Use `nix develop` to enter a reproducible shell with all build dependencies.
- Run `just run_local --no-doppler` to build and start the complete service stack.
- Execute `just seed-scenario apply` to populate realistic demo data.
- Use `just doctor-local` for troubleshooting and verification.

## Frequently Asked Questions

### Do I need Doppler access to develop locally?

No. The `--no-doppler` flag enables full local development using stub configuration for all secrets. This is the recommended approach for external contributors according to the [`RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/RUNNING_LOCALLY.md) guide.

### Why does my build fail with port conflicts?

Ports 8080 and 8090 are commonly occupied on macOS by AirPlay or other services. Run `just doctor-local` to detect conflicts, then specify an alternative base port with `--port-base 23000` or similar.

### How do I reset the database without rebuilding everything?

Use `just reset_local --instance <name>` to drop, recreate, and migrate the database for your stack instance. This preserves container builds while clearing application data.

### Can I run only specific services during development?

Yes. While `just run_local` starts everything, you can use `just run_dev` to run a single Rust binary against the shared infrastructure, or modify [`docker/docker-compose-databases.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose-databases.yml) to selectively disable services.