Fix "Docker is not running" error guidance for GitHub Codespaces (#62580)

When running Breeze in a GitHub Codespace, the generic "Docker is not
running" error gave no Codespace-specific troubleshooting hints. This
change:

- Adds feature in devcontainers to enable docker-in-docker
- Shows Docker's stderr output when `docker info` fails (previously
  suppressed) so users can see the actual error.
- Detects the CODESPACES environment variable and prints targeted
  troubleshooting steps (check socket, permissions, rebuild container).
- Adds a Docker verification step to the beginner quick-start guide.
- Adds a troubleshooting section to the Codespaces setup guide.

Closes: #62405

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

.devcontainer/devcontainer.json

@@ -4,6 +4,9 @@
         "../scripts/ci/docker-compose/devcontainer.yml",
         "../scripts/ci/docker-compose/devcontainer-sqlite.yml"
     ],
+    "features": {
+        "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {}
+    },
     "settings": {
         "terminal.integrated.defaultProfile.linux": "bash"
     },

.devcontainer/mysql/devcontainer.json

@@ -5,6 +5,9 @@
         "../../scripts/ci/docker-compose/backend-mysql.yml",
         "../../scripts/ci/docker-compose/devcontainer-mysql.yml"
     ],
+    "features": {
+        "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {}
+    },
     "settings": {
         "terminal.integrated.defaultProfile.linux": "bash"
     },

.devcontainer/postgres/devcontainer.json

@@ -5,6 +5,9 @@
         "../../scripts/ci/docker-compose/backend-postgres.yml",
         "../../scripts/ci/docker-compose/devcontainer-postgres.yml"
     ],
+    "features": {
+        "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {}
+    },
     "settings": {
         "terminal.integrated.defaultProfile.linux": "bash"
     },

contributing-docs/03a_contributors_quick_start_beginners.rst

@@ -148,7 +148,17 @@ Option B – One-Click GitHub Codespaces
     chmod +x ~/.docker/cli-plugins/docker-compose
     docker compose version
 
-4. Install Breeze and start the development container
+4. Verify Docker is accessible
+
+.. code-block:: bash
+
+      docker info
+
+   If ``docker info`` fails, try rebuilding the Codespace container
+   (Command Palette → *Codespaces: Rebuild Container*) or restarting
+   the Codespace from the GitHub Codespaces dashboard.
+
+5. Install Breeze and start the development container
 
 .. code-block:: bash
 
@@ -160,10 +170,10 @@ Option B – One-Click GitHub Codespaces
       uv run dev/ide_setup/setup_vscode.py
       breeze start-airflow
 
-5. Edit a file in the editor, save, and commit via the Source Control sidebar.
+6. Edit a file in the editor, save, and commit via the Source Control sidebar.
    Push when prompted.
 
-6. Press **Create pull request** when GitHub offers.
+7. Press **Create pull request** when GitHub offers.
 
 
 

contributing-docs/quick-start-ide/contributors_quick_start_codespaces.rst

@@ -46,4 +46,38 @@ Setup and develop using GitHub Codespaces
    as Codespaces use Visual Studio Code as interface.
 
 
+Troubleshooting Docker in Codespaces
+-------------------------------------
+
+If you see a "Docker is not running" error when running Breeze commands, try these steps:
+
+1. Verify that Docker is accessible by running:
+
+   .. code-block:: bash
+
+      docker info
+
+2. If the command fails, check that the Docker socket exists:
+
+   .. code-block:: bash
+
+      ls -la /var/run/docker.sock
+
+3. Check that your user has permission to access Docker:
+
+   .. code-block:: bash
+
+      groups $USER
+
+   You should see ``docker`` in the list. If not, add yourself to the group:
+
+   .. code-block:: bash
+
+      sudo usermod -aG docker $USER
+
+4. If the above steps do not help, rebuild the devcontainer
+   (Command Palette → *Codespaces: Rebuild Container*) or restart the Codespace
+   from the GitHub Codespaces dashboard.
+
+
 Follow the `Quick start <../03b_contributors_quick_start_seasoned_developers.rst>`_ for typical development tasks.

dev/breeze/src/airflow_breeze/utils/docker_command_utils.py

@@ -175,7 +175,7 @@ def check_docker_is_running():
     response = run_command(
         ["docker", "info"],
         no_output_dump_on_exception=True,
-        text=False,
+        text=True,
         capture_output=True,
         check=False,
     )
@@ -183,6 +183,18 @@ def check_docker_is_running():
         get_console().print(
             "[error]Docker is not running.[/]\n[warning]Please make sure Docker is installed and running.[/]"
         )
+        if response.stderr:
+            get_console().print(f"\n[warning]Docker error output:[/]\n{response.stderr.strip()}")
+        if os.environ.get("CODESPACES", "").lower() == "true":
+            get_console().print(
+                "\n[info]It looks like you are running in a GitHub Codespace.[/]\n"
+                "[info]Try the following troubleshooting steps:[/]\n"
+                "  1. Check if the Docker socket exists: ls -la /var/run/docker.sock\n"
+                "  2. Check Docker socket permissions: groups $USER\n"
+                "  3. Try restarting the Codespace from the GitHub Codespaces dashboard\n"
+                "  4. If the issue persists, rebuild the devcontainer "
+                "(Command Palette -> 'Codespaces: Rebuild Container')\n"
+            )
         sys.exit(1)