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

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 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
Just	Task runner installed automatically via Nix shell

Enter the development environment:

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
5. Launches frontend dev server (bun dev) with terminal attachment

Basic command

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 used by run_local.

---

Database Configuration with just

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

# 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 and documented in docs/RUNNING_LOCALLY.md.

---

Complete Workflow Example

Fresh repository setup:

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:

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	Service topology: PostgreSQL, Redis, OpenSearch, Mailpit, FusionAuth, LocalStack
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.

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