How to Update Macro to the Latest Version: A Complete Step-by-Step Guide

Updating Macro requires synchronizing source code, SQLx cache, database migrations, and Docker services using the just task runner.

Keeping your local Macro environment current ensures compatibility with the latest Rust services, TypeScript frontend, and database schema. This guide follows the official repository structure in macro-inc/macro and uses the justfile-defined workflows that the core team maintains.

Prerequisites

Before starting, verify you have:

• Git access to the repository
• The just command runner installed (cargo install just or system package manager)
• Docker and Docker Compose running locally
• A working Nix shell environment (see docs/RUNNING_LOCALLY.md for setup)

Step 1: Fetch the Latest Source Code

Pull the newest commits from the main branch to receive updated Rust crates, TypeScript packages, and infrastructure definitions.

git pull origin main

If you're starting fresh, clone the repository instead:

git clone https://github.com/macro-inc/macro.git
cd macro

Step 2: Update the SQLx Offline Cache

Macro uses SQLx compile-time query validation. After any schema change, you must regenerate the cached metadata so the Rust compiler can type-check database queries.

just prepare_db

This command inspects the migration files in crates/macro_db_client and updates the offline query data that cargo build relies on.

Step 3: Run Database Migrations

New releases frequently add or modify tables. Apply these changes to your local Postgres instance to keep the data model compatible.

just migrate_db

Alternatively, migrations run automatically when you start the full stack. Skip this explicit step if you plan to launch services immediately.

Step 4: Rebuild and Start the Rust Services

Compile every service with updated code and launch the complete Docker stack. The stack includes Postgres, Redis, OpenSearch, Kafka, FusionAuth, and more.

# Without Doppler secrets (uses stubbed keys for local development)

just run_local --no-doppler

If your team provides Doppler access for real integration keys, omit --no-doppler:

just run_local

According to the macro-inc/macro source code in infra/local/generated/, this command provisions deterministic ports, volumes, and network settings for your stack instance.

Step 5: Seed Sample Data (Optional)

After a fresh database, populate realistic users, channels, documents, and tasks to explore the UI effectively.

just seed-scenario apply --file seed/scenarios/team-perms.json

The justfile defines multiple seed scenarios; team-perms.json demonstrates team-based permission structures.

Step 6: Verify the Stack

Run the pre-flight health check to confirm Docker, required ports, and environment variables are correctly configured.

just doctor-local

This prints the frontend URL—typically http://localhost:3000 or your custom port base—allowing you to confirm the UI serves correctly.

Step 7: Upgrade Auxiliary Services (Conditional)

Certain services maintain Docker-built images that require explicit rebuilding when their code changes:

• sync_service
• lexical_service
• websocket_service

Add the --build-aux-services flag when these components update:

just run_local --no-doppler --build-aux-services

Handling Common Edge Cases

Port conflicts – macOS commonly reserves ports 8080 and 8090. Detect conflicts with just doctor-local, then launch with a custom base port:

just run_local --instance dev --port-base 31000

Multiple stack instances – The --instance <name> flag creates isolated Docker Compose projects with separate port windows. Each instance writes configuration to infra/local/generated/<name>/.

Doppler vs. no-Doppler workflows – The --no-doppler flag exists specifically for external contributors without team secrets. Internal developers should omit it to load production-like integration keys automatically.

Key Files and Their Purposes

Understanding the repository layout helps troubleshoot update issues:

File	Purpose
justfile	Root task definitions for all commands used above
docs/RUNNING_LOCALLY.md	Complete preparation and troubleshooting guide
crates/macro_db_client	Database client crate containing migrations and schema
infra/local/generated/	Stack-specific generated configuration
seed/scenarios/	JSON seed data for different demo configurations

Summary

• Pull code first with git pull to receive latest changes
• Regenerate SQLx cache with just prepare_db after any schema change
• Apply migrations via just migrate_db or automatic stack startup
• Launch services with just run_local --no-doppler for full stack
• Validate setup using just doctor-local before development
• Rebuild aux services with --build-aux-services when Docker images change
• Customize ports and run multiple instances using --port-base and --instance flags

Frequently Asked Questions

What happens if I skip just prepare_db?

The Rust compiler will fail with SQLx validation errors. The prepare_db command generates the offline query metadata in .sqlx/ that allows cargo build to type-check database queries without a live connection. Without it, any schema change breaks compilation.

Can I update Macro without Docker?

No. The just run_local command orchestrates a multi-service stack including Postgres, Redis, OpenSearch, and Kafka via Docker Compose. The repository's architecture depends on containerized infrastructure as defined in infra/local/generated/.

How do I know if I need --build-aux-services?

Check if your git pull modified code in sync_service/, lexical_service/, or websocket_service/. These services build Docker images from source rather than using prebuilt binaries. When in doubt, include the flag—it safely rebuilds only when necessary.

What does just doctor-local actually check?

The command verifies Docker daemon connectivity, port availability in your configured range, environment variable presence, and basic service health endpoints. It prints a diagnostic report and the active frontend URL for quick verification.

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