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

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:

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

As documented in 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:

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:

just run_local --no-doppler

This command, defined in 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:

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:

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

As documented in 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:

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:

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

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

These values override built-in defaults. See 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 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 to selectively disable services.

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