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

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 v3/plugins/<your-plugin-group>/<your-plugin-name>/<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 v3/plugins/sonarsource/sonarlint-vscode/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

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

  • 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 devfile

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 Devfile tab, and find the components section.

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

    Plug-ins are added in YAML format as array elements in the components section.

  4. To add plug-ins, append this lines to the components section. A record has the following format:

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

    Reference URL examples:

    • 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 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 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. The reviewer 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.

  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.

    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 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 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) and RAM request to 500 megabytes:

components:
  - id: redhat/vscode-yaml/0.8.0
    type: chePlugin
    memoryLimit: 768mi
    memoryRequest: 500M
Example 2. Limiting CPU use for a plug-in

Example of an attribute that sets the CPU limit for the YAML language server plug-in to 1.5 cores and CPU request to 500 millicores:

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