nealrichardson commented on a change in pull request #7021: URL: https://github.com/apache/arrow/pull/7021#discussion_r419722389
########## File path: docs/source/developers/docker.rst ########## @@ -0,0 +1,224 @@ +.. raw:: html + + <!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> + +Running Docker Builds +===================== + +Most of our Linux based continuous integration tasks are decoupled from public +CI services using docker and docker-compose. Keeping the CI configuration +minimal makes local reproducibility possible. + +Usage +----- + +There are multiple ways to execute the docker based builds. The recommended is +to use the archery tool: + +Installation +~~~~~~~~~~~~ + +``archery`` requires ``python>=3.5``. It is recommended to install archery in +``editable`` mode with the ``-e`` flag to automatically update the intallation +by pulling the arrow repository. + +.. code:: bash + + pip install -e dev/archery[docker] + +For the available commands and options invoke the installed archery commands +with the ``--help`` flag: + +.. code:: bash + + archery docker --help + archery docker run --help + + +Examples +~~~~~~~~ + +**List the available images:** + +.. code:: bash + + archery docker images + +**Execute a build:** + +.. code:: bash + + archery docker run conda-python + +Archery calls the following docker-compose commands: + +.. code:: bash + + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose run --rm conda-python + +**Show the docker-compose commands instead of executing them:** + +.. code:: bash + + archery docker run --dry-run conda-python + +**To disable the image pulling:** + +.. code:: bash + + archery docker run --no-cache conda-python + +Which translates to: + +.. code:: bash + + docker-compose build --no-cache conda-cpp + docker-compose build --no-cache conda-python + docker-compose run --rm conda-python + +**To disable the cache only for the leaf image:** + +Useful to force building the development version of a dependency. +In case of the example below the command builds the +``conda-cpp > conda-python > conda-python-pandas`` branch of the image tree +where the leaf image is ``conda-python-pandas``. + +.. code:: bash + + PANDAS=master archery docker run --no-cache-leaf conda-python-pandas + +Which translates to: + +.. code:: bash + + export PANDAS=master + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose build --no-cache conda-python-pandas + docker-compose run --rm conda-python-pandas + +Note that it doesn't pull the conda-python-pandas image and disable the cache +when building it. + +``PANDAS`` is a `build parameter <Docker Build Parameters>`_, see the +defaults in the .env file. + +**To entirely skip building the image:** + +The layer caching mechanism of docker-compose is less reliable than docker's +depending on the version, ``cache_from`` build entry and the used backend +(docker-py, docker-cli, docker-cli and buildkit). This can lead to different +layer hashes - even when executing the same build command repeatedly - +eventually causing cache misses full image rebuilds. + +If the image has been already built but the cache doesn't work properly, it can +be useful to skip the build phases: + +.. code:: bash + + archery docker run --no-build conda-python + +**Pass environment variables to the container:** + +Most of the build scripts used within the containers can be configured through +environment variables. Pass them using ``--env`` or ``-e`` CLI options - +similarly to ``docker run`` and ``docker-compose run`` interface. Review comment: ```suggestion similar to the ``docker run`` and ``docker-compose run`` interface. ``` ########## File path: docs/source/developers/docker.rst ########## @@ -0,0 +1,224 @@ +.. raw:: html + + <!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> + +Running Docker Builds +===================== + +Most of our Linux based continuous integration tasks are decoupled from public +CI services using docker and docker-compose. Keeping the CI configuration +minimal makes local reproducibility possible. + +Usage +----- + +There are multiple ways to execute the docker based builds. The recommended is +to use the archery tool: + +Installation +~~~~~~~~~~~~ + +``archery`` requires ``python>=3.5``. It is recommended to install archery in +``editable`` mode with the ``-e`` flag to automatically update the intallation +by pulling the arrow repository. + +.. code:: bash + + pip install -e dev/archery[docker] + +For the available commands and options invoke the installed archery commands +with the ``--help`` flag: + +.. code:: bash + + archery docker --help + archery docker run --help + + +Examples +~~~~~~~~ + +**List the available images:** + +.. code:: bash + + archery docker images + +**Execute a build:** + +.. code:: bash + + archery docker run conda-python + +Archery calls the following docker-compose commands: + +.. code:: bash + + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose run --rm conda-python + +**Show the docker-compose commands instead of executing them:** + +.. code:: bash + + archery docker run --dry-run conda-python + +**To disable the image pulling:** + +.. code:: bash + + archery docker run --no-cache conda-python + +Which translates to: + +.. code:: bash + + docker-compose build --no-cache conda-cpp + docker-compose build --no-cache conda-python + docker-compose run --rm conda-python + +**To disable the cache only for the leaf image:** + +Useful to force building the development version of a dependency. +In case of the example below the command builds the +``conda-cpp > conda-python > conda-python-pandas`` branch of the image tree +where the leaf image is ``conda-python-pandas``. + +.. code:: bash + + PANDAS=master archery docker run --no-cache-leaf conda-python-pandas + +Which translates to: + +.. code:: bash + + export PANDAS=master + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose build --no-cache conda-python-pandas + docker-compose run --rm conda-python-pandas + +Note that it doesn't pull the conda-python-pandas image and disable the cache +when building it. + +``PANDAS`` is a `build parameter <Docker Build Parameters>`_, see the +defaults in the .env file. + +**To entirely skip building the image:** + +The layer caching mechanism of docker-compose is less reliable than docker's +depending on the version, ``cache_from`` build entry and the used backend Review comment: ```suggestion The layer-caching mechanism of docker-compose can be less reliable than docker's, depending on the version, the ``cache_from`` build entry, and the backend used ``` ########## File path: docs/source/developers/docker.rst ########## @@ -0,0 +1,224 @@ +.. raw:: html + + <!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> + +Running Docker Builds +===================== + +Most of our Linux based continuous integration tasks are decoupled from public +CI services using docker and docker-compose. Keeping the CI configuration +minimal makes local reproducibility possible. + +Usage +----- + +There are multiple ways to execute the docker based builds. The recommended is +to use the archery tool: + +Installation +~~~~~~~~~~~~ + +``archery`` requires ``python>=3.5``. It is recommended to install archery in +``editable`` mode with the ``-e`` flag to automatically update the intallation +by pulling the arrow repository. + +.. code:: bash + + pip install -e dev/archery[docker] + +For the available commands and options invoke the installed archery commands +with the ``--help`` flag: + +.. code:: bash + + archery docker --help + archery docker run --help + + +Examples +~~~~~~~~ + +**List the available images:** + +.. code:: bash + + archery docker images + +**Execute a build:** + +.. code:: bash + + archery docker run conda-python + +Archery calls the following docker-compose commands: + +.. code:: bash + + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose run --rm conda-python + +**Show the docker-compose commands instead of executing them:** + +.. code:: bash + + archery docker run --dry-run conda-python + +**To disable the image pulling:** + +.. code:: bash + + archery docker run --no-cache conda-python + +Which translates to: + +.. code:: bash + + docker-compose build --no-cache conda-cpp + docker-compose build --no-cache conda-python + docker-compose run --rm conda-python + +**To disable the cache only for the leaf image:** + +Useful to force building the development version of a dependency. +In case of the example below the command builds the +``conda-cpp > conda-python > conda-python-pandas`` branch of the image tree +where the leaf image is ``conda-python-pandas``. + +.. code:: bash + + PANDAS=master archery docker run --no-cache-leaf conda-python-pandas + +Which translates to: + +.. code:: bash + + export PANDAS=master + docker-compose pull --ignore-pull-failures conda-cpp + docker-compose build conda-cpp + docker-compose pull --ignore-pull-failures conda-python + docker-compose build conda-python + docker-compose build --no-cache conda-python-pandas + docker-compose run --rm conda-python-pandas + +Note that it doesn't pull the conda-python-pandas image and disable the cache +when building it. + +``PANDAS`` is a `build parameter <Docker Build Parameters>`_, see the +defaults in the .env file. + +**To entirely skip building the image:** + +The layer caching mechanism of docker-compose is less reliable than docker's +depending on the version, ``cache_from`` build entry and the used backend +(docker-py, docker-cli, docker-cli and buildkit). This can lead to different +layer hashes - even when executing the same build command repeatedly - +eventually causing cache misses full image rebuilds. + +If the image has been already built but the cache doesn't work properly, it can +be useful to skip the build phases: Review comment: This sounds backwards to me but probably just needs a little explanation. If caching isn't working properly, doesn't that mean I *would* need to build, rather than? Because it can't take it from the cache. I would think that `--no-build` means "use the cache". ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
