diff --git a/README.md b/README.md index 5bb4cee0b..95b79e4d1 100644 --- a/README.md +++ b/README.md @@ -81,6 +81,11 @@ optional arguments: Check the [EXAMPLES](https://github.com/haddocking/haddock3/blob/main/examples/README.md) page for more some usage examples and the [User manual](https://www.bonvinlab.org/haddock3-user-manual) for a more detailed explanation of the configuration file. +## Container Usage Examples + +- [Container Usage Guide](usage-container/docs/usage.md) + (see detailed docs on running, builidng container, Slurm snippets, etc.) + ## Support If you encounter any code-related issues, [please open an issue](https://github.com/haddocking/haddock3/issues/new/choose). diff --git a/usage-container/CONTRIBUTING.md b/usage-container/CONTRIBUTING.md new file mode 100644 index 000000000..ac6b17899 --- /dev/null +++ b/usage-container/CONTRIBUTING.md @@ -0,0 +1,18 @@ +## What I Love to See + +We're not just building containers—we're crafting efficient, elegant tools for science. If you're looking for ways to make a difference, consider contributing to: + +- **New functionalities** (e.g., new features or support) +- **Reducing redundancy** in scripts or layered installs +- **Shrinking image size** by stripping unused packages or optimizing layers +- **Lowering computational/carbon footprint** through performance tweaks or ecoconscious configurations (smaller images) + +## Ideas Welcome — Let’s Connect! + +Have a suggestion? Want to extend functionality, reduce image size, or make this container even more efficient and elegant? I'm all ears. + +Feel free to: +- Open an [issue](https://github.com/Comp-era/Apptainer-Container-for-HADDOCK3/issues) +- Start a discussion +- Or reach out directly (shantanukhatri.bio@gmail.com), collaboration is always welcome. + diff --git a/usage-container/LICENSE b/usage-container/LICENSE new file mode 100644 index 000000000..20f363241 --- /dev/null +++ b/usage-container/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Shantanu Khatri + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/usage-container/README.md b/usage-container/README.md new file mode 100644 index 000000000..d72b34d0f --- /dev/null +++ b/usage-container/README.md @@ -0,0 +1,123 @@ +# Container workflow for HADDOCK3 + +This repository provides everything you need to build, run, and extend an **Apptainer/Singularity** container for HADDOCK3. [**HADDOCK3**](https://www.biorxiv.org/content/10.1101/2025.04.30.651432v1)(High Ambiguity Driven protein–protein Docking) is a flexible, information-driven software suite for modeling biomolecular complexes using experimental and theoretical restraints. **Docker**, **Singularity**, and **Apptainer** are containerization platforms that package applications and all their dependencies into lightweight, portable images, ensuring reproducible execution across different environments. + +A ready-to-use Docker image for HADDOCK3 is published on the GitHub container registry, simply pull: +```bash +docker pull ghcr.io/haddocking/haddock3:2025.5.0 +``` +See the [HADDOCK3 container package](https://github.com/haddocking/haddock3/pkgs/container/haddock3) for details and version tags. This image serves as the canonical, versioned distribution of HADDOCK3 and can be used across development, CI/CD, and cloud environments. + +To use this as the foundation for HPC-friendly SIF images, build **Apptainer** or **Singularity** containers directly from the Docker image in a single step. For example, to create an image: + +```bash +# Build Apptainer image +apptainer build haddock3_mpi.sif docker://ghcr.io/haddocking/haddock3:2025.5.0 + +# Or, build with Singularity +singularity build haddock3_mpi.sif docker://ghcr.io/haddocking/haddock3:2025.5.0 + ``` +**Note:** Refer to the [**usage.md**](https://github.com/Comp-era/HADDOCK3-Container/blob/main/docs/usage.md) and the example SLURM script available in the `scripts` folder for detailed instructions on how to run HADDOCK3 jobs in an HPC environment. +
 Version updates: The HADDOCK3 image is regularly updated. Please check the tags at ghcr.io/haddocking/haddock3 for the latest version.
+ +--- + +### Build Your Own HADDOCK3 Container +Containerization techniques enable highly reproducible, customizable, and scalable scientific workflows. If you want to understand how the container is built under the hood from scratch or customize it for your own workflows, follow these detailed steps: +1. **Clone** + + ```bash + git clone https://github.com/Comp-era/HADDOCK3-Container.git + cd HADDOCK3-Container/recipe + ``` + + **Repository Structure** + + ```plaintext + ├── apptainer_recipe/ + │ └── HADDOCK3.def # Definition file + ├── docs/ # Documentation + │ ├── usage.md # Usage guide + ├── scripts/ # Scripts + │ ├── slurm_run.sh # Multi-node MPI run script + ├── LICENSE # MIT License + ├── README.md # Overview + └── CONTRIBUTING.md # Contribution guidelines + ``` + +2. **Build** + +A definition file is a blueprint that tells the containerization platform how to build the container. It specifies the base OS, software packages, environment variables, and custom setup steps, ensuring your container is reproducible and tailored to your workflow. +A ready-to-use `HADDOCK3.def` is provided in the ([recipe/](https://github.com/Comp-era/HADDOCK3-Container/tree/main/recipe)) directory. + + ```bash + # Apptainer + apptainer build haddock3_mpi.sif haddock3_mpi.def + + # Singularity + singularity build haddock3_mpi.sif haddock3_mpi.def + ``` + + **Tip:** To create your own definition files to layer in additional packages, alternative MPI variants, Python libraries, and any domain-specific utilities.Just simply modify the `%post` section of `HADDOCK3.def` before building. + +3. **Verify&Run** + + - **Shell**: interactive access + ```bash + apptainer shell haddock3_cpu-mpi.sif + ``` + - **HADDOCK3**: verify installation + ```bash + apptainer shell haddock3_cpu-mpi.sif haddock3 --version + ``` + + +4. **Download a pre-built image** + + You can also pull the pre-built apptainer image I created directly from GitHub’s container registry using the ORAS protocol: + + ```bash + apptainer pull oras://ghcr.io/comp-era/haddock3:2025.06-v1.0-haddock3-mpi + ``` +--- + +## Resources & Tutorials + +- **Apptainer Installation & Usage**: Detailed installation instructions and usage examples can be found on the official docs: [apptainer.org/docs/admin/main/installation.html](https://apptainer.org/docs/admin/main/installation.html) +- **Official HADDOCK3 Tutorials**: Visit the Bonvin lab’s educational page for HADDOCK3 tutorials : [bonvinlab.org/education/HADDOCK3](https://www.bonvinlab.org/education/HADDOCK3/) +- **Source Code & Issues**: Explore the HADDOCK3 source code on GitHub: [github.com/haddocking/haddock3](https://github.com/haddocking/haddock3) + +--- + +## Requirements + +- **Host**: Linux with Apptainer or Singularity installed (local machine or HPC environment) +- **Disk**: ≥ 2 GB free for building +- **Python**: 3.10+ (inside container) + +--- + +## Documentation + +See the `docs/` folder: + +- [**usage.md**](https://github.com/Comp-era/HADDOCK3-Container/blob/main/docs/usage.md) – Detailed usage and instructions to run Apptainer. + +--- + +## Contributing + +Kindly refer to [CONTRIBUTING.md](CONTRIBUTING.md) , for contributions. + + + +--- + +## License + +MIT License © 2025 Shantanu Khatri. + +--- + +*Get ready for seamless reproducible workflow for HADDOCK3 runs!* + diff --git a/usage-container/docs/usage.md b/usage-container/docs/usage.md new file mode 100644 index 000000000..ab1484850 --- /dev/null +++ b/usage-container/docs/usage.md @@ -0,0 +1,46 @@ +This guide explains how to run HADDOCK3 jobs either interactively or via SLURM batch submission (MPI HPC ready) +--- + +## Quick Start + +### 1. Run Interactively with `srun` + +To run HADDOCK3 in an interactive SLURM session: + +#example code + +srun --partition=compute \ + --nodes=1 \ + --ntasks-per-node=8 \ + --chdir=/path/to/haddock3/examples/docking-protein-protein \ + apptainer exec \ + --bind /path/to/host:/path/to/host \ + /path/to/haddock3_cpu-mpi.sif \ + haddock3 docking-protein-protein-mpi.cfg + + *Note: Change the `.cfg` file path and directory bindings to match your project location.* + +--- + +### 2. Run as a Batch Job with `sbatch` + +Submit your job to SLURM using the sample script in the `scripts/` folder: + +```bash +scripts/ sbatch run_haddock3_slurm.sh +``` + + *Customize the script and config paths as needed.* + +--- + + + + +## Requirements + +- SLURM-enabled HPC environment +- Docker, Apptainer or Singularity installed +- Image: `haddock-mpi-gpt.sif` +- `.cfg` configuration file for HADDOCK3 + diff --git a/usage-container/recipe/haddock3_mpi.def b/usage-container/recipe/haddock3_mpi.def new file mode 100644 index 000000000..aef29d213 --- /dev/null +++ b/usage-container/recipe/haddock3_mpi.def @@ -0,0 +1,27 @@ +Bootstrap: docker +From: ubuntu:22.04 + +%labels + Maintainer Shantanu Khatri + Description "MPI-ready HADDOCK3 + mpi4py container" + +%environment + export PATH=/usr/local/bin:$PATH + export LD_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu/openmpi/lib:$LD_LIBRARY_PATH + +%post + # Install core dependencies and MPI + apt-get update && apt-get install -y \ + wget git build-essential cmake gfortran \ + libfftw3-dev libxml2-dev zlib1g-dev \ + openmpi-bin libopenmpi-dev \ + python3 python3-pip \ + && apt-get clean && rm -rf /var/lib/apt/lists/* + + # Install Python packages + pip3 install --no-cache-dir --upgrade pip \ + mpi4py haddock3 + +%runscript + echo "Welcome to the MPI-ready HADDOCK3 container." + exec "$@" diff --git a/usage-container/scripts/slurm_run._apptainer.sh b/usage-container/scripts/slurm_run._apptainer.sh new file mode 100644 index 000000000..972076e5a --- /dev/null +++ b/usage-container/scripts/slurm_run._apptainer.sh @@ -0,0 +1,34 @@ +#!/bin/bash + +#SBATCH --job-name=HADDOCK3-docking +#SBATCH --output=HADDOCK3_%j.out +#SBATCH --nodes=3 +#SBATCH --ntasks-per-node=120 +#SBATCH --mem=256GB +#SBATCH --partition=compute + +echo "Starting HADDOCK3 Docking Job" +echo "SLURM_JOBID = $SLURM_JOBID" +echo "SLURM_JOB_NODELIST = $SLURM_JOB_NODELIST" +echo "SLURM_NNODES = $SLURM_NNODES" +echo "SLURMTMPDIR = $SLURMTMPDIR" +echo "Date = $(date)" +echo "Hostname = $(hostname -s)" +echo "Working Directory = $(pwd)" +echo "Submit Directory = $SLURM_SUBMIT_DIR" + +# Load necessary environment (optional depending on your setup) +source /lustre/oneApi/setvars.sh +export OMP_NUM_THREADS=1 + +# Run HADDOCK3 via Apptainer +cd "${WORK_DIR}" + +# Ensure the working directory is set correctly +apptainer exec --bind /path/to/host/data:/path/to/container/data \ + /path/to/haddock3_image.sif \ + haddock3 your-docking-config.cfg + + +echo "HADDOCK3 Job Complete" +echo "Completed at: $(date)" diff --git a/usage-container/scripts/slurm_run_singularity.sh b/usage-container/scripts/slurm_run_singularity.sh new file mode 100644 index 000000000..e1034a330 --- /dev/null +++ b/usage-container/scripts/slurm_run_singularity.sh @@ -0,0 +1,34 @@ +#!/bin/bash + +#SBATCH --job-name=HADDOCK3-docking +#SBATCH --output=HADDOCK3_%j.out +#SBATCH --nodes=3 +#SBATCH --ntasks-per-node=120 +#SBATCH --mem=256GB +#SBATCH --partition=compute + +echo "Starting HADDOCK3 Docking Job" +echo "SLURM_JOBID = $SLURM_JOBID" +echo "SLURM_JOB_NODELIST = $SLURM_JOB_NODELIST" +echo "SLURM_NNODES = $SLURM_NNODES" +echo "SLURMTMPDIR = $SLURMTMPDIR" +echo "Date = $(date)" +echo "Hostname = $(hostname -s)" +echo "Working Directory = $(pwd)" +echo "Submit Directory = $SLURM_SUBMIT_DIR" + +# Load necessary environment (optional depending on your setup) +source /lustre/oneApi/setvars.sh +export OMP_NUM_THREADS=1 + +# Run HADDOCK3 via Apptainer +cd "${WORK_DIR}" + +# Ensure the working directory is set correctly +singularity exec --bind /path/to/host/data:/path/to/container/data \ + /path/to/haddock3_image.sif \ + haddock3 your-docking-config.cfg + + +echo "HADDOCK3 Job Complete" +echo "Completed at: $(date)"