===============
Docker Workflow
===============

The Dawn container provides an Ubuntu-based toolchain environment for building
and testing Dawn without installing the full host toolchain directly.

Build the image from the Dawn repository root::

  docker build -f tools/docker/ubuntu-container.Dockerfile \
    -t dawn-container \
    tools/docker

The image build installs the host toolchain, Docker QA entrypoint, and helper
scripts only. Dawn source checkout, ``repo_init.sh``, ``.venv`` creation,
editable Python package installation, and QA builds happen when the container
starts.

Full QA Suite
=============

Build the image first, then run the complete ``dawnpy-tests`` QA flow through
the protected wrapper::

  tools/docker/run-qa.sh

By default, this clones ``DAWN_REPO`` at ``DAWN_REF`` inside the container and
runs ``repo_init.sh`` there. To test the current host checkout instead, use
local source mode::

  tools/docker/run-qa.sh --local

Local source mode bind-mounts the host checkout read-only, copies it into an
in-container workspace, runs ``repo_init.sh``, creates the virtual environment,
installs the required local Python tooling from that copy, and runs QA there.
This keeps the host checkout isolated from root-owned build artifacts while
still testing local Dawn sources.

The wrapper refuses to start if Docker storage accounting is unhealthy, because
that state can leave stale container layers behind. It then runs the QA
container with bounded resources:

* ``DAWN_DOCKER_CPUS`` defaults to ``4``.
* ``DAWN_DOCKER_MEMORY`` defaults to ``8g`` and is also used for
  ``--memory-swap``.
* ``DAWN_DOCKER_QA_JOBS`` defaults to ``2``.
* Docker local log rotation defaults to ``20m`` x ``2``.
* the PID limit defaults to ``4096``.

The QA container uses ``--privileged`` because the integration tests create
kernel-backed network devices. The in-container entrypoint creates
``/dev/net/tun`` before running ``testenv_init.sh start``, so no manual host
``/dev/net/tun`` setup is required.

Pass additional ``dawnpy-tests`` arguments after the wrapper name, for example::

  tools/docker/run-qa.sh --jobs 1

Select upstream/image source explicitly::

  tools/docker/run-qa.sh --image

Select a different local checkout::

  DAWN_DOCKER_LOCAL_SOURCE=/path/to/dawn tools/docker/run-qa.sh --local

The same selection is available through ``DAWN_DOCKER_SOURCE=image`` or
``DAWN_DOCKER_SOURCE=local``.

Runtime Source Selection
========================

``DAWN_REPO``
  Git repository URL to clone in upstream/image mode. Defaults to
  ``https://github.com/railab/dawn.git``.

``DAWN_REF``
  Branch, tag, or commit to check out after cloning. Defaults to ``master``.

``NUTTX_BRANCH``
  Branch to use for both NuttX repositories during ``repo_init.sh``. Defaults
  to ``dawn``.

Example using an explicit ref::

  DAWN_REF=master tools/docker/run-qa.sh --image

Example using an explicit NuttX branch::

  NUTTX_BRANCH=dawn tools/docker/run-qa.sh --image

Publishing
==========

The ``Docker image`` GitHub Actions workflow publishes the Dawn container to
GitHub Container Registry as::

  ghcr.io/<owner>/<repo>/dawn-container

The workflow:

* builds on pull requests that touch Docker files, without publishing;
* publishes automatically on pushes to ``main`` or ``master`` that touch
  ``tools/docker/**`` or the workflow itself;
* can be started manually from the Actions tab.

Notes
=====

The Docker QA path is intended for simulator and virtual integration coverage.
Physical hardware access still depends on host device availability and explicit
Docker device permissions.