How to Run Macro Locally with Stubbed Secrets: Complete Setup Guide

Running Macro locally requires only Nix and uses the --no-doppler flag to launch a fully stubbed development stack with placeholder values for all secrets, enabling immediate local development without external API keys.

The Macro collaboration platform (macro-inc/macro) ships with a deterministic local development environment that eliminates the need for production credentials. By leveraging the stubbed secrets system, developers can spin up the entire service architecture—including Postgres, Redis, OpenSearch, Kafka, and FusionAuth—using only code-defined placeholder configuration values. This approach allows you to run macro locally with stubbed secrets while maintaining full platform functionality for authentication, document storage, and real-time collaboration.

Prerequisites: Install Nix

Macro requires Nix as the sole host-level dependency. Nix provides the Docker CLI, Docker Compose, and all Rust toolchains required for the build without polluting your system.

Install Nix using the official installer:

curl -L https://nixos.org/nix/install | sh

After installation, restart your shell or run exec $SHELL to ensure the Nix daemon is available.

Enter the Nix Development Shell

Navigate to the repository root and enter the development shell. This command makes just, Cargo, Bun, sqlx, and Docker tooling available automatically.

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

Inside this shell, you have access to all build tools defined in the project's Nix flake, ensuring reproducible builds across all developer machines.

Start the Stack with Stubbed Secrets

To launch the local stack without Doppler or real API keys, use the --no-doppler flag. According to the justfile, this command generates Docker Compose configurations in infra/local/generated/ and starts all services using stubbed values.

just run_local --no-doppler

The --no-doppler flag instructs Macro to use code-defined configuration with deterministic stub values for every secret. Internal plumbing keys such as REDIS_HOST, MACRO_DB_URL, and OPENSEARCH_USERNAME are pre-configured to local-compatible defaults in docker/docker-compose.yml, requiring no manual editing. Third-party integration keys for Google, GitHub, Stripe, and CloudFront remain stubbed, meaning those specific flows are gracefully disabled while the core platform—authentication, document storage, email handling, and search—functions out of the box.

Override Secrets for Real Integrations

While the stubbed configuration supports most development workflows, you may need to test live third-party integrations. Create a local.env file containing real API keys, then pass it using the --env-file flag to override specific stubs while keeping others placeholdered.

Create local.env:

STRIPE_SECRET_KEY=sk_live_XXXXXXXXXXXXXXXX
STRIPE_PRICE_ID=price_XXXXXXXXXXXXXXXX

Restart the stack with your overrides:

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

Values provided in --env-file take precedence over stub defaults, enabling selective integration testing without exposing unnecessary secrets.

Verify the Local Environment

Once just run_local completes, the terminal displays the frontend URL (typically http://localhost:3000/app/) and backend service endpoints.

Authentication uses a passwordless flow: enter any email address on the login screen, and the one-time code appears instantly in Mailpit at http://localhost:8025. This local email catcher eliminates the need for real SMTP credentials.

To populate the environment with realistic demo data, run:

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

This command creates sample users, teams, channels, documents, and tasks as defined in the scenario file.

Key Files in the Local Stack

Understanding these source files helps debug the stubbed environment:

• docs/RUNNING_LOCALLY.md — Comprehensive guide on launch procedures, stub behavior, and integration overrides.
• justfile — Defines the run_local, seed-scenario, and doctor-local commands orchestrating the workflow.
• docker/docker-compose.yml — Core service definitions for Postgres, Redis, LocalStack, OpenSearch, and Kafka used by the local stack.
• seed/scenarios/team-perms.json — Sample dataset creating users, teams, channels, documents, tasks, and permissions for demonstration purposes.

Summary

• Nix is the only host dependency required to run Macro locally, providing Docker and Rust toolchains through nix develop.
• The just run_local --no-doppler command launches a fully functional stack using stubbed secrets for all internal and third-party services.
• Stubbed secrets use deterministic placeholder values pre-configured in the codebase, eliminating manual .env setup.
• To test live integrations, create a local.env file and pass it via --env-file ./local.env to override specific stubs.
• Local authentication codes appear in Mailpit at localhost:8025, and sample data can be loaded via just seed-scenario.

Frequently Asked Questions

What services run in the stubbed local stack?

The stack launches Postgres, Redis, LocalStack (for S3-compatible storage), OpenSearch, Kafka, and FusionAuth inside Docker containers. According to docker/docker-compose.yml, these services communicate over a generated local network with pre-configured credentials that require no manual setup.

Can I test third-party integrations like Stripe or Google Login locally?

Yes. While the default stubbed configuration disables these flows, you can enable them by creating a local.env file with real API keys and launching with just run_local --no-doppler --env-file ./local.env. This overrides only the specified secrets while keeping all other services stubbed.

How do I view emails sent by the local stack?

All outbound emails from the local environment are captured by Mailpit, accessible at http://localhost:8025. This includes passwordless login codes, invitation emails, and notification digests, eliminating the need for external SMTP configuration.

Is Doppler required for local development?

No. The --no-doppler flag explicitly bypasses the Doppler secrets manager, instructing the application to load configuration from code-defined stubs. This allows offline development and CI/CD pipelines to run without Doppler access tokens.

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