From 2525023a567165606a1b885aaf60445d876d6363 Mon Sep 17 00:00:00 2001 From: Jarek Potiuk Date: Sat, 28 Feb 2026 21:48:17 +0100 Subject: [PATCH] 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 --- .devcontainer/devcontainer.json | 3 ++ .devcontainer/mysql/devcontainer.json | 3 ++ .devcontainer/postgres/devcontainer.json | 3 ++ ...03a_contributors_quick_start_beginners.rst | 16 +++++++-- .../contributors_quick_start_codespaces.rst | 34 +++++++++++++++++++ .../utils/docker_command_utils.py | 14 +++++++- 6 files changed, 69 insertions(+), 4 deletions(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index f6f28ac2a12..86d5400c149 100644 --- a/.devcontainer/devcontainer.json +++ b/.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" }, diff --git a/.devcontainer/mysql/devcontainer.json b/.devcontainer/mysql/devcontainer.json index 011ff292d27..ef1ef2de1f2 100644 --- a/.devcontainer/mysql/devcontainer.json +++ b/.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" }, diff --git a/.devcontainer/postgres/devcontainer.json b/.devcontainer/postgres/devcontainer.json index 419dbedfa1d..1be456df375 100644 --- a/.devcontainer/postgres/devcontainer.json +++ b/.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" }, diff --git a/contributing-docs/03a_contributors_quick_start_beginners.rst b/contributing-docs/03a_contributors_quick_start_beginners.rst index 0427a7c19c3..6a04887441e 100644 --- a/contributing-docs/03a_contributors_quick_start_beginners.rst +++ b/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. diff --git a/contributing-docs/quick-start-ide/contributors_quick_start_codespaces.rst b/contributing-docs/quick-start-ide/contributors_quick_start_codespaces.rst index 447e6ba4637..cb2b984815d 100644 --- a/contributing-docs/quick-start-ide/contributors_quick_start_codespaces.rst +++ b/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. diff --git a/dev/breeze/src/airflow_breeze/utils/docker_command_utils.py b/dev/breeze/src/airflow_breeze/utils/docker_command_utils.py index 13413108869..fef8b8d597a 100644 --- a/dev/breeze/src/airflow_breeze/utils/docker_command_utils.py +++ b/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)