How to Stop the Macro Local Stack: Complete Guide for Clean Shutdown

You can stop the macro local stack by pressing q in the interactive terminal, or by running just stack down from the command line, both of which remove all containers and Docker volumes.

The Macro development environment runs a comprehensive local stack that emulates the full production system including PostgreSQL, Redis, LocalStack, OpenSearch, Kafka, and FusionAuth. When you need to free system resources or ensure a fresh state for your next development session, properly stopping the stack prevents container leaks and stale data issues. This guide covers the exact commands and key combinations defined in the macro-inc/macro repository to shut down the environment cleanly.

Understanding the Macro Local Stack Architecture

The local stack defined in infra/stacks/* orchestrates multiple heavyweight services through Docker Compose. According to the source code in tooling/xtask/crates/xtask_local/src/local/stack.rs, the interactive runner provides a terminal UI that listens for hot-keys to manage container lifecycles. Because the stack creates persistent Docker volumes for databases and caches, a proper shutdown sequence is essential to prevent resource exhaustion on your workstation.

Method 1: Stop the Macro Local Stack Interactively

When you launch the stack using just stack up, the terminal enters an interactive mode with a live dashboard. In this mode, the recommended way to stop the macro local stack is to press q while the terminal window is focused.

This single keypress triggers a complete teardown sequence that:

• Stops all running containers immediately
• Removes the associated Docker volumes in one step
• Frees ports and network interfaces allocated to the stack

Why You Should Avoid Ctrl-C

Using the terminal’s close button or sending Ctrl-C interrupts is explicitly discouraged in docs/RUNNING_LOCALLY.md at line 145. This method leaves containers running in the background and can lead to stale state, port conflicts, and "ghost" volumes on your next start. The documentation states: "Use q, not the terminal close button. q stops and removes the containers at once."

Method 2: Stop the Macro Local Stack from Command Line

If you launched the stack in detached mode or need to stop it from a different terminal window, use the helper command defined in the justfile:

just stack down

As documented at line 255 in docs/RUNNING_LOCALLY.md, this command:

1. Stops all services gracefully
2. Removes the containers
3. Deletes the persistent Docker volumes that the stack created during initialization

This method is particularly useful for CI/CD pipelines and automation scripts where no interactive terminal is available.

Force a Complete Teardown (Optional Cleanup)

In rare cases where you encounter orphaned resources or want to reclaim disk space, you can combine the standard shutdown with Docker pruning commands:

# Stop the stack first

just stack down

# Remove unused containers, networks, and images

docker system prune -f

# Delete any dangling volumes

docker volume prune -f

Use these commands with caution in shared environments, as they affect all stopped containers on your system, not just the Macro stack.

Why Clean Shutdown Matters for the Macro Local Stack

Resource Management

The macro local stack runs several memory-intensive services including PostgreSQL, Redis, and OpenSearch clusters. Leaving these containers running consumes significant RAM and CPU on your workstation, degrading performance of other development tools.

Deterministic Environment State

A fresh start guarantees that each service loads the latest schema migrations and configuration changes. The source recommends using just stack up --build-aux-services only when you need to pick up changed service code; otherwise, a clean stop and start cycle ensures consistent behavior between sessions.

CI/CD Consistency

Automated CI pipelines rely on predictable port availability and empty database states. A lingering stack from a previous run can cause port conflicts or stale test data, leading to flaky tests and false negatives in your build pipeline.

Summary

• Press q in the interactive terminal to stop the macro local stack and remove volumes in one step.
• Run just stack down from any terminal to shut down detached or background stacks cleanly.
• Avoid Ctrl-C or terminal window closing, which leaves containers running and causes stale state.
• Use docker system prune only when you need to force-remove leftover images and volumes.
• The interactive logic resides in tooling/xtask/crates/xtask_local/src/local/stack.rs, while command orchestration is defined in the repository's justfile.

Frequently Asked Questions

What happens if I close the terminal instead of pressing q?

Closing the terminal window or sending Ctrl-C terminates the interactive UI process but leaves the Docker containers running in the background. This creates a "zombie" stack that continues consuming resources and can cause port conflicts when you attempt to start a new instance. Always use the q key to ensure containers and volumes are removed.

Does just stack down delete my data?

Yes. The just stack down command removes the persistent Docker volumes associated with the stack, including PostgreSQL databases, Redis caches, and OpenSearch indices. This is intentional to ensure a clean slate on the next startup. If you need to preserve data between sessions, you must implement external backup strategies before running the command.

How do I restart the macro local stack after stopping it?

After stopping with either q or just stack down, simply run just stack up again to recreate fresh containers and volumes. The stack will reinitialize all services, run migrations, and be ready for development within minutes. If you modified auxiliary service code, use just stack up --build-aux-services to rebuild images before starting.

Where is the interactive stack runner implemented?

The interactive terminal UI that listens for the q hot-key is implemented in tooling/xtask/crates/xtask_local/src/local/stack.rs. This Rust source file handles the keyboard input processing and coordinates the graceful shutdown sequence with the Docker Compose backend defined in the project's orchestration files.

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