diff options
author | Elisey Zanko <elisey.zanko@gmail.com> | 2023-03-30 19:02:46 +0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-03-30 07:02:46 -0700 |
commit | affd839ae837c838cb2de6e4ea4d2a95e29d72a8 (patch) | |
tree | 3bd5415b01cbecb3d6bbb1e61452895f4004076b | |
parent | 610bef5d0c083087686d1f87fd565209954b8f23 (diff) | |
download | tox-git-affd839ae837c838cb2de6e4ea4d2a95e29d72a8.tar.gz |
Document running tox within a Docker container (#2923)
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
-rw-r--r-- | docs/changelog/1035.doc.rst | 1 | ||||
-rw-r--r-- | docs/faq.rst | 42 |
2 files changed, 43 insertions, 0 deletions
diff --git a/docs/changelog/1035.doc.rst b/docs/changelog/1035.doc.rst new file mode 100644 index 00000000..b5f1b9db --- /dev/null +++ b/docs/changelog/1035.doc.rst @@ -0,0 +1 @@ +Document running tox within a Docker container. diff --git a/docs/faq.rst b/docs/faq.rst index 769c74a2..3698f854 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -306,3 +306,45 @@ Access full logs If you want to access the full logs you need to write ``-q`` and ``-v`` as individual tox arguments and avoid combining them into a single one. + +Running within a Docker container +--------------------------------- + +If you want to run tox within a Docker container you can use `31z4/tox <https://hub.docker.com/r/31z4/tox>`_. +This Docker image neatly packages tox along with common build dependencies (e.g., ``make``, ``gcc``, etc) and currently +`active CPython versions <https://devguide.python.org/versions/#status-of-python-versions>`_. See more details in +its `GitHub repository <https://github.com/31z4/tox-docker>`_. + +The recommended way of using the image is to mount the directory that contains your tox configuration files and your +code as a volume. Assuming your project is within the current directory of the host, use the following command to run +tox without any flags: + +.. code-block:: shell + + docker run -v `pwd`:/home/tox/tests -it --rm 31z4/tox + +Because an entry point of the image is ``tox``, you can easily pass subcommands and flags: + +.. code-block:: shell + + docker run -v `pwd`:/home/tox/tests -it --rm 31z4/tox run-parallel -e black,py311 + +Note, that the image is configured with a working directory at ``/home/tox/tests``. + +If you want to install additional Python versions/implementations or Ubuntu packages you can create a derivative image. +Just make sure you switch the user to ``root`` when needed and switch back to ``tox`` afterwards: + +.. code-block:: Dockerfile + + FROM 31z4/tox + + USER root + + RUN set -eux; \ + apt-get update; \ + DEBIAN_FRONTEND=noninteractive \ + apt-get install -y --no-install-recommends \ + python3.12; \ + rm -rf /var/lib/apt/lists/* + + USER tox |