How to Start the Local Macro Stack: Complete Docker Compose Guide

You can start the local Macro stack by running just run_local --no-doppler inside the Nix dev shell, which launches Docker containers for Postgres, Redis, LocalStack, and other services alongside the compiled Rust backend.

The Macro repository provides a fully containerized local development environment that mirrors production micro-service architecture. According to the macro-inc/macro source code, you can spin up the entire stack—including databases, search indexes, and authentication services—using deterministic stubbed configuration that requires no external cloud access.

Prerequisites

Install Nix, the only host-level dependency required by Macro:

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

Enter the development shell to load the Rust toolchain, Docker utilities, and just task runner:

nix develop

If this command fails, enable experimental features as documented in docs/RUNNING_LOCALLY.md.

Basic Startup Without Doppler

The fastest way to start the local Macro stack uses stubbed configuration values that simulate production integrations without requiring real API keys.

Launch the Stack

Execute the run_local recipe from the justfile:

just run_local --no-doppler

This command orchestrates multiple steps defined in docs/RUNNING_LOCALLY.md: it compiles the Rust services, starts the Docker Compose stack defined in docker/docker-compose.yml, and initializes containers for Postgres, Redis, LocalStack (AWS S3 mock), OpenSearch, Kafka, and FusionAuth.

Access the Application

Once startup completes, the terminal displays:

Frontend URL: http://localhost:3000/app/

Open this URL in your browser. The stack uses passwordless login: register any email address, then retrieve the one-time code from Mailpit at http://localhost:8025.

Control the Running Stack

While the terminal remains attached to the stack, use these hot-keys:

• r – Rebuild only the Rust services whose binaries changed
• q – Gracefully stop and remove all containers

Always press q to tear down the stack. Closing the terminal directly can leave orphaned containers and volumes.

Understanding the Local Architecture

The local stack simulates production through several coordinated components:

• Nix dev shell – Provides just, Cargo, the Rust toolchain, and Docker tooling as the single host-level prerequisite. All commands must run from inside nix develop.

• Docker Compose services – The docker/docker-compose.yml defines containers for Postgres, Redis, LocalStack, OpenSearch, Kafka, and FusionAuth, mirroring the production micro-service architecture.

• Stubbed configuration – A set of deterministic keys (e.g., dummy AWS credentials) defined in the local infrastructure setup satisfies service config loaders without accessing Doppler.

• Hot-reload proxy – Watches for source changes and triggers incremental rebuilds of Rust services during development.

Configuration and state for each stack instance are generated in infra/local/generated/, including port mappings and volume definitions.

Running With Real Integrations

To test third-party flows like Google login, GitHub OAuth, or Stripe billing, supply real secrets via Doppler or a local environment file.

Using Doppler:

just run_local

Using a local.env file:

Create local.env with the specific variables you need, then:

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

Only the variables you list override the built-in stubs; all other services continue using deterministic defaults.

Working With Named Instances

You can spin up multiple isolated stacks for parallel development or Git work-trees. Each instance receives its own port window, volumes, and network.

Start a named instance with a custom port base:

just run_local --no-doppler --instance agent-a --port-base 31000

Check the health of a specific instance:

just status_local --instance agent-a --port-base 31000

Seed data for a named instance:

just seed-scenario --instance agent-a --port-base 31000 \
    apply --file seed/scenarios/team-perms.json

Instance-specific configuration and snapshots are stored in infra/local/generated/ under the instance name.

Seeding Sample Data

Populate the stack with a realistic demo world using the seed-scenario recipe:

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

This creates users, teams, channels, documents, and tasks defined in seed/scenarios/team-perms.json, and prints login links for each test persona.

Summary

• Enter the Nix dev shell (nix develop) before running any commands.
• Use just run_local --no-doppler to start the stack with stubbed configuration.
• Access the UI at http://localhost:3000/app/ and Mailpit at http://localhost:8025.
• Press q while attached to gracefully stop the stack and clean up containers.
• Supply real secrets via --env-file ./local.env or omit --no-doppler to use Doppler.
• Run multiple isolated stacks using --instance <name> and --port-base <number>.

Frequently Asked Questions

Can I run multiple local stacks simultaneously?

Yes. Use the --instance flag to create isolated environments with separate port ranges, volumes, and networks. For example, just run_local --no-doppler --instance feature-x --port-base 32000 starts a completely independent stack that will not conflict with your default instance on port 3000.

Do I need Doppler access to run Macro locally?

No. The --no-doppler flag uses deterministic stubbed configuration values that satisfy all service requirements. You only need real secrets when testing specific third-party integrations like OAuth or payment processing.

How do I update the stack after modifying Rust source code?

While the stack is running and your terminal is attached, press r to rebuild only the services whose binaries changed. This hot-reload mechanism compiles incrementally and restarts the affected containers without tearing down the entire stack.

What services are included in the local Docker Compose stack?

The stack defined in docker/docker-compose.yml includes Postgres (primary database), Redis (caching), LocalStack (AWS S3 mock), OpenSearch (full-text search), Kafka (event streaming), and FusionAuth (identity management), alongside the compiled Macro Rust services and frontend proxy.

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