diff --git a/docs/_index.md b/docs/_index.md index ab6192aa8b2..c96c6335f1f 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -28,7 +28,7 @@ If you are viewing documentation for the development branch, you may wish to ins See the **advanced** installation instructions to use a preview or alternate version of Poetry. {{% /note %}} -{{< tabs tabTotal="4" tabID1="installing-with-the-official-installer" tabID2="installing-with-pipx" tabID3="installing-manually" tabID4="ci-recommendation" tabName1="With the official installer" tabName2="With pipx" tabName3="Manually (advanced)" tabName4="CI recommendations">}} +{{< tabs tabTotal="4" tabID1="installing-with-the-official-installer" tabID2="installing-with-pipx" tabID3="installing-manually" tabID4="ci-recommendations" tabName1="With the official installer" tabName2="With pipx" tabName3="Manually (advanced)" tabName4="CI recommendations">}} {{< tab tabID="installing-with-the-official-installer" >}} @@ -275,49 +275,76 @@ Poetry will be available at `$VENV_PATH/bin/poetry` and can be invoked directly To uninstall Poetry, simply delete the entire `$VENV_PATH` directory. {{< /tab >}} -{{< tab tabID="ci-recommendation" >}} -In contrast to development environments, where always having the latest version of an application is a good idea, -CI environments should be as much reproducable as possible. Here are some recommendations, when installing Poetry in -such an environment. +{{< tab tabID="ci-recommendations" >}} +Unlike development environments, where making use of the latest tools is desirable, in a CI environment reproducibility +should be made the priority. Here are some suggestions for installing Poetry in such an environment. -**Pin Poetry version** +**Installation method** -To ensure reproducable behavior it is highly recommended to explicit set a version during the installation. This can -be done by either using the `--version` option or set the `$POETRY_VERSION` environment variable: +The official installer script ([install.python-poetry.org](https://install.python-poetry.org)) offers a streamlined and +simplified installation of Poetry, sufficient for developer use or for simple pipelines. However, in a CI environment +the other two supported installation methods (pipx and manual) should be seriously considered. -```bash -curl -sSL https://install.python-poetry.org | python3 - --version 1.2.0 -curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.2.0 python3 - -``` +**Using install.python-poetry.org** -**Installation method** +Downloading a copy of the installer script to a place accessible by your CI pipelines (or maintaining a copy of the +[repository](https://github.com/python-poetry/install.python-poetry.org)) is strongly suggested, to ensure your +pipeline's stability and to maintain control over what code is executed. -Downloading the installer script from https://install.python-poetry.org always returns the latest version of the script. -To ensure reproducable behavior of the installation process, other ways are recommended: +By default the installer will install to a user-specific directory. In more complex pipelines that may make accessing +Poetry difficult (especially in cases like multi-stage container builds). It is highly suggested to make use of +`$POETRY_HOME` when using the official installer in CI, as that way the exact paths can be controlled. -***Store a local copy of the installer*** +```bash +export POETRY_HOME=/opt/poetry +python3 install-poetry.py --version 1.2.0 +$POETRY_HOME/bin/poetry --version +``` -Either fork the [repository of the installer](https://github.com/python-poetry/install.python-poetry.org) or download -the installer script once and place it somewhere, where all your CI pipelines have access to. Thus, you have the complete -control over which version of the installer is used. +**Using pipx** -***Use pip*** +Just as `pipx` is a powerful tool for development use, it is equally useful in a CI environment. It takes the same steps +the installer does to safely install Poetry isolated from the rest of your system, but is generic and able to do this +for any Python package, with a syntax/usage that is similar to `pip`. `pipx` should be considered equally supported in +comparison to the official installer, and should be one of your top choices for use of Poetry in CI. -The recommended way is using the installer or pipx. Both ensure that Poetry is isolated from other Python packages and -a global `poetry` command is provided. +``` +pipx install poetry==1.2.0 +``` -However, in a CI environment you have usually a complete control over what is installed and which commands run. Thus, it -might be suitable to install Poetry via `pip`: +**Using pip (aka manually)** -```bash -pip install poetry==1.2.0 +For maximum control in your CI environment, installation with `pip` is fully supported and something you should +consider. While this requires more explicit commands and knowledge of Python packaging from you, it in return offers the +best debugging experience, and leaves you subject to the fewest external tools. + +``` +virtualenv /opt/poetry +/opt/poetry/bin/pip install poetry==1.2.0 +/opt/poetry/bin/poetry --version ``` {{% note %}} -If you install Poetry via `pip`, ensure it is not installed in the same environment Poetry should manage. Otherwise it is -possible that Poetry will accidentally upgrade or uninstall its own dependencies. +If you install Poetry via `pip`, ensure you have Poetry installed into an isolated environment that is **not the same** +as the target environment managed by Poetry. If Poetry and your project are installed into the same environment, Poetry +is likely to upgrade or uninstall its own dependencies (causing hard-to-debug and understand errors). {{% /note %}} +**Version pinning** + +Whatever method you use, it is highly recommended to explicitly control the version of Poetry used, so that you are able +to upgrade after performing your own validation. Each install method has a different syntax for setting the version -- +the following are some simple examples: + +```bash +curl -sSL https://install.python-poetry.org | python3 - --version 1.2.0 +# or +curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.2.0 python3 - + +pipx install poetry==1.2.0 + +/path/to/venv/bin/pip install poetry==1.2.0 +``` {{< /tab >}} {{< /tabs >}}