This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 2361e174202 Clarify how to stop Breeze environments (#70560)
2361e174202 is described below
commit 2361e174202c69be04dc0cdc88388ea8581edbd6
Author: Andrew Chang <[email protected]>
AuthorDate: Tue Jul 28 05:01:15 2026 +0800
Clarify how to stop Breeze environments (#70560)
The default mprocs workflow does not expose stop_airflow, while the
existing instructions directed every start-airflow user to it. This could leave
the foreground container holding forwarded ports and Docker resources during
cleanup.
---
contributing-docs/03_contributors_quick_start.rst | 16 +++++++++++++---
contributing-docs/mprocs/MPROCS_QUICK_REFERENCE.md | 8 ++++++++
dev/breeze/doc/03_developer_tasks.rst | 17 ++++++++++++-----
3 files changed, 33 insertions(+), 8 deletions(-)
diff --git a/contributing-docs/03_contributors_quick_start.rst
b/contributing-docs/03_contributors_quick_start.rst
index 4212a85abe6..9f3e2cc7a56 100644
--- a/contributing-docs/03_contributors_quick_start.rst
+++ b/contributing-docs/03_contributors_quick_start.rst
@@ -629,13 +629,22 @@ Using Breeze
alt="Connecting to postgresql">
</div>
-4. Stopping breeze
+4. Stopping Breeze
-If ``breeze`` was started with ``breeze start-airflow``, this command will
stop breeze and Airflow:
+If Breeze was started with ``breeze start-airflow``, first exit the terminal
multiplexer so that the
+Breeze container stops and releases its forwarded ports:
+
+* With mprocs (the default), press ``q`` in the mprocs interface.
+* With tmux, run ``stop_airflow`` from the main shell pane:
.. code-block:: bash
[Breeze:3.10.19] root@f3619b74c59a:/opt/airflow# stop_airflow
+
+After returning to the host shell, stop the remaining Docker Compose services:
+
+.. code-block:: bash
+
breeze down
If ``breeze`` was started with ``breeze --python 3.10 --backend postgres`` (or
similar):
@@ -646,7 +655,8 @@ If ``breeze`` was started with ``breeze --python 3.10
--backend postgres`` (or s
breeze down
.. note::
- ``stop_airflow`` is available only when ``breeze`` is started with
``breeze start-airflow``.
+ ``stop_airflow`` is available only when ``breeze start-airflow`` uses
tmux. Use ``q`` to quit
+ the default mprocs interface.
Using tmux Instead of mprocs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/contributing-docs/mprocs/MPROCS_QUICK_REFERENCE.md
b/contributing-docs/mprocs/MPROCS_QUICK_REFERENCE.md
index 7ad569de524..416fed3b482 100644
--- a/contributing-docs/mprocs/MPROCS_QUICK_REFERENCE.md
+++ b/contributing-docs/mprocs/MPROCS_QUICK_REFERENCE.md
@@ -70,6 +70,14 @@ use it outside of Breeze if needed.
| `q` | Quit mprocs |
| `?` | Show help |
+When stopping the Breeze environment, press `q` rather than stopping only the
+selected process. Quitting mprocs lets the `breeze start-airflow` container
exit
+and release its forwarded ports. After returning to the host shell, run:
+
+```bash
+breeze down
+```
+
## Components Managed
- **scheduler** - Airflow scheduler
diff --git a/dev/breeze/doc/03_developer_tasks.rst
b/dev/breeze/doc/03_developer_tasks.rst
index cc951edb1f2..0db727c7e65 100644
--- a/dev/breeze/doc/03_developer_tasks.rst
+++ b/dev/breeze/doc/03_developer_tasks.rst
@@ -685,10 +685,16 @@ Make sure to substitute the port numbers if you have
customized them via the abo
Stopping the environment
------------------------
-After starting up, the environment runs in the background and takes quite some
memory which you might
-want to free for other things you are running on your host.
+After starting up, the environment takes quite some memory which you might
want to free for other things
+you are running on your host.
-You can always stop it via:
+If you used ``breeze start-airflow``, first exit its terminal multiplexer so
that the foreground
+container releases its forwarded ports:
+
+* With mprocs (the default), press ``q`` in the mprocs interface.
+* With tmux, run ``stop_airflow`` from its main shell pane.
+
+After returning to the host shell, stop the remaining Docker Compose services:
.. code-block:: bash
@@ -699,8 +705,9 @@ about — ``breeze shell``, ``breeze testing``, ``breeze
build-docs``, ``breeze
release-management, registry, ``breeze run``, and prek-hook compose projects —
by
reading the ``com.docker.compose.project`` label that compose sets on every
container
it creates. Each matching project is brought down with ``--remove-orphans`` and
-``--volumes`` (unless ``--preserve-volumes`` is passed). One ``breeze down`` is
-enough to leave the host clean.
+``--volumes`` (unless ``--preserve-volumes`` is passed). A running
+``breeze start-airflow`` container must exit first; otherwise it continues to
use
+the project's forwarded ports, network, and volumes.
If you have an unrelated docker compose project running on the host that does
not
match any breeze prefix, it is left alone by default. Pass ``--all-projects``
to
