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

> Update Macro to the latest version by syncing source code, SQLx cache, migrations, and Docker services. Follow this complete step-by-step guide.

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

---

**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`](https://github.com/macro-inc/macro/blob/main/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.

```bash
git pull origin main

```

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

```bash
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.

```bash
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.

```bash
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.

```bash

# 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`:

```bash
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.

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

```

The `justfile` defines multiple seed scenarios; [`team-perms.json`](https://github.com/macro-inc/macro/blob/main/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.

```bash
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:

```bash
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:

```bash
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`](https://github.com/macro-inc/macro/blob/main/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.