From c7d511277163726434e08725b250cddb38c5c660 Mon Sep 17 00:00:00 2001 From: Jim Mussared Date: Tue, 1 Aug 2023 11:18:25 +1000 Subject: [PATCH] idf-docker-image.rst: Run with current user ID instead of root. Rather than running the command inside the container as root, which will mean that any build artifacts created will be owned by root on the host, run the command as the current user. This requires setting a temporary home directory as idf.py will try to access e.g. ~/.cache, so just use /tmp inside the container which is ephemeral anyway. This also allows the command to use `git`. without setting the user ID, `docker run ... git status` will fail with fatal: detected dubious ownership in repository at '/project' Also added the missing explanation for `-w /project`. Signed-off-by: Jim Mussared --- docs/en/api-guides/tools/idf-docker-image.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/en/api-guides/tools/idf-docker-image.rst b/docs/en/api-guides/tools/idf-docker-image.rst index 1b7cf9b6ba..356b6b7aa5 100644 --- a/docs/en/api-guides/tools/idf-docker-image.rst +++ b/docs/en/api-guides/tools/idf-docker-image.rst @@ -53,13 +53,16 @@ In the project directory, run: .. code-block:: bash - docker run --rm -v $PWD:/project -w /project espressif/idf idf.py build + docker run --rm -v $PWD:/project -w /project -u $UID -e HOME=/tmp espressif/idf idf.py build The above command explained: - ``docker run``: runs a Docker image. It is a shorter form of the command ``docker container run``. - ``--rm``: removes the container when the build is finished. - ``-v $PWD:/project``: mounts the current directory on the host (``$PWD``) as ``/project`` directory in the container. +- ``-w /project``: makes ``/project`` the working directory for the command. +- ``-u $UID``: makes the command run with your user ID so that files are created as you (instead of root). +- ``-e HOME=/tmp``: gives the user a home directory for storing temporary files created ``by idf.py`` in ``~/.cache``. - ``espressif/idf``: uses Docker image ``espressif/idf`` with tag ``latest``. The ``latest`` tag is implicitly added by Docker when no tag is specified. - ``idf.py build``: runs this command inside the container. @@ -67,7 +70,7 @@ To build with a specific Docker image tag, specify it as ``espressif/idf:TAG``, .. code-block:: bash - docker run --rm -v $PWD:/project -w /project espressif/idf:release-v4.4 idf.py build + docker run --rm -v $PWD:/project -w /project -u $UID -e HOME=/tmp espressif/idf:release-v4.4 idf.py build You can check the up-to-date list of available tags at https://hub.docker.com/r/espressif/idf/tags. @@ -78,7 +81,7 @@ It is also possible to do builds interactively, to debug build issues or test th .. code-block:: bash - docker run --rm -v $PWD:/project -w /project -it espressif/idf + docker run --rm -v $PWD:/project -w /project -u $UID -e HOME=/tmp -it espressif/idf Then inside the container, use ``idf.py`` as usual: