Contents of the file

The file contains configuration of packages that should be installed to be used by the application. It contains:

Specification of channels from which the packages will be downloaded
Specification of packages to be installed, including their requested version

Prerequisites

To use the environment configuration, the containsEnvironmentDescription option in appDefinition.json has to be set to true, and requiredTools set to ["micromamba"] - see Application Definition file structure description.

File name and format

The environment specification file should always have the same name - environment.yml and has to be placed in the root (main) directory of your application's repository. Otherwise, the system wouldn't be able to locate it.

The format of the file is Yaml, a commonly used text format for representing objects and configurations. When creating and editing the file, you must take care to follow the format rules - e.g. using special characters and whitespaces*, otherwise, the environment may not be initialized properly. To validate the Yaml structure, you can use on-line tools, like https://www.yamllint.com/. The full specification of the format can be found at https://yaml.org/spec.

*Note: Yaml doesn't allow for using tabs as indentation (see https://yaml.org/faq.html), be careful to use 2 or 4 spaces for this purpose instead of a tab.

Structure

Excerpt 1. shows the structure of the environment.yml file with the possible options described below. Note, that the indentation has to be coherent between the same levels and has to be realized with spaces, as tabs are not allowed by the Yaml format.

  # NOTE: Environment name is programmatically set - any 'name' field here will be ignored
  channels:
    - <channel-name-1>
    ...
    - <channel-name-n>

  dependencies:
    - <package-spec-1>
    ...
    - <package-spec-n>

Excerpt 1. Environment specification file structure.

The options are described below, with the required fields are marked with bold, others are optional.

channels - list of channels that should be used for downloading packages - see more in Conda channels documentation. Each channel name should be added following indentation and a dash. If not included, a default channel will be used. Note, that if you don't want to specify channels, remove the whole channels section - if the channels keyword is present, but no channels are listed, the default channel will not be activated and the environment configuration may fail.
dependencies - list of packages to be installed. Each package should contain at least the package name and should be added following indentation and a dash. Optionally, the package specification can contain also a version specification and/or channel - the full package specification having format: <channel_name>::<package_name><version_specification>, where:
- channel_name - use in case the dependency should be downloaded from different channel than the ones specified within the channel option.
- package_name - name of the package
- version_specification - in case a specific version of the package is required, specify using equality signs (e.g. =, <=, >)

Note, that the environment name property, which is described in the Conda documentation, is not required (if specified, it will be ignored) in the environment.yml file used by the EPISODES Platform, as the environment name is set programatically by the platform.

To use the PIP package manager, add it as one of the dependencies, and specify the other packages under in the following way:

  dependencies:
     ... 
     - pip
     - pip:
       - <pip-package-spec-1>
       ...
       - <pip-package-spec-n>

Excerpt 2. Fragment of environment specification file structure containing PIP packages

For a detailed description of the file format, please consult the Conda environment file documentation.

Examples

Below you will find two examples of the Environment specification file - first one (Excerpt 3), using minimum configuration (skipping optional information) - second using more complex package specification (Excerpt 4).

dependencies:
  - python>=3.11
  - numpy

Excerpt 3. Example environment.yml configuration - minimum specification

channels:
  - javascript
dependencies:
  - python>=3.9,<3.10
  - bokeh=2.4.2
  - conda-forge::numpy=1.21.*
  - nodejs=16.13.*
  - flask
  - pip
  - pip:
    - Flask-Testing

Excerpt 4. Example environment.yml configuration - more complex specification

Note, that Python has to be included explicitly, unless there is another package specified, that has Python as dependency.

Implementation details

Under the hood, the portal installation uses Micromamba, therefore, you can also consult the tool's documentation for more information.

Contents of the file

Prerequisites

File name and format

Structure

Examples

Back to top

Related Documents