Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document running tox within a Docker container #2923

Merged
merged 2 commits into from
Mar 30, 2023
Merged

Document running tox within a Docker container #2923

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0f7fe1d
Document running tox within a Docker container
31z4 Feb 10, 2023
bac90ca
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Feb 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/changelog/1035.doc.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Document running tox within a Docker container.
42 changes: 42 additions & 0 deletions docs/faq.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would prefer to mount the project under the /w folder, personal preference 😅

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's possible too ☺️ But you have to specify the workdir in that case (-w /w):

docker run -v `pwd`:/w -w /w -it --rm 31z4/tox run-parallel -e black,py311

I can change image workdir from /home/tox/tests to something more concise, like /tests maybe. I agree that /home/tox/tests might be too long to type 😅

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd make/w the default, concise better 😅

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@31z4 ping on this?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've been pretty busy recently. Hopefully will get a chance to work on the official image later this month. In the meantime https://github.com/31z4/tox-docker should be good enough for production already.


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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we create a tox-dev or tox org instead to host under? You can be one of it's owner's 😊

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes I think it makes sense. Although, if we aim to make the image "official" maybe it's better to work towards this right now. This way we can save some maintenance efforts. Because we don't have to deprecate tox-dev/tox in favour of official tox. And also users don't have to migrate from the deprecated image to the official one.

Some benefits of an official image that I'd like to highlight:

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah let's make it so. What do you need from me to get there?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess nothing at this point. I'll make some usability changes to the image to conform with https://github.com/docker-library/official-images#consistency. And then will work on PRs to https://github.com/docker-library/official-images and https://github.com/docker-library/docs.


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