# Prerequisites for Developing Macro: Complete Development Environment Setup

> Set up your Macro development environment. Learn the essential prerequisites including Docker, Rust, Node.js, Just, PostgreSQL, Redis, and OpenSearch for efficient local development.

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

---

**To develop Macro locally, you need Docker, Rust (stable), Node.js (≥18), the Just command runner, and running instances of PostgreSQL, Redis, and OpenSearch, with optional Nix for reproducible environments and Doppler for secret management.**

Macro is a full-stack workspace combining Rust microservices with a SolidJS web frontend. Before you can build, test, or contribute to the [macro-inc/macro](https://github.com/macro-inc/macro) repository, you must configure several system dependencies and containerized services that power the search, caching, and data layers.

## Core System Prerequisites for Developing Macro

### Docker

**Docker** is mandatory for local development. All databases—including PostgreSQL, Redis, and OpenSearch—spin up in Docker containers for development and testing. As documented in [[`docs/CLOUD_STORAGE.md`](https://github.com/macro-inc/macro/blob/main/docs/CLOUD_STORAGE.md)](https://github.com/macro-inc/macro/blob/main/docs/CLOUD_STORAGE.md), the infrastructure expects containerized services for consistent environments across machines.

### Rust Toolchain (Stable)

The main services are written in Rust and compiled with `cargo`. You need the stable Rust toolchain installed via **rustup**, including `rustc`, `cargo`, and `rustfmt`. The [[`README.md`](https://github.com/macro-inc/macro/blob/main/README.md)](https://github.com/macro-inc/macro/blob/main/README.md) specifies that the project is "Built in SolidJS and Rust," requiring a functional Rust environment for all backend compilation.

### Node.js (≥18) and Package Managers

The frontend application located in `apps/web/` uses **SolidJS**, which requires **Node.js** version 18 or higher. You also need **npm** or **Yarn** to install JavaScript dependencies and build the UI. Refer to [[`apps/web/README.md`](https://github.com/macro-inc/macro/blob/main/apps/web/README.md)](https://github.com/macro-inc/macro/blob/main/apps/web/README.md) for specific frontend build instructions.

### Just Command Runner

Macro uses **Just** as its command runner. The repository ships with a `justfile` containing shortcuts for building, testing, and managing services. Key commands include:

- `just build` – Compiles all Rust services
- `just test` – Runs the full test suite
- `just dev-web` – Starts the development web server
- `just prepare_db` – Refreshes the SQLx offline query cache

As noted in the main [[`README.md`](https://github.com/macro-inc/macro/blob/main/README.md)](https://github.com/macro-inc/macro/blob/main/README.md), all development workflows route through Just commands defined in the root `justfile`.

## Containerized Infrastructure Dependencies

### PostgreSQL (MacroDB)

Macro’s core data lives in a PostgreSQL instance called **MacroDB**. According to [[`crates/macro_db_client/README.md`](https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/README.md)](https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/README.md), tests and local runs expect this database to be available. Use `just setup_macrodb` to spin up the container and run migrations automatically.

### Redis for Caching

**Redis** handles caching and session management across services. The [[`infra/stacks/cloud-storage-cache/README.md`](https://github.com/macro-inc/macro/blob/main/infra/stacks/cloud-storage-cache/README.md)](https://github.com/macro-inc/macro/blob/main/infra/stacks/cloud-storage-cache/README.md) documents that Redis must run in a Docker container for local development queues and ephemeral storage.

### OpenSearch for Document Indexing

**OpenSearch** powers the search index for documents, emails, and messages. The [[`infra/stacks/opensearch/README.md`](https://github.com/macro-inc/macro/blob/main/infra/stacks/opensearch/README.md)](https://github.com/macro-inc/macro/blob/main/infra/stacks/opensearch/README.md) specifies required environment variables and container configuration for the search service to function correctly during development.

## Optional Development Tools

### Nix for Reproducible Environments

While optional, **Nix** is recommended for maintaining consistent dependency versions. Running `nix develop` in the repository root automatically installs the correct Rust, Node.js, and system tool versions. The [[`infra/README.md`](https://github.com/macro-inc/macro/blob/main/infra/README.md)](https://github.com/macro-inc/macro/blob/main/infra/README.md) provides guidance on using Nix to eliminate "works on my machine" issues across the development team.

### Doppler for Environment Variables

Macro uses **Doppler** to manage production secrets and API keys. The codebase expects variables to be loaded through the `macro_env_var` crate rather than directly via `std::env`. As stated in the Development Notes section of the README, "All environment variables should be loaded with macro_env_var," which integrates with Doppler for secure secret injection.

## Step-by-Step Local Setup Workflow

After installing the core prerequisites, execute the following workflow to prepare your environment:

```bash

# Install system tools (macOS example)

brew install docker rustup node just nix

# Initialize Rust and Node

rustup default stable
nvm install 18 && nvm use 18

# Clone and enter repository

git clone https://github.com/macro-inc/macro.git
cd macro
nix develop  # Optional: enters reproducible shell

# Start infrastructure containers

just setup_macrodb      # Spins up PostgreSQL and runs migrations

just setup_test_envs    # Creates .env files for tests

just prepare_db         # Builds SQLx offline cache required for compilation

# Build and verify

just build
just test

```

Once containers are running and the SQLx cache is prepared, start the web UI with `just dev-web` or launch individual services via `just run <service-name>`.

## Cloud and Secret Management (Optional)

### AWS Credentials

Some services interact with AWS for S3 file storage, SQS queues, and Lambda triggers. While local development can use mock services for testing, real **AWS credentials** are required for full cloud deployment scenarios. The [[`infra/stacks/web-app/README.md`](https://github.com/macro-inc/macro/blob/main/infra/stacks/web-app/README.md)](https://github.com/macro-inc/macro/blob/main/infra/stacks/web-app/README.md) details the AWS integration points.

## Summary

Successful development of the Macro codebase requires:

- **Docker** for containerized PostgreSQL, Redis, and OpenSearch
- **Rust (stable)** and **Node.js (≥18)** for backend and frontend compilation
- **Just** for standardized build and test commands
- **SQLx workflow compliance** using `just prepare_db` after any schema changes
- **Optional Nix** for reproducible development environments
- **Doppler** for production-grade secret management

## Frequently Asked Questions

### Do I need Nix to develop Macro?

No, Nix is optional but recommended. You can install Rust, Node.js, and other tools manually, but `nix develop` provides a reproducible environment that ensures version consistency with the rest of the team. The [[`infra/README.md`](https://github.com/macro-inc/macro/blob/main/infra/README.md)](https://github.com/macro-inc/macro/blob/main/infra/README.md) documents this approach.

### What database migrations are required for local development?

Run `just setup_macrodb` to automatically spin up the PostgreSQL container and execute migrations. This command handles the initial schema setup required by the `macro_db_client` crate.

### How do I refresh the SQLx query cache after schema changes?

Macro uses SQLx offline mode for compile-time query checking. After any database schema change, run `just prepare_db` to refresh the `.sqlx` cache. This step is mandatory; without it, the Rust compiler will fail with offline query validation errors.

### Are AWS credentials required for local development?

No, AWS credentials are only required for production cloud deployments or specific integration tests. Local development uses Docker containers for all infrastructure needs, and mock services can substitute AWS dependencies during testing.