Publishing Che-Theia plug-ins

Che-Theia plug-in registries

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

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

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

Sample plug-in definition

  {
    "description": "This extension provides a live preview, syntax highlighting and snippets for the AsciiDoc format using Asciidoctor flavor.",
    "displayName": "AsciiDoc support",
    "id": "joaompinto/vscode-asciidoctor/latest",
    "links": {
      "self": "/v3/plugins/joaompinto/vscode-asciidoctor/latest/"
    },
    "name": "vscode-asciidoctor",
    "publisher": "joaompinto",
    "type": "VS Code extension",
    "version": "latest"
  }

This definition contains a links section that points to the complete plug-in description (meta.yaml).

Sample plug-in meta.yaml file

publisher: joaompinto
apiVersion: v2
version: latest
type: VS Code extension
name: vscode-asciidoctor
displayName: AsciiDoc support
title: AsciiDoctor Plugin.
description: This extension provides a live preview, syntax highlighting, and snippets
  for the AsciiDoc format using Asciidoctor flavor.
icon: https://www.eclipse.org/che/images/logo-eclipseche.svg
category: Language
repository: https://github.com/asciidoctor/asciidoctor-vscode
firstPublicationDate: '2019-09-09'
spec:
  extensions:
    - https://marketplace.visualstudio.com/_apis/public/gallery/publishers/joaompinto/vsextensions/asciidoctor-vscode/2.7.6/vspackage
latestUpdateDate: "2019-12-09"

For more details about the meta.yaml structure, see Che-Theia plug-in metadata.

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 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.

To use plug-ins from a custom registry, follow one of the following methods:

Specify a link to the plug-in in the configuration of a workspace. See Adding a plug-in into a workspace using the workspace configuration.
Replace the default official registry with a custom one in your Che instance. To do so, 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 to your registry from the official registry.

Additional resources

Che-Theia plug-in metadata

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

Submit a pull request to the plug-in registry repository containing the meta.yaml file of the plug-in in the v3/plugins/<plugin-publisher>/<plugin-name>/<plugin-version>/ directory.
Example 1. Location of meta.yaml file for the SonarLint Che-Theia plug-in
v3/plugins/sonarsource/sonarlint-vscode/0.0.1/meta.yaml

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

You can add Che-Theia plug-in into the Che-Theia IDE in three ways:

At Theia runtime
By configuring a workspace devfile
By preparing shareable devfile

Adding a plug-in at Theia 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.

Procedure

Run the Deploy Plugin by Id command, and specify the ID of the plug-in to add to the workspace. A plug-in ID can be:
A local directory with plug-ins
Che loads all the plug-in binaries (.theia files) in the specified directory.
Example 2. Adding the local directory /home/theia/plugins/

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.
Example 3. VS Code extension link for the XML language server plug-in

vscode:extension/redhat.vscode-xml
Link to plug-in binaries (.theia files)
Can be both HTTP and HTTPS.
Example 4. Link to plug-in binaries

https://domain.net/path/plugin.theia

Verification steps

Open the Plugins panel (View > Plugins in the main menu) and search for the plug-in in the list.

Adding a plug-in by configuring a workspace devfile

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

Procedure

Navigate to the Workspaces tab in the dashboard.
Select the workspace to which you want to add the plug-in.
Switch to the Devfile tab, and find the components section.

To add plug-ins, append your plugin component to the components section. A record has the following format:

components:
  - type: chePlugin
    reference: >-
      <registry-base-uri>/v3/plugins/<plugin-publisher>/<plugin-name>/<plugin-version>

Example 5. chePlugin reference URLs pointing to a plug-in meta.yaml

https://custom-registry/v3/plugins/custom-plugin-name/0.0.1/
https://raw.githubusercontent.com/username/che-custom-plugins/master/v3/plugins/custom-plugin-name/0.0.1/meta.yaml

Adding a plug-in by preparing shareable devfile

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.

Procedure

Create a devfile with the plug-in development environment and share it with reviewers to provide them with the same environment. Reviewers then must build and run the plug-in to test it, using a script or a set of instructions on how to include the build in the plug-in repository.
Share with reviewers factory link with a URL to a repository with devfile or a direct URL to content of the devfile.

Example 6. Factory URL pointing to a repository containing a devfile

https://che-host:che-port/f?url=https://github.com/eclipse/che

Example 7. Factory URL pointing to a devfile

https://che-host:che-port/f?url=https://raw.githubusercontent.com/eclipse/che/master/devfile.yaml
The reviewer starts a workspace by opening a link where they are able to starts 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.

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 circumstances 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 and request for a particular plug-in in their workspace configuration.

Set the memoryLimit and/or memoryRequest for devfile component 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 8. Limiting RAM use for a plug-in

For the YAML language server plug-in, sets the RAM limit to 768 mebibytes (1073741824 bytes) and RAM request to 500 megabytes:

components:
  - id: redhat/vscode-yaml
    type: chePlugin
    memoryLimit: 768mi
    memoryRequest: 500M

Example 9. Limiting CPU use for a plug-in

For the YAML language server plug-in, sets the CPU limit to 1.5 cores and CPU request to 500 millicores:

components:
  - id: redhat/vscode-yaml
    type: chePlugin
    cpuLimit: 1.5
    cpuRequest: 500m