diff --git a/README.md b/README.md index 5bb4cee0b..a9a122358 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, building 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/README.md b/usage-container/README.md new file mode 100644 index 000000000..24cc761c3 --- /dev/null +++ b/usage-container/README.md @@ -0,0 +1,106 @@ +# Container workflow for HADDOCK3 + +Build, run, and extend an **Apptainer/Singularity** container for HADDOCK3. [**HADDOCK3**](https://doi.org/10.1021/acs.jcim.5c00969)(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 +# For the latest release +docker pull ghcr.io/haddocking/haddock3:latest + +# Or pin to a specific release for reproducibility +docker pull ghcr.io/haddocking/haddock3:2025.8.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.8.0 + +# Or, build with Singularity +singularity build haddock3_mpi.sif docker://ghcr.io/haddocking/haddock3:2025.8.0 + ``` +**Note:** Refer to the [**usage.md**](https://github.com/haddocking/haddock3/blob/main/usage-container/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/haddocking/haddock3.git + cd haddock3/usage-container/usage-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 + ├── README.md # Overview + + ``` + +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/haddocking/haddock3/blob/main/usage-container/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 + ``` + + +## 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/haddocking/haddock3/blob/main/usage-container/docs/usage.md) – Detailed usage and instructions to run Apptainer. + + +--- + +*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..fdddb13a7 --- /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: `haddock3_cpu-mpi.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)"