diff --git a/docs/installation.rst b/docs/installation.rst index 9381937ce..1785de69a 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -153,9 +153,59 @@ hardware intended to run openfe jobs, as it will test GPU specific features. With that, you should be ready to use ``openfe``! +``conda-lock`` file +------------------- + +.. _conda-lock: https://github.com/conda/conda-lock?tab=readme-ov-file#conda-lock + +A `conda-lock`_ file is a cross platform way of specifying a conda environment that specifies packages in a reproducible way. +Unlike the single file installer, an internet connection is required to install from a ``conda-lock`` file. +We recomend the use of a ``conda-lock`` file when the same conda environment is required across different systems. + + +.. note:: + + You will likely need to install ``conda-lock``. + We strongly recomend installing ``conda-lock`` in a new virtual environment. + This will reduce the chance of dependency conflicts :: + + $ # Install conda lock into a virtual environment + $ conda create -n conda-lock -c conda-lock + $ # Activate the environment to use the conda-lock command + $ conda activate conda-lock + +See https://github.com/conda/conda-lock?tab=readme-ov-file#conda-lock for more information on ``conda-lock``. + +The latest version of the `conda-lock` file we provide can be downloaded with :: + + $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/latest/download/conda-lock-openfe.yml + +If a particular version is required, the URL will look like this (using the ``openfe 1.0.1`` release as an example) :: + + $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/download/v1.0.1/conda-lock-openfe-1.0.1.yml + +Create a conda environment from the lock file and activate it:: + + $ conda-lock install -n openfe conda-lock-openfe.yml + $ conda activate openfe + +To make sure everything is working, run the tests :: + + $ pytest --pyargs openfe openfecli + +The test suite contains several hundred individual tests. This will take a +few minutes, and all tests should complete with status either passed, +skipped, or xfailed (expected fail). + +With that, you should be ready to use ``openfe``! + Single file installer --------------------- +.. warning:: + + The single file installer may modify your ``.bashrc`` in a way that requires manual intervention to access your previous ``conda`` installation + .. _releases on GitHub: https://github.com/OpenFreeEnergy/openfe/releases Single file installers are available for x86_64 Linux and MacOS. @@ -359,43 +409,6 @@ skipped, or xfailed (expected fail). With that, you should be ready to use ``openfe``! -``conda-lock`` file -------------------- - -.. _conda-lock: https://github.com/conda/conda-lock?tab=readme-ov-file#conda-lock - -A `conda-lock`_ file is a cross platform way of specifying a conda environment that specifies packages in a reproducible way. -Unlike the single file installer, an internet connection is required to install from a ``conda-lock`` file. -We recomend the use of a ``conda-lock`` file when the same conda environment is required across different systems. - -See https://github.com/conda/conda-lock?tab=readme-ov-file#installation for instructions on how to install ``conda-lock``. - -.. note:: - - You will likely need to install ``conda-lock`` - -The latest version of the `conda-lock` file we provide can be downloaded with :: - - $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/latest/download/conda-lock-openfe.yml - -If a particular version is required, the URL will look like this (using the ``openfe 1.0.1`` release as an example) :: - - $ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/download/v1.0.1/conda-lock-openfe-1.0.1.yml - -Create a conda environment from the lock file and activate it:: - - $ conda-lock install -n openfe conda-lock-openfe.yml - $ conda activate openfe - -To make sure everything is working, run the tests :: - - $ pytest --pyargs openfe openfecli - -The test suite contains several hundred individual tests. This will take a -few minutes, and all tests should complete with status either passed, -skipped, or xfailed (expected fail). - -With that, you should be ready to use ``openfe``! Containers ----------