From ab378c8c8509a0092b32326e64f6b662f44d1ac9 Mon Sep 17 00:00:00 2001 From: Roger Olivella Date: Thu, 17 Oct 2024 17:58:44 +0200 Subject: [PATCH 1/2] Updated tutorial for Docker and Singularity for Linux --- docs/tutorial_docker.md | 68 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 60 insertions(+), 8 deletions(-) diff --git a/docs/tutorial_docker.md b/docs/tutorial_docker.md index 3f6ace578..2a544dec9 100644 --- a/docs/tutorial_docker.md +++ b/docs/tutorial_docker.md @@ -1,10 +1,62 @@ -# Pulling and running FragPipe using Docker - -- Install docker by following the [instruction](https://docs.docker.com/desktop/install/mac-install/) -- Open terminal and pull the docker image: `docker pull fcyucn/fragpipe` -- (optional) Check the pulled image: `docker image ls -a` -- Create a Docker container: `docker run -it -v : fcyucn/fragpipe /bin/bash`. `` is the directory in your host machine, and `` is the directory you want to map the host directory to container. -- Then, you have entered the docker, and FragPipe is located in `/fragpipe_bin` -- Go to `/fragpipe_bin/fragPipe-x.x/fragpipe/bin` directory and execute `./fragpipe --help` in the terminal +# Running FragPipe using Docker and Singularity + +This tutorial covers how to use **Docker** and **Singularity** to run FragPipe. We will run the `fcyucn/fragpipe:` 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](https://docs.docker.com/engine/install/). +- **Apptainer Installation**: Install Apptainer from the [Apptainer documentation](https://apptainer.org/docs/admin/main/installation.html). +- **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: + + ```bash + docker run fcyucn/fragpipe: fragPipe-/fragpipe/bin/fragpipe --help + ``` + + This command will: + - Pull the `fcyucn/fragpipe:` image from Docker Hub. + - Run the `fragpipe` command inside the container, displaying the help options. + +2. **Save the Docker image to a TAR file:** + + To convert the Docker container for use in Singularity, save the Docker image to a tarball: + + ```bash + docker save -o fragPipe-.tar fcyucn/fragpipe: + ``` + + This command will export the Docker image into a file called `fragPipe-.tar`. + +## Running FragPipe with Singularity + +1. **Convert the Docker image to a Singularity image:** + + Use the exported Docker tarball to create a Singularity image: + + ```bash + singularity build fragPipe-.img docker-archive://fragPipe-.tar + ``` + + This will convert the Docker image into a Singularity image named `fragPipe-.img`. + +2. **Run the FragPipe tool with Singularity:** + + Once the Singularity image is built, you can execute the `fragpipe` command with: + + ```bash + singularity exec fragPipe-.img /fragpipe_bin/FragPipe-/fragpipe/bin/fragpipe --help + ``` + + This command runs the same `fragpipe` tool using the Singularity image, displaying the help options. Read more: Check [Running FragPipe in command line interface](https://fragpipe.nesvilab.org/docs/tutorial_headless.html) for the instructions running FragPipe in command line interface. From e5a7d887cecb2785d2258d4301d3a870c69de904 Mon Sep 17 00:00:00 2001 From: Roger Olivella Date: Wed, 23 Oct 2024 09:36:06 +0200 Subject: [PATCH 2/2] Added docker running instructions within the container --- docs/tutorial_docker.md | 162 +++++++++++++++++++++++++--------------- 1 file changed, 100 insertions(+), 62 deletions(-) diff --git a/docs/tutorial_docker.md b/docs/tutorial_docker.md index 2a544dec9..021378183 100644 --- a/docs/tutorial_docker.md +++ b/docs/tutorial_docker.md @@ -1,62 +1,100 @@ -# Running FragPipe using Docker and Singularity - -This tutorial covers how to use **Docker** and **Singularity** to run FragPipe. We will run the `fcyucn/fragpipe:` 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](https://docs.docker.com/engine/install/). -- **Apptainer Installation**: Install Apptainer from the [Apptainer documentation](https://apptainer.org/docs/admin/main/installation.html). -- **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: - - ```bash - docker run fcyucn/fragpipe: fragPipe-/fragpipe/bin/fragpipe --help - ``` - - This command will: - - Pull the `fcyucn/fragpipe:` image from Docker Hub. - - Run the `fragpipe` command inside the container, displaying the help options. - -2. **Save the Docker image to a TAR file:** - - To convert the Docker container for use in Singularity, save the Docker image to a tarball: - - ```bash - docker save -o fragPipe-.tar fcyucn/fragpipe: - ``` - - This command will export the Docker image into a file called `fragPipe-.tar`. - -## Running FragPipe with Singularity - -1. **Convert the Docker image to a Singularity image:** - - Use the exported Docker tarball to create a Singularity image: - - ```bash - singularity build fragPipe-.img docker-archive://fragPipe-.tar - ``` - - This will convert the Docker image into a Singularity image named `fragPipe-.img`. - -2. **Run the FragPipe tool with Singularity:** - - Once the Singularity image is built, you can execute the `fragpipe` command with: - - ```bash - singularity exec fragPipe-.img /fragpipe_bin/FragPipe-/fragpipe/bin/fragpipe --help - ``` - - This command runs the same `fragpipe` tool using the Singularity image, displaying the help options. - -Read more: Check [Running FragPipe in command line interface](https://fragpipe.nesvilab.org/docs/tutorial_headless.html) for the instructions running FragPipe in command line interface. +# Running FragPipe using Docker and Singularity + +This tutorial covers how to use **Docker** and **Singularity** to run FragPipe. We will run the `fcyucn/fragpipe:` 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](https://docs.docker.com/engine/install/). +- **Apptainer Installation**: Install Apptainer from the [Apptainer documentation](https://apptainer.org/docs/admin/main/installation.html). +- **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: + + ```bash + docker run fcyucn/fragpipe: fragPipe-/fragpipe/bin/fragpipe --help + ``` + + This command will: + - Pull the `fcyucn/fragpipe:` 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: + + ```bash + docker run -v /path/to/your/data:/mnt/data fcyucn/fragpipe: fragPipe-/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: + + ```bash + docker run -v /path/to/your/data:/mnt/data -it fcyucn/fragpipe: /fragpipe_bin/FragPipe-/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-/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: + + ```bash + docker save -o fragPipe-.tar fcyucn/fragpipe: + ``` + + This command will export the Docker image into a file called `fragPipe-.tar`. + +## Running FragPipe with Singularity + +1. **Convert the Docker image to a Singularity image:** + + Use the exported Docker tarball to create a Singularity image: + + ```bash + singularity build fragPipe-.img docker-archive://fragPipe-.tar + ``` + + This will convert the Docker image into a Singularity image named `fragPipe-.img`. + +2. **Run the FragPipe tool with Singularity:** + + Once the Singularity image is built, you can execute the `fragpipe` command with: + + ```bash + singularity exec fragPipe-.img /fragpipe_bin/FragPipe-/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: + + ```bash + singularity exec -B /path/to/your/data:/mnt/data fragPipe-.img /fragpipe_bin/FragPipe-/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. \ No newline at end of file