Prerequisites for Developing Macro: Complete Development Environment Setup

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

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

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