Skip to main content

Delivering software with conda

Conda is a cross-platform, cross-language package and environment manager that simplifies dependency management for scientific software. Platforma supports packaging Conda environments, making it easy to distribute complex software stacks with all their dependencies.

What is Conda?​

Conda is both a package manager and an environment manager that:

  • Handles dependencies across multiple languages (Python, R, C/C++, etc.)
  • Works consistently across Linux, macOS, and Windows
  • Provides access to thousands of pre-built packages from channels like conda-forge and bioconda
  • Creates isolated environments that prevent dependency conflicts

For Platforma, Conda is particularly useful for packaging bioinformatics tools that have complex dependency chains or require specific versions of system libraries.

Conda Environment Specification​

Conda environments are defined using a conda-spec.yaml file in your package root. This file specifies:

  • Channels — Where to download packages from (e.g., conda-forge, bioconda)
  • Dependencies — List of packages to install in the environment

Example conda-spec.yaml:

channels:
  - bioconda
  - conda-forge

dependencies:
  - anarci

During the build process, Package Builder:

  1. Creates a Conda environment from your conda-spec.yaml
  2. Freezes the environment to a frozen-spec.yaml with exact versions of installed software
  3. Packages the entire environment (software you need and all its dependencies) into platform-specific archives

Package Configuration​

To package Conda software, define a conda entrypoint in your package.json:

{
  "block-software": {
    "entrypoints": {
      "main": {
        "conda": {
          "artifact": {
            "roots": {
              "linux-x64": "./build/linux-x64",
              "linux-aarch64": "./build/linux-aarch64",
              "macosx-x64": "./build/macosx-x64",
              "macosx-aarch64": "./build/macosx-aarch64"
            }
          },
          "cmd": ["ANARCI"]
        }
      }
    }
  }
}

Configuration Options​

  • roots — Platform-specific directories where built environments are located
  • cmd — Command to execute (typically the name of a tool installed in the Conda environment)

The command specified in cmd should be available in the Conda environment's PATH after installation. Package Builder automatically includes micromamba in the archive, which is used to activate the environment and run commands on the Platforma backend.

Automatic Docker Image Generation​

Conda software automatically generates Docker images alongside binary archives. The Docker image:

  • Uses the frozen environment specification for reproducible builds
  • Includes micromamba for environment management
  • Sets up the Conda environment at build time
  • Uses micromamba run --prefix /conda-env as the entrypoint

This means your Conda software is available both as:

  1. Binary archive — For direct execution on compatible platforms
  2. Docker image — For containerized execution (automatically generated)

The Platforma backend will automatically choose the appropriate execution method based on what's available.

Example Projects​

To ease conda environments build, we created a special repository, that already has all required preparations to build the software using Github CI: all packages mentioned in this repository are get built into archives and docker images, uploaded into official Platforma repositories and can be used in platforma blocks.

See working examples in the software-conda repository:

  • Empty conda package — Minimal example with no dependencies. This is an example just to see the structure: this package has no meaning in a real life application.
  • ANARCI — real packaging of the bioinformatics tool.

These examples demonstrate the complete setup, including conda-spec.yaml configuration and package.json entrypoint definitions.

Advanced topics​

While conda software packaging settings described above cover most of the cases, sometimes you might need more flexibility and freedom.

Here are examples of cases, when you may need advanced software build configuration:

  • you faced some specific issues of micromamba used for conda software execution;
  • you develop software packages for custom private software registry of your company.

Micromamba​

Platforma uses micromamba to manage Conda environments. Micromamba is a fast, lightweight Conda-compatible package manager that doesn't require Python and is ideal for containerized environments.

By default, Package Builder uses micromamba version 2.3.2-0. To use a different version, specify it in your artifact configuration:

{
  "block-software": {
    "entrypoints": {
      "main": {
        "conda": {
          "artifact": {
            "micromamba-version": "2.3.2-0",
            "roots": {
              "linux-x64": "./build/linux-x64"
            }
          },
          "cmd": ["ANARCI"]
        }
      }
    }
  }
}

The specified micromamba version will be:

  • Downloaded and bundled with your Conda environment in binary archives
  • Used in automatically generated Docker images
  • Used by Platforma backend to activate and run your Conda environment

Registry Customization​

By default, software packages are published to the platforma-open registry. You can customize the registry in several ways:

Option 1: Specify registry name in artifact configuration

{
  "block-software": {
    "entrypoints": {
      "main": {
        "conda": {
          "artifact": {
            "registry": "my-custom-registry",
            "roots": {
              "linux-x64": "./build/linux-x64"
            }
          },
          "cmd": ["ANARCI"]
        }
      }
    }
  }
}

Option 2: Configure registry with custom URLs

You can define registry settings in your package.json or via environment variables. For a registry named my-custom-registry, you can set:

  • PL_REGISTRY_MY_CUSTOM_REGISTRY_UPLOAD_URL — Where to upload packages (e.g., s3://my-bucket/software/)
  • PL_REGISTRY_MY_CUSTOM_REGISTRY_DOWNLOAD_URL — Public URL for downloading packages (e.g., https://software.example.com/)

Option 3: Use registry object in artifact configuration

{
  "block-software": {
    "entrypoints": {
      "main": {
        "conda": {
          "artifact": {
            "registry": {
              "name": "my-custom-registry",
              "downloadURL": "https://software.example.com/",
              "storageURL": "s3://my-bucket/software/"
            },
            "roots": {
              "linux-x64": "./build/linux-x64"
            }
          },
          "cmd": ["ANARCI"]
        }
      }
    }
  }
}

Environment variables take precedence over configuration in package.json, allowing you to override registry settings without modifying code.