Docker container orchestration

docker-container-orchestration

Summary

Run platform-dependent bioinformatics tools (like msconvert) inside containerized Docker environments to ensure reproducibility and avoid native OS dependencies. This skill is essential when the target tool has restrictive licensing or vendor-specific requirements that complicate native installation.

When to use

Your analysis requires msconvert or another ProteoWizard tool on macOS, but native installation is infeasible or licensing-restricted. You need to convert vendor raw mass spectrometry files (.raw) to the open mzML format without installing ProteoWizard directly on your system.

When NOT to use

• msconvert is already natively installed and working on your system (native execution is simpler and faster than containerization).
• You are working on Windows/PC where ProteoWizard can be installed directly from the ProteoWizard repository without Docker.
• Your raw files are already in open formats (mzML or imzML) and do not require conversion.

Inputs

• Directory containing vendor .raw mass spectrometry files
• Docker installation and Docker daemon running
• Raw file path string passed to iw_utils.RAW_to_mzML()

Outputs

• mzML format files converted from vendor raw data
• Docker container execution logs and conversion status

How to apply

First, verify Docker is installed and running on your system. Pull the pre-built Docker image containing msconvert: docker pull chambm/pwiz-skyline-i-agree-to-the-vendor-licenses. When imzML Writer invokes raw-to-mzML conversion (via iw_utils.RAW_to_mzML(raw_data_path)), the framework automatically detects the Docker environment and routes the msconvert call through the containerized image instead of seeking a native binary. The container receives the raw file path, applies default peak-picking settings, and writes mzML output back to the host filesystem. Monitor conversion progress in the GUI or logs; verify the mzML file is generated with correct XML structure and file naming.

Related tools

• Docker (Container runtime that downloads, manages, and executes the pwiz-skyline Docker image containing msconvert and its dependencies) — https://www.docker.com/products/docker-desktop/
• msconvert (ProteoWizard utility that runs inside the Docker container to convert vendor raw mass spectrometry files to mzML format with peak-picking) — https://proteowizard.sourceforge.io/download.html
• imzML Writer (Python framework that detects Docker availability on macOS and orchestrates Docker-containerized msconvert calls for RAW to mzML conversion) — https://github.com/VIU-Metabolomics/imzML_Writer
• chambm/pwiz-skyline-i-agree-to-the-vendor-licenses (Pre-built Docker image hosted on Docker Hub containing msconvert and ProteoWizard libraries with vendor license agreements pre-accepted) — https://hub.docker.com/r/chambm/pwiz-skyline-i-agree-to-the-vendor-licenses

Examples

docker pull chambm/pwiz-skyline-i-agree-to-the-vendor-licenses; import imzml_writer.imzML_Writer as iw; iw.gui()

Evaluation signals

• Docker image is successfully pulled and appears in docker images output with tag chambm/pwiz-skyline-i-agree-to-the-vendor-licenses.
• mzML output files are generated in the expected directory with correct naming (matching input .raw filenames with .mzML extension).
• mzML files have valid XML structure (verified by opening with XML parser or imzML-compatible software).
• Conversion completion is logged without Docker runtime errors or permission failures.
• File size of mzML output is consistent with input raw file size and expected centroid/profile mode data volume.

Limitations

• Docker must be running and the container image must be downloaded; initial setup adds latency compared to native tool installation.
• On macOS, Docker Desktop requires additional system resources (CPU, memory, disk) to maintain a running container; some systems may experience performance degradation.
• Vendor license agreements embedded in the Docker image apply automatically; users implicitly accept them by pulling and running the image.
• File path handling between host and container must be explicitly mapped; incorrect mount paths will cause conversion to fail silently or report 'file not found' errors.
• The image is maintained by a third party (chambm); updates or deprecation are outside imzML Writer's control.

Evidence

• [readme] On Mac, you can still run msconvert via a docker image. First, install Docker: https://www.docker.com/products/docker-desktop/: "On Mac, you can still run msconvert via a docker image. First, install Docker"
• [readme] Similarly, imzML Writer will prompt you to download the docker image the first time you try to call it. If you'd like to do this in advance you can open Terminal.app and run the command: docker pull chambm/pwiz-skyline-i-agree-to-the-vendor-licenses: "imzML Writer will prompt you to download the docker image the first time you try to call it. If you'd like to do this in advance you can open Terminal.app and run the command: docker pull"
• [methods] on Mac, msconvert runs via a Docker image (chambm/pwiz-skyline-i-agree-to-the-vendor-licenses) that is downloaded on demand: "on Mac, msconvert runs via a Docker image (chambm/pwiz-skyline-i-agree-to-the-vendor-licenses) that is downloaded on demand"
• [methods] Invoke iw_utils.RAW_to_mzML(raw_data_path) on the directory containing the .raw file, which internally calls msconvert with default peakPicking settings to convert vendor raw data to mzML format.: "Invoke iw_utils.RAW_to_mzML(raw_data_path) on the directory containing the .raw file, which internally calls msconvert with default peakPicking settings"