# How to Configure Docker Services and Local Development Stack with `just` in Macro

> Configure Docker services and local development stack with the just command. Use just run_local for the full Macro environment or just stack up for Docker services.

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

---

**Use `just run_local` to launch the full Macro development environment, or `just stack up` to run only Docker services.**

The Macro repository uses a **Justfile-based task runner** to orchestrate Docker services and local development. This guide covers how to configure PostgreSQL, Redis, OpenSearch, LocalStack, Mailpit, FusionAuth, and Rust services using the `just` command according to the [macro-inc/macro](https://github.com/macro-inc/macro) source code.

---

## Prerequisites

| Tool | Purpose |
|------|---------|
| **Nix** | Provides reproducible development shell with Rust toolchain, `just`, Docker, Bun, and Biome |
| **Docker Compose** | Spins up containerized services defined in [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) |
| **Just** | Task runner installed automatically via Nix shell |

Enter the development environment:

```bash
nix develop --command bash

```

---

## Starting the Full Local Stack with `just`

The `just run_local` command in `tooling/just/xtask.just` performs five sequential operations:

1. Creates Docker network (if missing)
2. Builds Rust binaries via `cargo zigbuild`
3. Generates temporary `runtime` Docker image mounting fresh binaries
4. Starts Docker Compose topology from [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml)
5. Launches frontend dev server (`bun dev`) with terminal attachment

### Basic command

```bash
just run_local

```

### Common `just run_local` options

| Option | Example | Effect |
|--------|---------|--------|
| `--instance <NAME>` | `just run_local --instance agent-a` | Isolates stack in separate Docker network for parallel testing |
| `--no-doppler` | `just run_local --no-doppler` | Skips Doppler secrets; requires local `.env` file |
| `--env-file <PATH>` | `just run_local --env-file ./local.env` | Loads additional environment variables |
| `--no-frontend` | `just run_local --no-frontend` | Backend services only |
| `--no-build` | `just run_local --no-build` | Reuses existing binaries; skips rebuild |
| `--build-aux-services` | `just run_local --build-aux-services` | Rebuilds auxiliary images like `cloud-storage-cache` |
| `--port-base <N>` | `just run_local --port-base 23000` | Offsets all service ports by N for multiple instances |

---

## Managing Docker Services Directly with `just stack`

For CI pipelines or debugging individual services, use the `just stack` family defined in the root **Justfile**:

| Command | Purpose |
|---------|---------|
| `just stack up` | Starts Compose stack without building Rust binaries |
| `just stack down` | Stops and removes containers, networks, volumes |
| `just stack status` | Shows container status via `docker compose ps` |
| `just stack snapshot` | Captures volume snapshots for preview pipeline reuse |

These commands reference the same [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) used by `run_local`.

---

## Database Configuration with `just`

Prepare PostgreSQL and run migrations using database-specific `just` commands:

```bash

# Generate environment files (with Doppler unless --no-doppler)

just get_environment

# Start PostgreSQL container in detached mode

just run_dbs -d

# Prepare test environments and apply migrations

just setup_test_envs      # creates .env.test

just initialize_dbs       # applies all migrations

```

These utilities are implemented in [`tooling/xtask/crates/xtask_local/src/local/stack.rs`](https://github.com/macro-inc/macro/blob/main/tooling/xtask/crates/xtask_local/src/local/stack.rs) and documented in [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md).

---

## Complete Workflow Example

Fresh repository setup:

```bash
nix develop --command bash

just build-dev              # optional pre-build

just run_dbs -d
just setup_test_envs
just initialize_dbs
just run_local              # full stack with frontend

```

Existing binaries, services only:

```bash
just stack up
just stack status
just stack down             # or Ctrl+C from attached run_local

```

---

## Key Source Files

| File | Contents |
|------|----------|
| `justfile` | Central task definitions: `run_local`, `stack`, `build-dev`, `setup_test_envs` |
| `tooling/just/xtask.just` | Detailed `run_local` recipe with flag handling |
| [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) | Service topology: PostgreSQL, Redis, OpenSearch, Mailpit, FusionAuth, LocalStack |
| [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md) | Human-readable setup guide |
| `tooling/xtask/crates/xtask_local/src/local/` | Rust implementation of just recipes |

---

## Tips for Configuring Docker Services

- **Doppler integration**: With access, secrets inject automatically; without it, define `POSTGRES_PASSWORD`, `OPENSEARCH_PASSWORD` in local `.env`
- **Port conflicts**: Use `--port-base <N>` to run multiple isolated instances
- **Fast iteration**: `just run_local --no-build` skips recompilation when only code changed
- **Auxiliary services**: Cloud storage cache and similar services rebuild with `--build-aux-services`
- **Clean state**: Persistent volumes survive `just stack down`; purge manually or with `--purge` flag

---

## Summary

- **`just run_local`** boots complete development environment: Docker services, Rust backend, and frontend
- **`just stack up/down`** provides direct Docker Compose control for CI and debugging
- **Database prep**: `just get_environment`, `just run_dbs`, `just setup_test_envs`, `just initialize_dbs`
- **Instance isolation**: Use `--instance` and `--port-base` for parallel development
- **All recipes** defined in `justfile` and `tooling/just/xtask.just` with implementation in Rust at `tooling/xtask/crates/xtask_local/src/local/`

---

## Frequently Asked Questions

### What does `just run_local` actually build?

`just run_local` compiles Rust binaries using `cargo zigbuild` for fast cross-compilation, creates a temporary `runtime` Docker image mounting those binaries, starts all Docker Compose services, and launches the Bun-based frontend dev server. The frontend attaches to your terminal; press Ctrl+C to tear down everything.

### How do I run Macro without Doppler secrets?

Pass `--no-doppler` to skip Doppler integration. You must then provide a local `.env` file with required secrets including `POSTGRES_PASSWORD`, `OPENSEARCH_PASSWORD`, and service-specific credentials. Use `--env-file ./local.env` to specify a custom file path.

### Can I run multiple Macro instances on one machine?

Yes. Use `just run_local --instance <NAME> --port-base <OFFSET>` to isolate stacks. Each instance creates separate Docker networks and offsets all service ports by the specified base number, preventing collisions between PostgreSQL, Redis, and other services.