# How to Stop the Macro Local Stack: Complete Guide for Clean Shutdown > Easily stop the macro local stack by pressing q in the terminal or running just stack down. This guide provides a complete walkthrough for a clean shutdown. - Repository: [Macro/macro](https://github.com/macro-inc/macro) - Tags: how-to-guide - Published: 2026-08-21 --- **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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`: ```bash just stack down ``` As documented at line 255 in [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/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: ```bash # 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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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.