Che-Theia plug-in registries

A plug-in registry is a simple service that hosts information (metadata) about the plug-ins.

To retrieve a full list of plug-ins hosted in a registry, navigate to the following address: <registry-base-uri>/plugins/index.json.

Each plug-in item in the list is represented by a JSON definition:

Sample plug-in definition
{
    "id": "che-dummy-plugin",
    "version": "0.0.1",
    "type": "Che Plugin",
    "name": "Che Samples Hello World Plugin",
    "description": "A hello world theia plug-in wrapped into a Che Plug-in",
    "links": {
        "self": "/plugins/che-dummy-plugin/0.0.1/meta.yaml"                  (1)
 }
1 Points to a more complete plug-in description (meta.yaml).
Sample plug-in meta.yaml file
id: che-dummy-plugin
version: 0.0.1
type: Che Plugin
name: Che Samples Hello World Plugin
title: Che Samples Hello World Plugin
description: A hello world theia plug-in wrapped into a Che Plug-in
icon: https://www.eclipse.org/che/images/logo-eclipseche.svg
url: https://github.com/ws-skeleton/che-dummy-plugin/releases/download/untagged-8f3e198285a2f3b6b2db/che-dummy-plugin.tar.gz (1)
1 Points to the plug-in configuration. Typically, it is a TAR archive with the plug-in YAML file. It is also possible to have a link to the raw content of a plug-in YAML file.

For a VS Code extension, the url field is replaced with an attributes section.

Sample attributes section of meta.yaml
attributes:
extension: "vscode:extension/extension.id"             (1)
container-image: "my.docker.registry/remote-theia:tag" (2)
1 VS Code extension ID with a vscode:extension/ prefix
2 Points to a container image in which the extension runs. Note that the image should contain an appropriate Node.js version with installed dependencies for Che-Theia remote plug-ins.

For more details about the meta.yaml structure, see [che-theia-plug-in-metadata_what-is-a-che-theia-plug-in].

Official plug-in registry

The official Che plug-in registry is at che-plugin-registry.openshift.io. By default, the Che dashboard shows editors and plug-ins from this registry.

The source is located at link: github.com/eclipse/che-plugin-registry.

Custom plug-in registries

For more information about setting up a custom registry, see the description of the official registry repository.

There are two ways of using plug-ins from a custom registry:

  • Specify a link to the plug-in in the configuration of a workspace. See Adding a plug-in into a workspace via configuration.

  • Replace the default official registry with a custom one in your Che instance. To do that, set the PLUGIN_REGISTRY_IMAGE environment variable in your Che configuration. Note that plug-ins from the official registry are not available from the dashboard interface. To include them, add references into your registry from the official registry.

Additional resources

Adding a Che-Theia plug-in to the Che plug-in registry

To have a Che-Theia plug-in available in the default Che plug-in registry, submit a pull request to the registry GitHub repository.

Prerequisites

  • Che-Theia plug-in definition file: meta.yaml

Procedure

  1. Submit a PR with the meta.yaml file of your Che-Theia plug-in in the plugins/<your-plug-in-id>/<version>/ directory to the Che plug-in registry GitHub repository at che-plugin-registry.

    For example, SonarLint Che-Theia plug-in is located in the plugins/org.eclipse.che.vscode-sonarlint/0.0.1/meta.yaml file.

After the new Che-Theia plug-ins are added and merged into the repository, the list of available plug-ins in the registry is updated.

Additional resources

Adding a Che-Theia plug-in into a workspace

There are three ways to add a Che-Theia plug-in into the Che-Theia IDE:

  • Using the Che-Theia dashboard

  • By configuring a workspace

  • At runtime

Adding a plug-in through the dashboard

  1. Navigate to the Workspaces tab in the dashboard.

  2. Select the workspace to which you want to add the plug-in.

  3. In Workspace > <workspace-name> window, click the Plugins tab, and select the required plug-ins.

    adding plug ins in dashboard
    Figure 1. Adding plug-ins through the dashboard

Adding a plug-in by configuring a workspace

This method is useful when you need to add plug-ins from a non-default registry.

  1. Navigate to the Workspaces tab in the dashboard.

  2. Select the workspace to which you want to add the plug-in.

  3. Switch to the Config tab, and find the attributes.plugins section.

    adding plug ins in workspace configuration
    Figure 2. Adding plug-ins by configuring a workspace

    Plug-ins are separated by commas (,).

  4. To add plug-ins, append new records after the separator. A record has the following format:

     <registry-base-uri>/plugins/<plugin-name>:<version>

    Examples:

    • https://custom-registry/plugins/org.name.plugin.theia:1.0.0

    • https://raw.githubusercontent.com/username/che-custom-plugins/master/plugins/org.name.plugin.theia:0.0.1

Adding a plug-in at runtime

This method adds a plug-in to an already running workspace. The plug-in is not added permanently; it is removed when the workspace stops. This is a good method to test a plug-in without affecting the permanent workspace configuration.

  1. Run the Deploy Plugin by Id command, and specify the ID of the plug-in that you want to add to the workspace. A plug-in ID can be:

    • A local directory with plug-ins. All the plug-in binaries (.theia files) in the specified directory would be loaded. Example: local-dir:///home/theia/plugins/.

    • VS Code extension link. To obtain the link, go to the VS Code marketplace, find the needed extension, copy its ID, and append the ID to the vscode:extension/ prefix.

      For example, for the XML language server plug-in, it is: vscode:extension/redhat.vscode-xml.

    • Link to plug-in binaries (.theia files). Can be both HTTP and HTTPS. Example: https://domain.net/path/plugin.theia.

To check if the plug-in loaded successful, open the Plugins panel (View > Plugins in the main menu) and search for the plug-in in the list.

Sharing your Che-Theia plug-in with a factory

This section describes how to use a Che-Theia factory to share a plug-in in development environment with other users.

Sharing a factory with a plug-in development environment

This approach brings an advantage of other users being able to contribute to the development, provided they have write access to the repository with the plug-in.

  1. Create a factory with the plug-in development environment, and share it. The reviewers get the exact same environment. They must then build and run the plug-in to test it (a script or instructions on how to build should be included in the plug-in repository).

  2. The reviewer should start a hosted plug-in instance and specify the path to the plug-in project inside the workspace. For instructions on how to start a hosted instance of Che-Theia for plug-in testing, see [testing-che-theia-plug-ins_extending-che].

  3. To make the reviewers' work easier, it is possible to invoke a command to build the plug-in after the loading of the factory is completed. For more details, see the factory documentation.

Sharing a factory with plug-in configuration

This method provides a workspace with a ready-to-use plug-in. The author of the plug-in must host the plug-in binaries in a custom registry.

  1. Create a factory.

  2. Go to the factory details, and scroll to the Configuration section.

  3. Add the plug-in to the workspace.attributes.plugins field. The format is the same as described in Adding a Che-Theia plug-in into a workspace.

    sharing plug in with factory

  4. Share the factory link.

Only accept factories from trusted sources. Malicious factories can potentially steal data that is accessible from within your workspace.
Additional resources

Overriding RAM of a Che-Theia plug-in

Sometimes, a plug-in consumes more memory than what has been allocated to it by the plug-in author or Che defaults. An example of such a case is the use of a language server with a project that has many source files (&8gt; 10 000). RAM consumption in such circumstanes needs to be tuned, otherwise the machine that runs the Che workspaces kills the process with an out-of-memory error (OOM) error.

Procedure

Users can override the RAM limit for a particular plug-in in their workspace configuration.

  • Set the workspace attribute sidecar.<plugin ID>.memory_limit to 1000M or 10Gi, or any other value formatted as a number and a unit (b, k, ki, m, mi, g, gi). When no unit is specified, the number is in bytes.

Using this notation, units that contain the character i, denote a number that is of the power 2, such as 1024 (as opposed to numbers that use a power of 10, such as 1000).
Example 1. Limiting RAM use for a plug-in

Example of an attribute that sets the RAM limit for the YAML language server plug-in to 768 mebibytes (1073741824 bytes):

"attributes": {
   "Sidecar.redhat.vscode-yaml.memory_limit": "768mi"
}
Tags: