DEVX-20: feat: extract Docker daemon start to tested Python module

src/devx/molecule/start_docker.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Start a Docker daemon inside a CI runner container (Docker-in-Docker).
+
+CI runners (e.g. ``gitea/runner-images:ubuntu-latest``) may not have a
+Docker daemon running. This module starts ``dockerd`` in the background
+and waits for it to become ready, or exits immediately if Docker is
+already available.
+
+Usage::
+
+    python3 -m devx.molecule.start_docker [--timeout 30]
+"""
+
+from __future__ import annotations
+
+import subprocess  # nosec B404
+import sys
+import time
+
+import click
+
+from devx.i18n import _
+
+DEFAULT_TIMEOUT = 30
+DOCKERD_LOG = "/var/log/dockerd.log"
+
+
+def is_docker_ready() -> bool:
+    """Check if the Docker daemon is responding."""
+    result = subprocess.run(  # nosec B603 B607
+        ["docker", "info"],
+        capture_output=True,
+        check=False,
+    )
+    return result.returncode == 0
+
+
+def start_docker_daemon(timeout: int = DEFAULT_TIMEOUT) -> bool:
+    """Start dockerd in the background and wait for it to be ready.
+
+    Returns ``True`` if Docker is ready (either already running or
+    successfully started), ``False`` if it failed to start within
+    the timeout.
+    """
+    if is_docker_ready():
+        click.echo(_("Docker daemon already running"))
+        return True
+
+    click.echo(_("Starting Docker daemon..."))
+    log_file = open(DOCKERD_LOG, "w")  # noqa: SIM115
+    subprocess.Popen(  # nosec B603 B607
+        ["dockerd"],
+        stdout=log_file,
+        stderr=subprocess.STDOUT,
+        start_new_session=True,
+    )
+
+    for _i in range(timeout):
+        if is_docker_ready():
+            click.echo(_("Docker daemon started"))
+            return True
+        time.sleep(1)
+
+    click.echo(_("Docker daemon failed to start"))
+    return False
+
+
+@click.command()
+@click.option(
+    "--timeout",
+    default=DEFAULT_TIMEOUT,
+    type=int,
+    help="Seconds to wait for Docker daemon to start (default: 30).",
+)
+def main(timeout: int) -> None:
+    """Start Docker daemon for CI molecule tests."""
+    if start_docker_daemon(timeout):
+        sys.exit(0)
+    sys.exit(1)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()