This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch v3-3-test
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/v3-3-test by this push:
new 7fe5b439ed0 [v3-3-test] Document Colima and DOCKER_HOST setup for
Breeze contributors (#72431) (#72665)
7fe5b439ed0 is described below
commit 7fe5b439ed0e59440377de573ada4b1f931a7c1d
Author: github-actions[bot]
<41898282+github-actions[bot]@users.noreply.github.com>
AuthorDate: Tue Sep 8 11:53:23 2026 +0200
[v3-3-test] Document Colima and DOCKER_HOST setup for Breeze contributors
(#72431) (#72665)
The old Colima guidance symlinked into /var/run/docker.sock, which
conflicts with Docker Desktop. Contributors hitting stale desktop-linux
contexts need DOCKER_HOST / --docker-host instead.
(cherry picked from commit 10d9349bccc506a1d5ddff6f5de0b61c27ae435a)
Co-authored-by: SreeCharan Desu <[email protected]>
Co-authored-by: Rahul Vats <[email protected]>
---
contributing-docs/03_contributors_quick_start.rst | 21 +++++++++++++++------
dev/breeze/doc/01_installation.rst | 21 ++++++++++++++++-----
dev/breeze/doc/03_developer_tasks.rst | 6 +++++-
3 files changed, 36 insertions(+), 12 deletions(-)
diff --git a/contributing-docs/03_contributors_quick_start.rst
b/contributing-docs/03_contributors_quick_start.rst
index 33c2824cc4f..907133da734 100644
--- a/contributing-docs/03_contributors_quick_start.rst
+++ b/contributing-docs/03_contributors_quick_start.rst
@@ -113,21 +113,30 @@ Docker Community Edition
Colima
------
-If you use Colima as your container runtimes engine, please follow the next
steps:
+If you use Colima as your container runtime, prefer Docker contexts /
``DOCKER_HOST`` over
+symlinking sockets into ``/var/run`` (that can break Docker Desktop or other
engines).
-1. `Install buildx manually
<https://github.com/docker/buildx#manual-download>`_ and follow its instructions
+1. `Install buildx manually
<https://github.com/docker/buildx#manual-download>`_ if your
+ Colima install does not already provide it, and follow its instructions.
-2. Link the Colima socket to the default socket path. Note that this may break
other Docker servers
+2. Start Colima and select its Docker context (Colima creates a ``colima``
context for the
+ default profile):
.. code-block:: bash
- sudo ln -sf $HOME/.colima/default/docker.sock /var/run/docker.sock
+ colima start
+ docker context use colima
+ docker info
-3. Change docker context to use default
+3. Optionally set ``DOCKER_HOST`` (or pass ``breeze --docker-host``) so tools
pick Colima
+ even when another context is current:
.. code-block:: bash
- docker context use default
+ export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock
+
+If you previously symlinked Colima into ``/var/run/docker.sock``, remove that
symlink when
+you switch back to Docker Desktop or another engine.
Docker Compose
--------------
diff --git a/dev/breeze/doc/01_installation.rst
b/dev/breeze/doc/01_installation.rst
index eb337d29aa4..cc565e4b819 100644
--- a/dev/breeze/doc/01_installation.rst
+++ b/dev/breeze/doc/01_installation.rst
@@ -41,11 +41,22 @@ Docker Desktop
a problem with Docker. If you see a weird behaviour, try ``breeze cleanup``
command.
Also see `pruning <https://docs.docker.com/config/pruning/>`_ instructions
from Docker.
- **Docker context**: Recent versions of Docker Desktop are by default
configured to use ``desktop-linux``
- docker context that uses docker socket created in user home directory. Older
versions (and plain docker)
- uses ``/var/run/docker.sock`` socket and ``default`` context. Breeze will
attempt to detect if you have
- ``desktop-linux`` context configured and will use it if it is available, but
you can force the
- context by adding ``--builder`` flag to the commands that build image or run
the container and forward
- the socket to inside the image.
+ docker context that uses a docker socket created in the user home directory.
Older versions (and plain
+ Docker Engine) use ``/var/run/docker.sock`` and the ``default`` context.
Lightweight engines such as
+ Colima create a ``colima`` context. Breeze tries to pick a suitable context
automatically, but a leftover
+ ``desktop-linux`` context after quitting Docker Desktop can still win even
when Colima is the running
+ engine.
+
+ To point Breeze at a specific Docker socket (for example Colima), set
``DOCKER_HOST`` or pass
+ ``--docker-host``::
+
+ export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock
+ # or:
+ breeze --docker-host unix://$HOME/.colima/default/docker.sock shell
+
+ The ``--builder`` flag selects the Buildx builder / docker context name used
for
+ ``docker buildx build``. Prefer ``--docker-host`` / ``DOCKER_HOST`` when you
only need to choose
+ which engine socket to talk to.
Here is an example configuration with more than 200GB disk space for Docker:
diff --git a/dev/breeze/doc/03_developer_tasks.rst
b/dev/breeze/doc/03_developer_tasks.rst
index 0db727c7e65..8a9b4459848 100644
--- a/dev/breeze/doc/03_developer_tasks.rst
+++ b/dev/breeze/doc/03_developer_tasks.rst
@@ -51,10 +51,14 @@ as follows:
protocol not available
Error 1 returned
-Try adding ``--builder=default`` to your command. For example:
+If autodetection picked a stale Docker Desktop context, point Breeze at a
working socket
+with ``--docker-host`` (or set ``DOCKER_HOST``), or force a known context /
Buildx builder
+with ``--builder``. For example:
.. code-block:: bash
+ breeze --docker-host unix://$HOME/.colima/default/docker.sock --python
3.10 --backend mysql --mysql-version 8.0
+ # or:
breeze --builder=default --python 3.10 --backend mysql --mysql-version 8.0
The choices you make are persisted in the ``./.build/`` cache directory so
that next time when you use the
