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.

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

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

  1. Navigate to the Workspaces tab in the dashboard.

  2. Select the plug-in destination workspace.

  3. Switch to the Devfile tab, and find the components section.

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

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

  2. 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/#https://github.com/eclipse/che

    Example 7. Factory URL pointing to a devfile

    https://che-host:che-port/#https://raw.githubusercontent.com/eclipse/che/master/devfile.yaml

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