Updated tutorial for Docker and Singularity for Linux

[rolivella]

The modified file is a tutorial on how to run FragPipe using Docker and Apptainer (formerly Singularity). It explains how to pull and run the fcyucn/fragpipe:<version> container in Docker, convert it into a Singularity image, and then run FragPipe using both containerization tools. The guide includes the necessary prerequisites for installing Docker and Apptainer on Linux, along with step-by-step instructions for running FragPipe in both environments, converting Docker images, and handling permissions with sudo.

[fcyu]

Could you add the option to

1. mout the host directory to the docker container
2. run FragPipe inside the container

These two are the major parts in my original tutorial, and I feel them the most handy when I use Docker.

Thanks,

Fengchao

[rolivella]

@fcyu new version adding your comments:

---

Running FragPipe using Docker and Singularity

This tutorial covers how to use Docker and Singularity to run FragPipe. We will run the fcyucn/fragpipe:<version> container, first with Docker, then converting it to a Singularity image.

Prerequisites for Docker and Apptainer (Linux)

Before setting up Docker and Apptainer on Linux, ensure the following:

• Operating System: A Linux distribution (e.g., Ubuntu, CentOS, Debian).

• Docker Installation: Install Docker by following the official guide for Linux.

• Apptainer Installation: Install Apptainer from the Apptainer documentation.

• Using Singularity Commands: Apptainer supports Singularity commands. After installation, you can use singularity as the command-line interface (apptainer binary serves as singularity).

• User Privileges: Ensure you have sudo privileges for installation.

Running FragPipe with Docker

1. Pull and run the Docker container:

   To run the FragPipe tool directly using Docker, execute:

   docker run fcyucn/fragpipe:<version> fragPipe-<version>/fragpipe/bin/fragpipe --help

   This command will:

   • Pull the fcyucn/fragpipe:<version> image from Docker Hub.
   • Run the fragpipe command inside the container, displaying the help options.

2. Mounting the Host Directory to the Docker Container:

   One of the most useful features of Docker is the ability to mount a host directory inside the container. This is especially helpful when you need to access data files or output results from FragPipe.

   You can mount a local directory (e.g., /path/to/your/data) to the Docker container using the -v option:

   docker run -v /path/to/your/data:/mnt/data fcyucn/fragpipe:<version> fragPipe-<version>/fragpipe/bin/fragpipe --help

   • /path/to/your/data: The path on your host machine where your data is located.
   • /mnt/data: The directory inside the container where the host directory will be mounted.

   Now, any files placed in /path/to/your/data will be accessible from /mnt/data inside the Docker container. This allows you to read input files and save output directly from/to your local machine while running FragPipe in Docker.

3. Running FragPipe Inside the Docker Container:

   To run FragPipe inside the container, mount the required directories (for example, where your data or project files are located), then execute the FragPipe tool. You can use the following command:

   docker run -v /path/to/your/data:/mnt/data -it fcyucn/fragpipe:<version> /fragpipe_bin/FragPipe-<version>/fragpipe/bin/fragpipe -config /mnt/data/config_file.fpconfig

   • -v /path/to/your/data:/mnt/data: Mounts the host directory to the container.
   • -it: Enables interactive mode, allowing you to interact with the container.
   • /fragpipe_bin/FragPipe-<version>/fragpipe/bin/fragpipe: Executes FragPipe inside the container.
   • -config /mnt/data/config_file.fpconfig: Specifies the configuration file from the mounted directory for FragPipe.

   You can replace /mnt/data/config_file.fpconfig with the path to your actual configuration file located in the mounted directory. This way, FragPipe runs with your specific settings.

4. Save the Docker image to a TAR file:

   To convert the Docker container for use in Singularity, save the Docker image to a tarball:

   docker save -o fragPipe-<version>.tar fcyucn/fragpipe:<version>

   This command will export the Docker image into a file called fragPipe-<version>.tar.

Running FragPipe with Singularity

1. Convert the Docker image to a Singularity image:

   Use the exported Docker tarball to create a Singularity image:

   singularity build fragPipe-<version>.img docker-archive://fragPipe-<version>.tar

   This will convert the Docker image into a Singularity image named fragPipe-<version>.img.

2. Run the FragPipe tool with Singularity:

   Once the Singularity image is built, you can execute the fragpipe command with:

   singularity exec fragPipe-<version>.img /fragpipe_bin/FragPipe-<version>/fragpipe/bin/fragpipe --help

   This command runs the same fragpipe tool using the Singularity image, displaying the help options.

3. Mounting Host Directories with Singularity:

   Similar to Docker, you can mount directories from your host system when using Singularity. Use the -B option to bind a directory from your host system to the Singularity container:

   singularity exec -B /path/to/your/data:/mnt/data fragPipe-<version>.img /fragpipe_bin/FragPipe-<version>/fragpipe/bin/fragpipe -config /mnt/data/config_file.fpconfig

   This command binds the host directory /path/to/your/data to /mnt/data inside the Singularity container and runs FragPipe using the specified configuration file.

[fcyu]

@rolivella I can't find the new commit. Could you push it?

Thanks,

Fengchao

[rolivella]

@fcyu OK, I pushed the commit: e5a7d88

[fcyu]

What is the -config flag for? And what is the format of the fpconfig file? Why not just provide FragPipe's arguments?

[fcyu]

What is the -config flag for? And what is the format of the fpconfig file? Why not just provide FragPipe's arguments?