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

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, 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#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)
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)

The [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) 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)

• Doppler account — Environment variables (API keys, secrets) flow through the macro_env_var crate rather than std::env. The README's Development Notes section emphasizes this architectural choice for secure secret management

---

Step-by-Step Local Setup

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

# 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, 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). 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 — High-level overview and development commands
• justfile — All task definitions (just build, just test, etc.)
• crates/macro_db_client/README.md — PostgreSQL requirements and migrations
• infra/stacks/opensearch/README.md — Search index prerequisites
• infra/stacks/cloud-storage-cache/README.md — Redis cache setup
• apps/web/README.md — Front-end Node.js requirements
• 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, 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 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, enables rotation logging and prevents accidental secret exposure in logs or stack traces.

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