# What Are the Prerequisites for Using Macro? Complete Setup Guide for 2024

> Discover the prerequisites for using Macro locally. Learn about Docker, Rust, Node.js, Just, Nix, and database requirements for a smooth setup in 2024.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: how-to-guide
- Published: 2026-08-14

---

**To use Macro locally, you need Docker, Rust (stable toolchain), Node.js ≥18, Just, and optionally Nix for reproducible environments—plus PostgreSQL, Redis, and OpenSearch running in containers.**

Macro is a full-stack, Rust-based workspace that combines a SolidJS web UI with a suite of micro-services. Understanding the prerequisites for using Macro ensures you can build, test, and run the entire stack without hitting environment-specific roadblocks. This guide covers every dependency, where it's documented in the source code, and the exact commands to get started.

---

## Core Prerequisites for Running Macro

The Macro repository at `macro-inc/macro` expects these foundational tools on your development machine:

- **Docker** — Required for all databases and containerized services
- **Rust toolchain (stable)** — `rustc`, `cargo`, and `rustup` for compiling services
- **Node.js ≥18 with npm or Yarn** — Powers the SolidJS front-end in `apps/web/`
- **Just** — Task runner defined in the repository's `justfile`

According to the [README](https://github.com/macro-inc/macro/blob/main/README.md#built-in-solidjs-and-rust), these four tools form the minimum viable environment. The `justfile` at the repository root centralizes shortcuts like `just build`, `just test`, and `just dev-web`.

---

## Database and Service Dependencies

Macro's architecture relies on three containerized data stores. These spin up via Docker rather than requiring native installation:

| Service | Purpose | Documentation Location |
|---------|---------|------------------------|
| **PostgreSQL** | Core data persistence (*MacroDB*) | [[`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#prerequisite) |
| **Redis** | Caching and session management | [[`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) |
| **OpenSearch** | Document, email, and message search index | [[`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) |

The [[`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#prerequisites) file explicitly lists Docker as a prerequisite precisely because these services run as containers.

---

## Optional but Recommended Tools

### Nix for Reproducible Environments

While not strictly required, **Nix** provides the smoothest path through Macro's prerequisites. 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 how `nix develop` automatically installs correct versions of Rust, Node, and supporting tools—eliminating version drift across machines.

### AWS Credentials and Doppler

Two additional pieces unlock full cloud functionality:

- **AWS credentials** — Required for S3 storage, SQS queues, and Lambda triggers in production deployments. Local development can use mock services, but real credentials are needed for the full cloud stack documented in [[`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)

- **Doppler account** — Environment variables (API keys, secrets) flow through the `macro_env_var` crate rather than `std::env`. The README's [Development Notes section](https://github.com/macro-inc/macro/blob/main/README.md#development-notes) emphasizes this architectural choice for secure secret management

---

## Step-by-Step Local Setup

With prerequisites installed, this sequence boots the complete Macro environment:

```bash

# 1. Install system tools (macOS example via Homebrew)

brew install docker rustup node just nix

# 2. Initialize language runtimes

rustup default stable
nvm install 18 && nvm use 18

# 3. Clone and enter development shell

git clone https://github.com/macro-inc/macro.git
cd macro
nix develop  # Optional: pins all tool versions

# 4. Start database infrastructure

just setup_macrodb      # PostgreSQL container + migrations

just setup_test_envs    # Generates .env files for tests

just prepare_db         # Builds SQLx offline query cache

# 5. Build and verify

just build
just test

```

The `just prepare_db` command deserves special attention. As documented in the [SQLx Workflow section](https://github.com/macro-inc/macro/blob/main/README.md#sqlx-workflow), Macro compiles SQLx queries offline. After any schema migration, you **must** run `just prepare_db` to refresh the `.sqlx` cache or compilation fails.

---

## Running the Web UI and Services

Once prerequisites are satisfied, launch components individually:

| Command | What It Starts |
|---------|--------------|
| `just dev-web` | SolidJS front-end with hot reload |
| `just run <service-name>` | Individual Rust micro-service |
| `just test` | Full test suite against running containers |

The front-end specifically requires Node ≥18 as documented in [[`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). SolidJS and its build pipeline depend on modern Node features unavailable in earlier versions.

---

## Key Source Files for Prerequisites

Reference these locations when troubleshooting setup issues:

- [`README.md`](https://github.com/macro-inc/macro/blob/main/README.md) — High-level overview and development commands
- `justfile` — All task definitions (`just build`, `just test`, etc.)
- [`crates/macro_db_client/README.md`](https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/README.md) — PostgreSQL requirements and migrations
- [`infra/stacks/opensearch/README.md`](https://github.com/macro-inc/macro/blob/main/infra/stacks/opensearch/README.md) — Search index prerequisites
- [`infra/stacks/cloud-storage-cache/README.md`](https://github.com/macro-inc/macro/blob/main/infra/stacks/cloud-storage-cache/README.md) — Redis cache setup
- [`apps/web/README.md`](https://github.com/macro-inc/macro/blob/main/apps/web/README.md) — Front-end Node.js requirements
- [`infra/README.md`](https://github.com/macro-inc/macro/blob/main/infra/README.md) — Nix development environment guide

---

## Summary

- **Four core tools** are mandatory: Docker, Rust (stable), Node.js ≥18, and Just
- **Three databases** run in Docker: PostgreSQL (*MacroDB*), Redis, and OpenSearch
- **Nix** automates dependency management but remains optional
- **AWS credentials and Doppler** unlock production cloud features
- **`just prepare_db`** is required after any schema change for SQLx offline compilation
- All prerequisites are documented across the `justfile`, root [`README.md`](https://github.com/macro-inc/macro/blob/main/README.md), and stack-specific readmes

---

## Frequently Asked Questions

### Do I need to install PostgreSQL, Redis, or OpenSearch natively?

No. Macro runs these as Docker containers. The `just setup_macrodb` and related commands manage container lifecycle and initial schema migrations. Native installations are unsupported and unnecessary.

### What happens if I skip `just prepare_db`?

Compilation fails. Macro uses SQLx's offline mode, which requires cached query metadata in `.sqlx/`. Running `just prepare_db` regenerates this cache after any `migrations/` change. The [README's SQLx Workflow section](https://github.com/macro-inc/macro/blob/main/README.md#sqlx-workflow) documents this requirement explicitly.

### Is Nix actually optional for using Macro?

Yes, though strongly recommended. You can install Rust, Node, and Just through standard package managers. Nix simply guarantees identical versions across all developer machines via `nix develop`. Without it, you may encounter subtle version incompatibilities.

### Why does Macro use Doppler instead of .env files?

Security and auditability. The `macro_env_var` crate centralizes secret access rather than scattering `std::env` calls throughout the codebase. This design choice, documented in [Development Notes](https://github.com/macro-inc/macro/blob/main/README.md#development-notes), enables rotation logging and prevents accidental secret exposure in logs or stack traces.