MAINT: update installation instructions (#167)

* update installation instructions * update note on Docker images * update codecov action * update instructions to include Q2 metagenome as default * fix hyperlinks * fix last link * fix special charac link * address comments * shorten intro of installation --------- Co-authored-by: Michal Ziemski <[email protected]>
bokulich-lab · Jul 8, 2024 · 7892c1f · 7892c1f
1 parent f357fa8
commit 7892c1f
Show file tree

Hide file tree

Showing 3 changed files with 40 additions and 23 deletions.
diff --git a/.github/workflows/ci-dev.yaml b/.github/workflows/ci-dev.yaml
@@ -25,7 +25,7 @@ jobs:
           name: ${{ needs.ci.outputs.additional-reports-name }}
           path: ${{ needs.ci.outputs.additional-reports-path }}
 
-      - uses: codecov/codecov-action@v3
+      - uses: codecov/codecov-action@v4
         name: 'Upload coverage'
         with:
           fail_ci_if_error: true

diff --git a/README.md b/README.md
@@ -12,38 +12,45 @@
 </p><br>
 
 ## Installation
-You can install q2-fondue using mamba in a conda environment of its own (option 1) or in an existing QIIME 2 environment (option 2) by following the steps described below. The current q2-fondue version supports QIIME 2 **v2021.4** or higher. Alternatively, a minimal Docker image is available to run q2-fondue methods (option 3 below).
+There are multiple options to install q2-fondue (**v2024.5** or higher) - each targeted towards different needs:
 
-For both options 1 and 2 make sure to start by installing [mamba](https://mamba.readthedocs.io/en/latest/index.html) in your base environment:
+(To install q2-fondue with a version <= 2023.7 see [this](#installing-q2-fondue-with-older-versions) section.)
+
+### Option 1: Install q2-fondue with QIIME 2 metagenome distribution
+q2-fondue is a part of the QIIME 2 metagenome distribution and you can install it as outlined in the [QIIME 2 installation instructions](https://docs.qiime2.org/). 
+After that, don't forget to run **[the mandatory configuration step](#mandatory-configuration-for-all-three-options)**!
+
+### Option 2: Install q2-fondue within a QIIME 2 amplicon conda environment
+* Install the QIIME 2 amplicon distribution within a conda environment as described in [the official QIIME 2 documentation](https://docs.qiime2.org/). 
+* Activate the QIIME 2 environment (v2024.5 or higher) and install q2-fondue within while making sure that the used conda channel matches the version of the QIIME 2 environment (replace below `{ENV_VERSION}` with the version number of your QIIME 2 environment):
+```
+conda activate qiime2-amplicon-{ENV_VERSION}
+mamba install -y \
+   -c https://packages.qiime2.org/qiime2/{ENV_VERSION}/metagenome/released/ \
+   -c conda-forge -c bioconda -c defaults \
+   q2-fondue
+```
+* Now, don't forget to run **[the mandatory configuration step](#mandatory-configuration-for-all-three-options)**!
+
+### Option 3: Minimal fondue environment
+* Start with installing [mamba](https://mamba.readthedocs.io/en/latest/index.html) in your base environment:
 ```shell
 conda install mamba -n base -c conda-forge
 ```
-
-### Option 1: Minimal fondue environment:
 * Create and activate a conda environment with the required dependencies:
 ```shell
 mamba create -y -n fondue \
-   -c https://packages.qiime2.org/qiime2/2023.7/tested/ \
+   -c https://packages.qiime2.org/qiime2/2024.5/metagenome/released/ \
    -c conda-forge -c bioconda -c defaults \
    q2cli q2-fondue
 
 conda activate fondue
 ```
-Now, don't forget to run [the mandatory configuration step](#mandatory-configuration-for-both-options-1-and-2)!
+* Now, don't forget to run **[the mandatory configuration step](#mandatory-configuration-for-all-three-options)**!               
 
-### Option 2: Install fondue within existing QIIME 2 environment
-* Install QIIME 2 within a conda environment as described in [the official user documentation](https://docs.qiime2.org/). 
-* Activate the QIIME 2 environment (v2022.8 or higher) and install fondue within while making sure that the used conda channel matches the version of the QIIME 2 environment (replace below `{ENV_VERSION}` with the version number of your QIIME 2 environment):
-```
-conda activate qiime2-{ENV_VERSION}
-mamba install -y \
-   -c https://packages.qiime2.org/qiime2/{ENV_VERSION}/tested/ \
-   -c conda-forge -c bioconda -c defaults \
-   q2-fondue
-```
-Now, don't forget to run [the mandatory configuration step](#mandatory-configuration-for-both-options-1-and-2)!
+Note: You can replace the version number `2024.5` with later releases if they are already available. 
 
-### Mandatory configuration for both options 1 and 2
+### Mandatory configuration for all three options
 * Refresh the QIIME 2 CLI cache and see that everything worked:
 ```shell
 qiime dev refresh-cache
@@ -63,9 +70,19 @@ vdb-config -i
 vdb-config --proxy <your proxy URL> --proxy-disable no
 ```
 
-### Option 3: Use fondue via a public Docker image
-Use containerization to integrate q2-fondue into your pipelines, or simply run reproducibly without the need for heavyweight package managers. [Read more about Docker here.](https://www.docker.com/get-started/)
-
+### Installing q2-fondue with older versions
+To install fondue with a version <= 2023.7 in a minimal environment run the following command inserting the respective version number `{ENV_VERSION}`:
+```shell
+mamba create -y -n fondue \
+   -c https://packages.qiime2.org/qiime2/{ENV_VERSION}/tested/ \
+   -c conda-forge -c bioconda -c defaults \
+   q2cli q2-fondue
+
+conda activate fondue
+```
+Now, don't forget to run **[the mandatory configuration step](#mandatory-configuration-for-all-three-options)**!               
+
+Alternatively, a minimal Docker image is available to run q2-fondue==v2023.7: 
 * Install [Docker](https://docs.docker.com/engine/install/) with the linked instructions
 * Pull the [q2-fondue Docker image](https://hub.docker.com/layers/linathekim/q2-fondue/2023.7/images/sha256-f5d26959ac035811a8f34e2a46f6cc381f9a4ce21b3604a196c1ee176ba708e7?context=repo):
 ```shell

diff --git a/tutorial/tutorial.md b/tutorial/tutorial.md
@@ -65,7 +65,7 @@ Some microbiome datasets are also uploaded on [Qiita](https://qiita.ucsd.edu), a
 After reading about regionally distinct microbial communities in vineyards in the publication by Bokulich et al. (2016)<sup>2</sup>, we are super curious to explore the dataset this study was based on. Luckily, with _q2-fondue_ retrieving all this data is a cakewalk! :cake:
 
 ### Installation
-To install _q2-fondue_ please follow the instructions for installing _q2-fondue_ in an existing QIIME 2 environment (option 2) available in the [README](../README.md).
+To install _q2-fondue_ please follow the instructions for installing _q2-fondue_ in an existing QIIME 2 amplicon environment (option 2) available in the [README](../README.md).
 
 ### Getting started