Configuration¶

In order to host remote laboratories for your institution you will need to configure the LabDiscoveryEngine instance appropriately. The configuration will define which laboratories are available, in which local addresses they are hosted, their icons, their descriptions, their keywords and more.

Files and formats¶

The configuration is stored in various YML (YAML) files. This format was chosen for its readability and ease of use, and it is somewhat similar to JSON. The configuration system is designed to be simple for laboratory developers and administrators to use.

An example of a configuration set can be found in the tests/deployments/simple directory.

In the following sections we will describe the various configuration files.

configuration.yml¶

The configuration.yml file contains the main configuration of the LabDiscoveryEngine instance.

Although it is an YML file, in this case the variables inside are loaded as environment variables before the instance is run. Therefore, if you observe the source code, you will see that the environment variables that are accessed are often present and defined in this file.

The variables that this file contains normally are related to the instance as a whole or to the institution that is hosting the instance.

The main variables are the following:

Variable	Description	Example
`SECRET_KEY`	The secret key that this instance will use. Should be unique and not shared.	`ivTp3UApt7epzy0YzlNOEGirzKe1gHC4JQJc_rcuS2s`
`DEFAULT_LAB_VISIBILITY`	The default visibility of the laboratories. Can be `public` or `private`.	`public`
`INSTITUTION_LOGO`	The URL to the institution’s logo or image.	`https://labsland.com/pub/lde/labsland-logo-long.png`
`INSTITUTION_NAME`	The name of the institution.	`LabsLand`
`INSTITUTION_DESCRIPTION`	A brief description of the institution.	`LabsLand - The remote labs company.`
`INSTITUTION_URL`	The URL to the institution’s main page.	`https://labsland.com` \|

credentials.yml¶

The credentials.yml file contains the credentials for administrator and external users.

Administrators are those users that have full privileges over the instance. They can access any laboratory and have multiple privileges, such as creating new users. For security reasons administrators must always be defined in this file: administration privileges cannot be granted through the user’s database.

External users are mostly meant to be used by trusted external tools that access the instance, such as platforms that aggregate laboratories.

For security reasons no passwords are stored in plaintext. There is, however, a tool to set and change passwords. The tool can be invoked through: `lde credentials administrators change-password`.

laboratories.yml¶

The laboratories.yml file contains the configuration of the laboratories that are provided by the instance. Each laboratory is defined by a unique identifier and a set of properties.

An example is:

archimedes:
  display_name: Archimedes Lab # optional
  description: The Archimedes lab lets you experiment with buoyancy. # optional
  keywords:
    - physics
    - buoyancy
    - liquids
  category: Physics # optional
  max_time: 300 # optional, maximum time users can use the lab, in seconds
  image: https://labsland.com/pub/labs/file-cd0988-buoyancy_thumb.jpg # optional
  resources: # alternatively you can put them inline: dummy-1, dummy-2
    - arch-1
    - arch-2

Each laboratory has a unique identifier. In this case ‘archimedes’.

Then, various parameters:

Variable	Description
`display_name`	The name of the laboratory. This is the name that will be displayed to users.
`keywords`	Keywords associated to the laboratory that can be used for search and discovery.
`category`	The labs category to which this lab belongs.
`max_time`	Maximum time that users can use the lab, in seconds, in a single session.
`image`	Thumbnail for the lab.
`resources`	List of resources that provide this laboratory. These are the identifiers of each of the resources, which must match and be defined in the `resources.yml` file.

resources.yml¶

The resources.yml file contains the resources that provide the laboratories. A resource represents an instance of a laboratory. A laboratory may have several resources. For example, a FPGA laboratory may have various different copies of the FPGA remote lab. Each of these copies is a ‘resource’ and will be associated to the laboratory.

An example of a resource is:

orgchem-1:
  url: http://localhost:5100
  login: lde
  password: password
  features: ['feature2', 'feature4']

A resource is first identified by a unique identifier. In this case ‘orgchem-1’. These identifiers need to match the one in the laboratories.yml file used to identify it.