damona 0.23.0

Overview

Damona is a conda-style package and environment manager built on top of Apptainer/Singularity containers. It lets you install bioinformatics (and other) tools as isolated containers, manage multiple versions side-by-side, and run them exactly like any other command-line tool — with no dependency conflicts and no root privileges required.

Think of Damona as conda for Singularity images: the same familiar create / activate / install workflow you already know, but with the rock-solid isolation and reproducibility that containers provide.

Why Damona?

Managing scientific software is notoriously painful:

• Conda environments break when incompatible packages are installed together.

• Raw Singularity/Apptainer requires verbose singularity exec invocations and manual management of image files.

• Docker is unavailable or restricted on most HPC clusters.

Damona solves all three problems at once:

Installation

Step 1 — Install Apptainer

Damona is a manager for Apptainer/Singularity images, so Apptainer must be present on your system first. Follow the official Apptainer installation guide, or — if you already use conda — install it with:

conda install -c conda-forge apptainer

Step 2 — Install Damona

pip install damona

Step 3 — Initialise Damona

Run damona once to create the configuration directory and shell helpers:

damona

Follow the on-screen instructions. To make the shell integration permanent, add one of the following lines to your shell start-up file:

bash — add to ~/.bashrc:

source ~/.config/damona/damona.sh

zsh — add to ~/.zshrc:

source ~/.config/damona/damona.zsh

fish — add to ~/.config/fish/config.fish:

source ~/.config/damona/damona.fish

Then open a new shell and run damona again. You should see the help screen:

Quick Start

The full workflow takes under a minute:

# 1. Create a named environment
damona create TEST

# 2. Activate it (installed tools go here)
damona activate TEST

# 3. Install a tool — container + wrapper created automatically
damona install fastqc:0.11.9

# 4. Use it just like any other command
fastqc --help

# 5. Rename or remove the environment when you're done
damona rename TEST --new-name prod
damona remove prod

For more examples see the User Guide.

# --- Prerequisites ---------------------------------------------------
# 1. Install Apptainer (once, system-wide or via your package manager).
#    On Debian/Ubuntu:
sudo apt-get install -y apptainer
#    Or follow https://apptainer.org/docs/admin/main/installation.html

# --- Python environment ----------------------------------------------
# 2. Create and activate a pyenv virtualenv with Python 3.10
pyenv install 3.10.14          # skip if already installed
pyenv virtualenv 3.10.14 damona-env
pyenv activate damona-env

# 3. Install Damona
pip install damona

# --- First-time initialisation ---------------------------------------
# 4. Run once to create the configuration directory and shell helpers
damona

# 5. Add the shell integration to your start-up file (bash example):
echo 'source ~/.config/damona/damona.sh' >> ~/.bashrc
source ~/.bashrc

# --- Install minimap2 ------------------------------------------------
# 6. Create and activate a Damona environment
damona create my-env
damona activate my-env

# 7. Install minimap2 — the container is downloaded automatically
damona install minimap2:2.24.0

# 8. Use it like any other command
minimap2 --version

Motivation

Conda/Bioconda is excellent for distributing pre-compiled scientific software, but dependency conflicts are a real-world problem: installing one package can silently break another, and rebuilding environments is time-consuming.

Singularity/Apptainer solves the isolation problem perfectly — each image is self-contained and reproducible — but using it directly requires verbose singularity exec commands and manual bookkeeping of image files and wrapper scripts.

Damona bridges the gap: it wraps Singularity images in the familiar conda-style environment model so that containers are as easy to install, activate, and use as conda packages, while retaining full container isolation and reproducibility.

Damona was originally developed for the Sequana project, but it is completely general-purpose and can be used to distribute any Singularity-compatible software.

Commands (Full CLI Reference)

Run damona --help to see all available commands:

Environment management:
  create      Create a new environment
  remove      Remove an environment and all its binaries.
  rename      Rename an existing environment.
  env         List all environments with their size and binary counts.
  activate    Activate a damona environment.
  deactivate  Deactivate the current Damona environment.

Package management:
  install     Download and install an image and its binaries into the active environment.
  uninstall   Uninstall a binary or an image from an environment.
  clean       Find and remove orphaned images and binaries across all environments.
  export      Export an environment as a YAML file or a tar bundle.
  info        Show images and binaries installed in an environment.

Registry:
  search      Search the registry for a container image or binary.
  list        List all containers available in the local registry.
  stats       Show registry statistics and local installation summary.

Developer tools:
  check       Check that all binaries in a built image are functional.
  build       Build a Singularity image from a local recipe, a Damona recipe, or a Docker image.
  catalog     Show a developer overview: latest version, size, and base image for every container.

For command-specific help (e.g. install):

damona install --help

damona env

damona create TEST

damona env

damona activate TEST
damona env        # confirms TEST is active

damona deactivate TEST

damona activate base
damona activate TEST
damona deactivate           # removes TEST (last activated)
damona deactivate base      # removes base by name

damona install fastqc:0.11.9

damona info TEST

damona search PATTERN

damona search fastqc --registry damona

damona create test1
damona activate test1
damona install fastqc:0.11.9   # reuses the cached image

damona activate base
damona activate test1

Contributors

Maintaining Damona would not have been possible without users and contributors. Each contribution has been an encouragement to pursue this project. Thanks to all:

Changelog

The full, up-to-date changelog lives in CHANGELOG.rst and is rendered in the documentation.

From version 0.16 onwards, new software and versions are no longer listed there; only changes to the code itself are recorded. The complete list of available software is obtained with:

damona list