Working with your QIIME 2 container

Working with your QIIME 2 container#

In this workshop, to use QIIME 2 on the command line or through Jupyter Lab, you’ll work through a containerized environment. We recommend using either Podman or Docker. Before you jump in with QIIME 2, follow the “Get Started” (i.e., install) instructions for one or the other, and confirm that it’s working according to the Podman’s or Docker’s instructions. (We don’t link to their instructions here so that we don’t send you to an outdated link.)

Podman versus Docker

We don’t take much of a stance on whether Podman or Docker is a better tool for using QIIME 2 - teaching with either is still pretty new to us.

Podman seems to have some interesting benefits though, including ease of transition to paid cloud environments (via Kubernetes) if you need more computational resources than you have access to. Podman also doesn’t require that you have root/admin access on the computer where you’re using it, so may work better if you’re using computer hardware that is administered by others (such as a laptop computer owned and maintained by your employer).

You can find a perspective on the differences between the two from the developers of Podman here.

Pull the container image#

After installing Docker or Podman, we next need to pull (i.e., download) the image that contains our QIIME 2 environment. Copy/paste the relevant commands.

First, open Docker Desktop.

Then, in a command terminal, run:

docker \
 image \
 pull quay.io/qiime2/workshops:2024.08.27-nih-amplicon-2024.5

The first time you start podman, you’ll need to run the following command:

podman machine init

Then, each time you restart your computer, you’ll need to run:

podman machine start

Then, run:

podman \
 image \
 pull quay.io/qiime2/workshops:2024.08.27-nih-amplicon-2024.5

Create data storage volume#

Next, we create a volume that will be used to store any data we generate during our analysis. Data that you create in your container will persist and be available the next time you start the container.

docker volume create qiime2-workshop

podman volume create qiime2-workshop

Start the container#

Next, we’ll start the container.

docker container run \
  -itd \
  --rm \
  -v qiime2-workshop:/home/qiime2 \
  --name qiime2-workshop \
  -p 8889:8888 \
  quay.io/qiime2/workshops:2024.08.27-nih-amplicon-2024.5

docker container run \
  -itd \
  --rm \
  -v qiime2-workshop:/home/qiime2 \
  --name qiime2-workshop \
  -p 8889:8888 \
  --platform "linux/amd64" \
  quay.io/qiime2/workshops:2024.08.27-nih-amplicon-2024.5

podman container run \
  -itd \
  --rm \
  -v qiime2-workshop:/home/qiime2 \
  --name qiime2-workshop \
  -p 8889:8888 \
  quay.io/qiime2/workshops:2024.08.27-nih-amplicon-2024.5

podman container run \
  -itd \
  --rm \
  -v qiime2-workshop:/home/qiime2 \
  --name qiime2-workshop \
  -p 8889:8888 \
  --platform "linux/amd64" \
  quay.io/qiime2/workshops:2024.08.27-nih-amplicon-2024.5

Interact with Jupyter Lab and QIIME 2#

When the container is running, you can interact with it by opening the following link: http://localhost:8889

Using QIIME 2 through the command line#

In the Jupyter Lab window, click the Terminal button toward the bottom right. (Look for a block box with a $ symbol in it.)

You’ll then have command line access to QIIME 2.

In the terminal environment, run the following command:

qiime info

This provides information on your QIIME 2 environment, including the versions of the QIIME 2 framework, Python, and the installed plugins.

To get a start getting a feel for what you can do with your QIIME 2 deployment, run:

qiime --help

This provides a list of the available QIIME 2 plugins. To learn more about what you can do with one of them (for example, the feature-table plugin), call:

qiime feature-table --help

This will display a list of actions (i.e., commands) that are available in that plugin. To learn how to use one, for example filter-samples, call:

qiime feature-table filter-samples --help

That will provide help text and a list of examples that illustrate how to use the command to achieve different goals.

You can return to this document when you need to start, stop, or update your container. You can now continue to Exploring the data through your container.

Stopping the container#

When you’re no longer using the container, you can stop it as follows:

docker container stop qiime2-workshop

podman container stop qiime2-workshop

If using Docker, once you’re done using your container and don’t have any other containers running, it’s a good idea to quit Docker so it’s not using resources unnecessarily.

Building the image locally (optional; experts only ♦♦)#

Expert users may ultimately be interesting in modifying the image used here. This can be done with docker as follows. Pulling the image will be quicker and easier.

First, clone the repository for this Jupyter book.

git clone git@github.com:caporaso-lab/2024-q2-ITN-Workshop.git

Then, navigate to the directory that contains the Dockerfile and auxiliary data.

cd 2024-q2-ITN-Workshop/dockerfiles/jupyter-lab-on-miniconda

Next, make sure that the Docker daemon is running (e.g. by launching Docker Desktop).

Finally, build the image.

docker image build -t my-image-name .

docker image build -t my-image-name --platform "linux/amd64" .