Installing Metasmith#

Important

Metasmith does not need to be installed again on remote machines. To execute a workflow remotely, deploy an agent using your local installation.

Prerequisites#

Operating System#

Linux and MacOS running on x86_64 (Intel/AMD CPUs) or arm64 (Apple silicon) architectures are supported.

Windows users can use either WSL, or Docker (see installation instructions below).

Tip

You can check your OS and CPU architecture with:

UNIX Terminal#
$ uname -s -m

Which should print “Linux”/”Darwin” and “amd64”/”arm64” if your system is supported.

Installation#

Metasmith is available through multiple channels. Pick one of the following.

Conda#

Conda is a package manager that both provides a distribution channel and automates the install of Metasmith. Alternatively, we recommend mamba, which is a significantly more performant drop-in replacement for conda.

Install Mamba

Install Conda

Terminal#
$ mamba create -n msm_env -c hallamlab -c bioconda metasmith
$ mamba activate msm_env
(msm_env)$ msm
expected output:#
metasmith v#.#.#
https://github.com/hallamlab/metasmith
...

Docker#

Warning

Experimental feature

Docker is a runtime for software packaged into containers along with nearly all of their dependencies. Containers are “pulled” as “images” which can then be executed.

Install Docker Desktop

Terminal#
$ docker run \
    --platform=linux/amd64 \
    -it --rm \
    -u $(id -u):$(id -g) \
    --mount type=bind,source="${TMPDIR-/tmp}",target="/tmp" \
    --mount type=bind,source="$(pwd -P)",target="/ws" \
    --workdir="/ws" \
    quay.io/hallamlab/metasmith \
    msm
expected output:#
...
metasmith v#.#.#
https://github.com/hallamlab/metasmith
...

Apptainer#

Apptainer is an alternative to Docker designd for research computing on grid infrastructure. It is only available for Linux machines.

We recommend installing via your system package manager (e.g. sudo apt install apptainer on Debian/Ubuntu) or by following Apptainer’s official install docs. This gives you a setuid Apptainer, which metasmith deploys as a single .sif image.

Warning

The conda-forge / mamba Apptainer build is not reliable for deployment. Because it lacks the setuid starter-suid helper, it can only build and run the container rootfs through unprivileged user namespaces. Many recent Linux distributions restrict these by default — e.g. Ubuntu 23.10 and later ship kernel.apparmor_restrict_unprivileged_userns=1, under which smith.Deploy() fails while unpacking the sandbox with FATAL: ... Failed to create container process: Operation not permitted.

On a host where unprivileged user namespaces are blocked, choose one of:

  • install a system (setuid) Apptainer via your package manager (preferred), or

  • enable unprivileged user namespaces: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 (persist under /etc/sysctl.d/), or

  • use the Docker runtime instead.

HPC clusters that provide a setuid Apptainer module (e.g. via module load) are unaffected. Where the conda-forge build does work, metasmith unpacks each image to a sandbox directory at deploy time, roughly doubling the on-disk footprint per cached image.

Install Apptainer

Terminal#
$ apptainer run \
    --bind "${TMPDIR-/tmp}":/tmp,"$(pwd -P)":/ws \
    --workdir /ws \
    docker://quay.io/hallamlab/metasmith \
    msm
expected output:#
...
metasmith v#.#.#
https://github.com/hallamlab/metasmith
...

Next Steps#

Try a tutorial