How to Set Up the Macro Inc. Development Environment: A Complete Guide

Setting up the Macro Inc. development environment requires Docker, Nix, and the Just task runner to bootstrap a Rust microservice architecture with PostgreSQL, Redis, and OpenSearch containers.

The macro-inc/macro repository is a Rust-based, multi-service micro-architecture that relies on Nix for reproducible builds and Docker for local databases. According to docs/RUNNING_LOCALLY.md, developers enter a Nix shell and use commands defined in the justfile to compile roughly 80 crates and orchestrate the local stack. This guide provides the exact commands and source file references needed to build, run, and test the application on your machine.

Prerequisites: Docker, Nix, and Just

Before compiling any Rust code, install the following tools on your host machine:

• Docker — required to run PostgreSQL, OpenSearch, Redis, and other backing services defined in docker/docker-compose.yml.
• Nix — the package manager that provides a deterministic toolchain including Rust, Cargo, and auxiliary utilities.
• Just — the task runner invoked by commands such as just build; it is automatically available inside the Nix shell, but you may install it separately if preferred.

All containerized services are defined in docker/docker-compose.yml, while the high-level developer workflow is documented in docs/RUNNING_LOCALLY.md.

Enter the Nix Development Shell

Drop into the repository's declarative shell to guarantee exact compiler versions:

nix develop

This command places just, cargo, docker, pulumi, and other build dependencies on your PATH automatically. The environment matches the specifications encoded in the repository's Nix configuration, ensuring consistent behavior across developer machines.

Start the Local Database Stack

Macro uses several PostgreSQL databases—including macrodb, commsdb, emaildb, and contactsdb—that must be running before you build or test services.

First, start the Postgres container:

docker compose -f docker/docker-compose.yml up -d postgres

Then generate the required .env files and apply migrations:

just setup_test_envs
just initialize_dbs

The just setup_test_envs command creates local .env files used by the test suites, while just initialize_dbs runs migrations for every service database. These helper commands are defined in the justfile and implemented in tools/xtask/src/main.rs and tools/xtask/crates/xtask_workflows/src/*.

If you add new environment variables later, load them through the macro_env_var crate rather than with std::env::var, and store values in Doppler or the local .env placeholders generated above.

Build All Services

Compile the entire workspace and verify that no compilation errors exist:

just build

This single command builds every Rust crate and Lambda binary in the workspace. The justfile defines this target, which orchestrates cargo invocations across the roughly 80 crates contained in the repository.

Run the Full Stack Locally

With databases running and binaries compiled, start all microservices:

just stack up --no-doppler

If you have Doppler credentials and need live secret injection, omit the --no-doppler flag:

just stack up

This spins up the web app, background workers, Lambda emulators, and supporting infrastructure using Docker and Nix. The stack behavior is documented in docs/RUNNING_LOCALLY.md and infra/preview/README.md, while orchestration logic lives in the justfile.

Once running, access the local endpoints:

• Web UI: http://localhost:8090/app/
• Mailpit (email sandbox): http://localhost:8090/mailpit/
• FusionAuth (authentication): http://localhost:9011/

These URLs are listed in README.md and let you interact with the UI, inspect outbound emails, and authenticate through the local identity provider.

Log In with the Passwordless Developer Flow

Macro's development environment uses a passwordless login flow to avoid secret handling in local builds.

Open http://localhost:8090/app/ and enter a seeded email address such as alice@seed.macro.local. The one-time code and magic link appear instantly in Mailpit at http://localhost:8090/mailpit/. Click the link to complete authentication.

This flow is described in README.md and relies on the local FusionAuth instance running at http://localhost:9011/.

Run the Test Suite

Execute the full test suite against the live local database:

just test

Tests rely on a running Postgres instance, so keep the Docker database stack active. The just test command is defined in the justfile and invokes the appropriate cargo test workflows for the workspace.

Optional: Build or Deploy a Single Service

For fast iteration on a specific crate without rebuilding the entire workspace, use service-specific just commands. For example:

just build_document_storage_service
just deploy_document_storage_service

Individual service README files such as services/document_storage_service/README.md contain additional context for their respective crates.

Clean Up the Local Stack

To stop all containers and free resources:

just stack down

Run this command whenever you need to reset the environment or shut down the development stack after a session.

Summary

• Install Docker and Nix before entering the nix develop shell, which supplies just and the Rust toolchain automatically.
• Start databases first with docker compose -f docker/docker-compose.yml up -d postgres, then run just setup_test_envs and just initialize_dbs.
• Build everything with just build, then launch the stack via just stack up --no-doppler.
• Access the UI at http://localhost:8090/app/ and log in using seeded emails and Mailpit.
• Run tests with just test while the Postgres container remains active.
• Refer to docs/RUNNING_LOCALLY.md for the canonical local development guide and tools/xtask/src/main.rs for the implementation of helper workflows.

Frequently Asked Questions

Do I need Doppler to run the Macro Inc. development environment locally?

No. You can start the local stack without Doppler credentials by passing the --no-doppler flag to just stack up. This disables live secret injection and uses local .env placeholders instead.

What databases does the Macro stack require for local development?

The stack requires several PostgreSQL databases—macrodb, commsdb, emaildb, and contactsdb—which are created and migrated via just initialize_dbs after starting the Postgres container with docker compose -f docker/docker-compose.yml up -d postgres.

How do I log in to the local Macro application?

Use the passwordless developer flow documented in README.md. Enter a seeded email such as alice@seed.macro.local into the web UI, then retrieve the one-time code from Mailpit at http://localhost:8090/mailpit/ to complete login.

Can I build and test a single service instead of the entire workspace?

Yes. The justfile exposes service-specific targets such as just build_document_storage_service and just deploy_document_storage_service, which compile and deploy an individual crate without rebuilding all 80 workspace crates.

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