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

> Learn how to set up the Macro Inc. development environment with Docker, Nix, and Just. Bootstrap your Rust microservices and connect to PostgreSQL, Redis, and OpenSearch.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: getting-started
- Published: 2026-08-20

---

**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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml), while the high-level developer workflow is documented in [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md).

## Enter the Nix Development Shell

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

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

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

```

Then generate the required `.env` files and apply migrations:

```bash
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`](https://github.com/macro-inc/macro/blob/main/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:

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

```bash
just stack up --no-doppler

```

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

```bash
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`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md) and [`infra/preview/README.md`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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:

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

```bash
just build_document_storage_service
just deploy_document_storage_service

```

Individual service README files such as [`services/document_storage_service/README.md`](https://github.com/macro-inc/macro/blob/main/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:

```bash
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`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md)** for the canonical local development guide and [`tools/xtask/src/main.rs`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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.