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.
{
"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
).
meta.yaml
filepublisher: 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.
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.
-
Che-Theia plug-in definition file:
meta.yaml
-
Submit a pull request to the plug-in registry repository containing the
meta.yaml
file of the plug-in in thev3/plugins/<plugin-publisher>/<plugin-name>/<plugin-version>/
directory.Example 1. Location ofmeta.yaml
file for the SonarLint Che-Theia plug-inv3/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.
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.
-
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-invscode:extension/redhat.vscode-xml
- Link to plug-in binaries (
.theia
files) -
Can be both HTTP and HTTPS.
Example 4. Link to plug-in binarieshttps://domain.net/path/plugin.theia
-
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.
-
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-inmeta.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.
-
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 devfilehttps://che-host:che-port/f?url=https://github.com/eclipse/che
Example 7. Factory URL pointing to a devfilehttps://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.
Users can override the RAM limit and request for a particular plug-in in their workspace configuration.
-
Set the
memoryLimit
and/ormemoryRequest
for devfile component to1000M
or10Gi
, 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).
|
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
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