Chapter 4. Customizing developer environments

Red Hat CodeReady Workspaces provides a default web IDE for workspaces: Che-Theia. It is based on Eclipse Theia. It is a slightly different version than the plain Eclipse Theia one because there are functionalities that have been added based on the nature of the Red Hat CodeReady Workspaces workspaces. This version of Eclipse Theia for CodeReady Workspaces is called Che-Theia.

You can extend the IDE provided with Red Hat CodeReady Workspaces by building a Che-Theia plug-in. Che-Theia plug-ins are compatible with any other Eclipse Theia-based IDE.

4.1.2.1. Client-side and server-side Che-Theia plug-ins

The Che-Theia editor plug-ins let you add languages, debuggers, and tools to your installation to support your development workflow. Plug-ins run when the editor completes loading. If a Che-Theia plug-in fails, the main Che-Theia editor continues to work.

Che-Theia plug-ins run either on the client side or on the server side. This is a scheme of the client and server-side plug-in concept:

Figure 4.2. Client and server-side Che-Theia plug-ins

The same Che-Theia plug-in API is exposed to plug-ins running on the client side (Web Worker) or the server side (Node.js).

Che-Theia plug-in metadata is information about individual plug-ins for the plug-in registry.

The Che-Theia plug-in metadata, for each specific plug-in, is defined in a meta.yaml file.

The che-plugin-registry repository contains .

apiVersion: v2
category: Other
description: Che Plugin with che-machine-exec service to provide creation terminal or tasks for Red Hat CodeReady Workspaces workspace containers
displayName: CodeReady Workspaces machine-exec Service
firstPublicationDate: "2019-12-02"
icon: https://www.eclipse.org/che/images/logo-eclipseche.svg
name: che-machine-exec-plug-in
publisher: eclipse
repository: https://github.com/eclipse/che-machine-exec/
title: Che machine-exec Service Plugin
type: Che Plugin
version: 7.5.1
spec:
  endpoints:
   -  name: "che-machine-exec"
      public: true
      targetPort: 4444
      attributes:
        protocol: ws
        type: terminal
        discoverable: false
        secure: true
        cookiesAuthEnabled: true
  containers:
   - name: che-machine-exec
     image: "quay.io/eclipse/che-machine-exec:7.5.1"
     ports:
       - exposedPort: 4444

apiVersion: v2
category: Language
description: This extension provides a live preview, syntax highlighting and snippets for the AsciiDoc format using Asciidoctor flavor
displayName: AsciiDoc support
firstPublicationDate: "2019-12-02"
icon: https://www.eclipse.org/che/images/logo-eclipseche.svg
name: vscode-asciidoctor
publisher: joaompinto
repository: https://github.com/asciidoctor/asciidoctor-vscode
title: AsciiDoctor Plug-in
type: VS Code extension
version: 2.7.7
spec:
  extensions:
  - https://github.com/asciidoctor/asciidoctor-vscode/releases/download/v2.7.7/asciidoctor-vscode-2.7.7.vsix

When a user is starting a workspace, the following procedure is followed:

Figure 4.3. Che-Theia plug-in lifecycle

Before a CodeReady Workspaces workspace is launched, CodeReady Workspaces master starts containers for the workspace:

Che-Theia plug-in lifecycle:

Developer workspaces in Red Hat CodeReady Workspaces provide all dependencies needed to work on a project. The application includes the dependencies needed by all the tools and plug-ins used.

There are two different ways a Che-Theia plug-in can run. This is based on the dependencies that are needed for the plug-in: embedded (or local) and remote.

4.1.5.1. Embedded (or local) plug-ins

The plug-in does not have specific dependencies - it only uses a Node.js runtime, and it runs in the same container as the IDE. The plug-in is injected into the IDE.

Examples:

• Code linting
• New set of commands
• New UI components

To include a Che-Theia plug-in as embedded, define a URL to the plug-in binary file (the .theia archive) in the meta.yaml file. In the case of a VS Code extension, provide the extension ID from the Visual Studio Code marketplace (see Using a Visual Studio Code extension in CodeReady Workspaces).

When starting a workspace, CodeReady Workspaces downloads and unpacks the plug-in binaries and includes them in the Che-Theia editor container. The Che-Theia editor initializes the plug-ins when it starts.

Figure 4.4. Local Che-Theia plug-in

4.1.5.2. Remote plug-ins

The plug-in relies on dependencies or it has a back end. It runs in its own sidecar container, and all dependencies are packaged in the container.

A remote Che-Theia plug-in consist of two parts:

• Che-Theia plug-in or VS Code extension binaries. The definition in the meta.yaml file is the same as for embedded plug-ins.
• Container image definition, for example, eclipse/che-theia-dev:nightly. From this image, CodeReady Workspaces creates a separate container inside a workspace.

Examples:

• Java Language Server
• Python Language Server

When starting a workspace, CodeReady Workspaces creates a container from the plug-in image, downloads and unpacks the plug-in binaries, and includes them in the created container. The Che-Theia editor connects to the remote plug-ins when it starts.

Figure 4.5. Remote Che-Theia plug-in

Red Hat CodeReady Workspaces has a remote plug-in endpoint service to start VS Code Extensions and Che-Theia plug-ins in separate containers. Red Hat CodeReady Workspaces injects the remote plug-in endpoint binaries into each remote plug-in container. This service starts remote extensions and plug-ins defined in the plug-in meta.yaml file and connects them to the Che-Theia editor container.

The remote plug-in endpoint creates a plug-in API proxy between the remote plug-in container and the Che-Theia editor container. The remote plug-in endpoint is also an interceptor for some plug-in API parts, which it launches inside a remote sidecar container rather than an editor container. Examples: terminal API, debug API.

The remote plug-in endpoint executable command is stored in the environment variable of the remote plug-in container: PLUGIN_REMOTE_ENDPOINT_EXECUTABLE.

Red Hat CodeReady Workspaces provides two ways to start the remote plug-in endpoint with a sidecar image:

The user of CodeReady Workspaces can use a workspace devfile to use any plug-in, also known as Visual Studio Code (VS Code) extension. This plug-in can be added to the plug-in registry, then easily reused by anyone in the same organization with access to that workspaces installation.

Some plug-ins need a runtime dedicated container for code compilation. This fact makes those plug-ins a combination of a runtime sidecar container and a VS Code extension.

The following section describes the portability of a plug-in configuration and associating an extension with a runtime container that the plug-in needs.

When the required VS Code extension is added into a CodeReady Workspaces plug-in registry, the user can add it into the workspace through the CodeReady Workspaces Plugins panel or through the workspace configuration.

CodeReady Workspaces plug-ins are special services that extend the CodeReady Workspaces workspace capabilities. CodeReady Workspaces plug-ins are packaged as containers. The containers that the plug-ins are packaged into run as sidecars of the CodeReady Workspaces workspace editor and augment its capabilities.

For a VS Code extension with external dependencies not found in one of the ready-to-use images, use a container image based on the eclipse/che-theia-endpoint-runtime:next image that contains the dependencies.

Che-Theia does not fully support the VS Code extensions API. The vscode-theia-comparator is used to analyze the compatibility between the Che-Theia plug-in API and the VS Code extension API. This tool runs in a nightly cycle, and the results are published on the vscode-theia-comparator GitHub page.

CodeReady Workspaces plug-ins are extensions to the Che-Theia IDE that come bundled with a container image that contains their native prerequisites (for example, the OpenShift Connector plug-in needs the oc command installed). A Che Plugin is a list of Che-Theia plug-ins together about a Linux container that the plug-in requires to run in. It can also include metadata to define the description, categorization tags, and an icon. CodeReady Workspaces provides a registry of plug-ins available for installation into the user’s workspace.

Because many VS Code extensions can run inside the Che-Theia IDE, they can be packaged as CodeReady Workspaces plug-ins by combining them with a runtime or a sidecar container. Users can choose from many more plug-ins that are provided out of the box.

From the Dashboard, plug-ins in the registry can be added from the Plugin tab or by adding them into a devfile. The devfile can also be used for further configuration of the plug-in, such as to define memory or CPU usage. Alternatively, plug-ins can be installed from CodeReady Workspaces by pressing Ctrl+Shift+J or by navigating to View → Plugins.

This procedure describes adding a tool to an already existing workspace, by enabling a dedicated plug-in from the Dashboard.

To add tools that are available as plug-ins into a CodeReady Workspaces workspace, use one of the following methods:

This procedure uses the Java language support plug-in as an example.