# How to Set Up the Macro Development Environment: A Complete Guide > Set up your macro development environment effortlessly. Clone macro-inc/macro, run nix develop, and start local services with just run_local. Your complete guide. - Repository: [Macro/macro](https://github.com/macro-inc/macro) - Tags: how-to-guide - Published: 2026-08-21 --- **Install Nix and Docker, clone the `macro-inc/macro` repository, run `nix develop`, then execute `just run_local --no-doppler` to orchestrate Postgres, Redis, Kafka, and FusionAuth locally.** Macro is a Rust-based, multi-service workspace that combines email, chat, documents, tasks, and CRM into a bidirectional-graph-driven system. Setting up the Macro development environment requires orchestrating a complex local stack including OpenSearch, LocalStack (S3), and FusionAuth alongside the Cargo workspace. This guide provides the exact commands and file paths from the official repository to get you running locally. ## Prerequisites Before cloning the repository, install the foundational tooling that manages the entire toolchain. - **Nix** – The package manager provides `just`, Cargo, Rust, Bun, Zig, and `cargo-zigbuild` through a declarative shell. Install via [nix.dev](https://nix.dev/install-nix). - **Docker with Compose v2** – Required for the Postgres, Redis, OpenSearch, Kafka, and FusionAuth containers. Docker Desktop, OrbStack, or Colima are all compatible. Ensure the Docker daemon is running before proceeding. ## Initial Setup ### Clone the Repository and Enter the Nix Shell Clone the repository and enter the reproducible development environment: ```bash git clone https://github.com/macro-inc/macro.git cd macro nix develop ``` If `nix develop` fails, enable experimental features for that session: ```bash nix develop --extra-experimental-features nix-command --extra-experimental-features flakes ``` To make these features permanent, add `experimental-features = nix-command flakes` to `~/.config/nix/nix.conf`. ### Platform-Specific Tauri Setup (Optional) For desktop or mobile development, load the platform-specific Nix shell: ```bash # Linux desktop nix develop .#tauri-linux # Android on x86_64 Linux nix develop .#tauri-android ``` ## Start the Local Stack Launch the full development stack without external secrets: ```bash just run_local --no-doppler ``` The `justfile` recipe performs the following actions: 1. Builds all Rust services in the `services/` directory. 2. Spins up Docker containers defined in [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) for Postgres, Redis, LocalStack, OpenSearch, Kafka, and FusionAuth. 3. Launches the proxy and SolidJS frontend located in `apps/web/`. 4. Attaches an interactive session for hot-reloading. ## Verify and Seed Data ### Health Checks Before interacting with the UI, confirm the stack is healthy: ```bash just doctor-local ``` The `doctor-local` command verifies Docker connectivity, port availability, and service responsiveness. ### Seeding Realistic Test Data Populate the database with users, teams, channels, and documents: ```bash just seed-scenario apply --file seed/scenarios/team-perms.json ``` This creates FusionAuth accounts for test personas and prints login URLs such as `http://alice.localhost:3000/app/login?email=alice@seed.macro.local`. Open these URLs in separate browser tabs to simulate multi-user collaboration. ## Development Workflows ### Hot-Reloading Changes While `just run_local` is attached, use the interactive controls: - Press **`r`** – Rebuild any changed Rust services and reload them. - Press **`q`** – Gracefully stop the stack, removing containers and volumes. ### Running Multiple Isolated Instances Test different branches or features simultaneously using separate Docker Compose projects: ```bash # Default instance just run_local --instance agent-a # Separate instance with isolated volumes and networks just run_local --instance agent-b ``` If you encounter port conflicts, shift the entire port range: ```bash just run_local --port-base 41000 ``` ### Headless Operation (CI/Automation) For automated testing or scripts, use the stack commands without the interactive loop: ```bash just stack up # Launch services just stack status --json # Machine-readable health status just stack update # Rebuild changed services (equivalent to pressing 'r') just stack down # Clean shutdown ``` ## Enabling Real Third-Party Integrations To test with live APIs (Google OAuth, GitHub, Stripe), create a `local.env` file with real credentials: ```bash # local.env GOOGLE_CLIENT_ID=your_real_id GITHUB_CLIENT_ID=your_real_id STRIPE_SECRET_KEY=your_real_key ``` Launch the stack with your overrides: ```bash just run_local --no-doppler --env-file ./local.env ``` Only the keys you supply override the stub values; internal secrets remain configured for local defaults. ## Key Files in the Repository Understanding these paths accelerates debugging and customization: - **[`README.md`](https://github.com/macro-inc/macro/blob/main/README.md)** – High-level architecture overview and contributor entry point. - **[`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md)** – Detailed troubleshooting and advanced configuration. - **`justfile`** – Contains all orchestration recipes including `run_local`, `seed-scenario`, and `doctor-local`. - **[`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml)** – Defines the Postgres, Redis, OpenSearch, Kafka, and FusionAuth services. - **`crates/macro_db_client/`** – Central PostgreSQL client with SQLx queries and migrations. - **`services/`** – Individual microservices (e.g., `document_storage_service`, `email_service`). - **`apps/web/`** – SolidJS frontend and Tauri desktop entry point. - **`infra/local/generated/`** – Auto-generated network configs and port mappings for each named instance. ## Summary - Install **Nix** and **Docker** as the foundation for the toolchain. - Enter the reproducible shell with `nix develop` to receive `just`, Rust, and Bun. - Launch the stack via `just run_local --no-doppler` to orchestrate all backend services. - Verify health with `just doctor-local` and seed data using `just seed-scenario`. - Use interactive hotkeys (`r` to rebuild, `q` to quit) during active development. - Isolate instances with `--instance ` or `--port-base ` for parallel testing. ## Frequently Asked Questions ### Do I need Doppler to run Macro locally? No. Use the `--no-doppler` flag with `just run_local` to run entirely with local defaults. Doppler is only required for `just run_dev`, which connects to cloud-hosted resources rather than the Docker Compose stack. ### Can I run a single service without the full stack? Yes. If you have Doppler access, use `just run_dev` to run a specific backend binary against shared development resources. This skips the Docker orchestration and is faster for iterating on a single crate in `services/`. ### Why does the build require Nix instead of just Rust? Nix provides exact versions of `cargo-zigbuild`, `sqlx`, Bun, Zig, and `just` in a reproducible shell that matches the CI environment. This eliminates "works on my machine" issues across the `crates/` and `services/` workspace boundaries. ### How do I debug port conflicts when running multiple instances? Macro automatically assigns deterministic port ranges per instance. If the default ports (starting at 3000/5432/etc.) are occupied, launch with `just run_local --port-base 41000` to shift the entire stack to 41000-range ports, or use `--instance ` to create completely isolated Docker networks and volumes.