Chapter 4. Customizing developer environments

Red Hat CodeReady Workspaces is an extensible and customizable developer-workspaces platform.

You can extend Red Hat CodeReady Workspaces in three different ways:

Alternative IDEs provide specialized tools for Red Hat CodeReady Workspaces. For example, a Jupyter notebook for data analysis. Alternate IDEs can be based on Eclipse Theia or any other web IDE. The default IDE in Red Hat CodeReady Workspaces is Che-Theia.
Che-Theia plug-ins add capabilities to the Che-Theia IDE. They rely on plug-in APIs that are compatible with Visual Studio Code. The plug-ins are isolated from the IDE itself. They can be packaged as files or as containers to provide their own dependencies.
Stacks are pre-configured CodeReady Workspaces workspaces with a dedicated set of tools, which cover different developer personas. For example, it is possible to pre-configure a workbench for a tester with only the tools needed for their purposes.

Figure 4.1. CodeReady Workspaces extensibility

A user can extend CodeReady Workspaces by using self-hosted mode, which CodeReady Workspaces provides by default.

4.1. What is a Che-Theia plug-in

A Che-Theia plug-in is an extension of the development environment isolated from the IDE. Plug-ins can be packaged as files or containers to provide their own dependencies.

Extending Che-Theia using plug-ins can enable the following capabilities:

Language support: Extend the supported languages by relying on the Language Server Protocol.
Debuggers: Extend debugging capabilities with the Debug Adapter Protocol.
Development Tools: Integrate your favorite linters, and as testing and performance tools.
Menus, panels, and commands: Add your own items to the IDE components.
Themes: Build custom themes, extend the UI, or customize icon themes.
Snippets, formatters, and syntax highlighting: Enhance comfort of use with supported programming languages.
Keybindings: Add new keymaps and popular keybindings to make the environment feel natural.

4.1.1. Features and benefits of Che-Theia plug-ins

Features	Description	Benefits
Fast Loading	Plug-ins are loaded at runtime and are already compiled. IDE is loading the plug-in code.	Avoid any compilation time. Avoid post-installation steps.
Secure Loading	Plug-ins are loaded separately from the IDE. The IDE stays always in a usable state.	Plug-ins do not break the whole IDE if it has bugs. Handle network issue.
Tools Dependencies	Dependencies for the plug-in are packaged with the plug-in in its own container.	No-installation for tools. Dependencies running into container.
Code Isolation	Guarantee that plug-ins cannot block the main functions of the IDE like opening a file or typing	Plug-ins are running into separate threads. Avoid dependencies mismatch.
VS Code Extension Compatibility	Extend the capabilities of the IDE with existing VS Code Extensions.	Target multiple platform. Allow easy discovery of Visual Studio Code Extension with required installation.

4.1.2. Che-Theia plug-in concept in detail

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

4.1.2.2. Che-Theia plug-in APIs

For the purpose of providing tool isolation and easy extensibility in Red Hat CodeReady Workspaces, the Che-Theia IDE has a set of plug-in APIs. The APIs are compatible with Visual Studio Code extension APIs. Usually, Che-Theia can run VS Code extensions as its own plug-ins.

When developing a plug-in that depends on or interacts with components of CodeReady Workspaces workspaces (containers, preferences, factories), use the CodeReady Workspaces APIs embedded in Che-Theia.

4.1.2.3. Che-Theia plug-in capabilities

Che-Theia plug-ins have the following capabilities:

Plug-in	Description	Repository
CodeReady Workspaces Extended Tasks	Handles the CodeReady Workspaces commands and provides the ability to start those into a specific container of the workspace.
CodeReady Workspaces Extended Terminal	Allows to provide terminal for any of the containers of the workspace.
CodeReady Workspaces Factory	Handles the Red Hat CodeReady Workspaces Factories
CodeReady Workspaces Container	Provides a container view that shows all the containers that are running in the workspace and allows to interact with them.	Containers plugins
Dashboard	Integrates the IDE with the Dashboard and facilitate the navigation.
CodeReady Workspaces APIs	Extends the IDE APIs to allow interacting with CodeReady Workspaces-specific components (workspaces, preferences).

4.1.2.4. VS Code extensions and Eclipse Theia plug-ins

A Che-Theia plug-in can be based on a VS Code extension or an Eclipse Theia plug-in.

A Visual Studio Code extension: To repackage a VS Code extension as a Che-Theia plug-in with its own set of dependencies, package the dependencies into a container. This ensures that Red Hat CodeReady Workspaces users do not need to install the dependencies when using the extension. See https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.4/html-single/administration_guide/index#using-a-visual-studio-code-extension-in-codeready-workspaces_crw.
An Eclipse Theia plug-in: You can build a Che-Theia plug-in by implementing an Eclipse Theia plug-in and packaging it to Red Hat CodeReady Workspaces.

Additional resources

Section 4.1.5, “Embedded and remote Che-Theia plug-ins”

4.1.3. Che-Theia plug-in metadata

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.

Here is an overview of all fields that can be available in plugin meta YAML files. This document represents the Plugin meta YAML structure version 3.

The che-plugin-registry repository contains:

Table 4.1. meta.yml
`apiVersion`	Version 2 and higher where version is 1 supported for backwards compatibility
`category`	Available: Category must be set to one of the followings: `Editor`, `Debugger`, `Formatter`, `Language`, `Linter`, `Snippet`, `Theme`, `Other`
`description`	Short description of plugin’s purpose
`displayName`	Name shown in user dashboard
`Deprecate`	Optional; section for deprecating plugins in favor of others * autoMigrate - boolean * migrateTo - new org/plugin-id/version, for example `redhat/vscode-apache-camel/latest`
`firstPublicationDate`	Not required to be present in YAML, as if not present, it will be generated during Plugin Registry dockerimage build
`latestUpdateDate`	Not required to be present in YAML, as if not present, it will be generated during Plugin Registry dockerimage build
`icon`	URL of an SVG or PNG icon
`name`	Name (no spaces allowed), must match [-a-z0-9]
`publisher`	Name of the publisher, must match [-a-z0-9]
`repository`	URL for plugin repository, for example, GitHub
`title`	Plugin title (long)
`type`	`Che Plugin`, `VS Code extension`
`version`	Version information, for example: 7.5.1, [-.a-z0-9]
`spec`	Specifications (see below)

Table 4.2. spec attributes
`endpoints`	Optional; plugin endpoint. See Section 3.2.4.2.19, “Endpoints”
`containers`	Optional; sidecar containers for the plug-in. Che Plugin and VS Code extension supports only one container
`initContainers`	Optional; sidecar init containers for the plug-in
`workspaceEnv`	Optional; environment variables for the workspace
`extensions`	Optional; Attribute that is required for VS Code and Che-Theia plug-ins in a form list of URLs to plug-in artefacts, such as .vsix or .theia files

Table 4.3. spec.containers. Notice: spec.initContainers has absolutely the same container definition.
`name`	Sidecar container name
`image`	Absolute or relative container image URL
`memoryLimit`	OpenShift memory limit string, for example `512Mi`
`memoryRequest`	OpenShift memory request string, for example `512Mi`
`cpuLimit`	OpenShift CPU limit string, for example `2500m`
`cpuRequest`	OpenShift CPU request string, for example `125m`
`env`	List of environment variables to set in the sidecar
`command`	String array definition of the root process command in the container
`args`	String array arguments for the root process command in the container
`volumes`	Volumes required by the plug-in
`ports`	Ports exposed by the plug-in (on the container)
`commands`	Development commands available to the plug-in container
`mountSources`	Boolean flag to bound volume with source code `/projects` to the plug-in container
`initContainers`	Optional; init containers for sidecar plugin
`Lifecycle`	Container lifecycle hooks. See `lifecycle` description

Table 4.4. spec.containers.env and spec.initContainers.env attributes. Notice: workspaceEnv has absolutely the same attributes
`name`	Environment variable name
`value`	Environment variable value

Table 4.5. spec.containers.volumes and spec.initContainers.volumes attributes
`mountPath`	Path to the volume in the container
`name`	Volume name
`ephemeral`	If true, the volume is ephemeral, otherwise the volume is persisted

Table 4.6. spec.containers.ports and spec.initContainers.ports attributes
`exposedPort`	Exposed port

Table 4.7. spec.containers.commands and spec.initContainers.commands attributes
`name`	Command name
`workingDir`	Command working directory
`command`	String array that defines the development command

Table 4.8. spec.endpoints attributes
`name`	Name (no spaces allowed), must match [-a-z0-9]
`public`	`true`, `false`
`targetPort`	Target port
`attributes`	Endpoint attributes

Table 4.9. spec.endpoints.attributes attributes
`protocol`	Protocol, example: `ws`
`type`	`ide`, `ide-dev`
`discoverable`	`true`, `false`
`secure`	`true`, `false`. If `true`, then the endpoint is assumed to listen solely on `127.0.0.1` and is exposed using a JWT proxy
`cookiesAuthEnabled`	`true`, `false`

Table 4.10. spec.containers.lifecycle and spec.initContainers.lifecycle attributes
`postStart`	The `postStart` event that runs immediately after a Container is started. See postStart and preStop handlers * `exec`: Executes a specific command, resources consumed by the command are counted against the Container * `command`: ["/bin/sh", "-c", "/bin/post-start.sh"]
`preStop`	The `preStop` event that runs before a Container is terminated. See postStart and preStop handlers * `exec`: Executes a specific command, resources consumed by the command are counted against the Container * `command`: ["/bin/sh", "-c", "/bin/post-start.sh"]

Example meta.yaml for a Che-Theia plug-in: the CodeReady Workspaces machine-exec Service

  apiVersion: v2
  publisher: eclipse
  name: che-machine-exec-plugin
  version: 7.9.2
  type: Che Plugin
  displayName: CodeReady Workspaces machine-exec Service
  title: Che machine-exec Service Plugin
  description: CodeReady Workspaces Plug-in with che-machine-exec service to provide creation terminal
    or tasks for Eclipse CHE workspace containers.
  icon: https://www.eclipse.org/che/images/logo-eclipseche.svg
  repository: https://github.com/eclipse/che-machine-exec/
  firstPublicationDate: "2020-03-18"
  category: Other
  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.9.2"
       ports:
         - exposedPort: 4444
       command: ['/go/bin/che-machine-exec', '--static', '/cloud-shell', '--url', '127.0.0.1:4444']

Example meta.yaml for a VisualStudio Code extension: the AsciiDoc support extension

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

4.1.4. Che-Theia plug-in lifecycle

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

CodeReady Workspaces master checks for plug-ins to start from the workspace definition.
Plug-in metadata is retrieved, and the type of each plug-in is recognized.
A broker is selected according to the plug-in type.
The broker processes the installation and deployment of the plug-in (the installation process is different for each broker).

Note

Different types of plug-ins exist. A broker ensures all installation requirements are met for a plug-in to deploy correctly.

Figure 4.3. Che-Theia plug-in lifecycle

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

The Che-Theia plug-in broker extracts the plug-in (from the .theia file) to get the sidecar containers that the plug-in needs.
The broker sends the appropriate container information to CodeReady Workspaces master.
The broker copies the Che-Theia plug-in to a volume to have it available for the Che-Theia editor container.
CodeReady Workspaces workspace master then starts all the containers of the workspace.
Che-Theia is started in its own container and checks the correct folder to load the plug-ins.

Che-Theia plug-in lifecycle:

When a user is opening a browser tab or window with Che-Theia, Che-Theia starts a new plug-in session (Web Worker for frontend or Node.js for backend). Every Che-Theia plug-in is notified that a new session has been started (the start() function of the plug-in triggered).
A Che-Theia plug-in session is running and interacting with the Che-Theia backend and frontend.
When the user is closing the browser tab or there is a timeout, every plug-in is notified (the stop() function of the plug-in triggered).

4.1.5. Embedded and remote Che-Theia plug-ins

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.

Che-Theia plug-in can run in two different ways, based on the necessary dependencies: 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 https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.4/html-single/administration_guide/index#using-a-visual-studio-code-extension-in-codeready-workspaces_crw).

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

4.1.5.3. Comparison matrix

When a Che-Theia plug-in (or a VS Code extension) does not need extra dependencies inside its container, it is an embedded plug-in. A container with extra dependencies that includes a plug-in is a remote plug-in.

Table 4.11. Che-Theia plug-in comparison matrix: embedded vs remote
	Configure RAM per plug-in	Environment dependencies	Create separated container
Remote	TRUE	Plug-in uses dependencies defined in the remote container.	TRUE
Embedded	FALSE (users can configure RAM for the whole editor container, but not per plug-in)	Plug-in uses dependencies from the editor container; if container does not include these dependencies, the plug-in fails or does not function as expected.	FALSE

Depending on your use case and the capabilities provided by your plug-in, select one of the described running modes.

4.1.6. Remote plug-in endpoint

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:

Defining a launch remote plug-in endpoint using a Dockerfile. To use this method, patch an original image and rebuild it.
Defining a launch remote plug-in endpoint in the plug-in meta.yaml file. Use this method to avoid patching an original image.

4.1.6.1. Defining a launch remote plug-in endpoint using Dockerfile

To start a remote plug-in endpoint, use the PLUGIN_REMOTE_ENDPOINT_EXECUTABLE environment variable in the Dockerfile.

Procedure

Start a remote plug-in endpoint using the CMD command in the Dockerfile:

Dockerfile example

FROM fedora:30

RUN dnf update -y && dnf install -y nodejs htop && node -v

RUN mkdir /home/jboss

ENV HOME=/home/jboss

RUN mkdir /projects \
    && chmod -R g+rwX /projects \
    && chmod -R g+rwX "${HOME}"

CMD ${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}

Start a remote plug-in endpoint using the ENTRYPOINT command in the Dockerfile:

Dockerfile example

FROM fedora:30

RUN dnf update -y && dnf install -y nodejs htop && node -v

RUN mkdir /home/jboss

ENV HOME=/home/jboss

RUN mkdir /projects \
    && chmod -R g+rwX /projects \
    && chmod -R g+rwX "${HOME}"

ENTRYPOINT ${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}

4.1.6.1.1. Using a wrapper script

Some images use a wrapper script to configure permissions. The script is defined it in the ENTRYPOINT command of the Dockerfile to configure permissions inside the container, and it script executes a main process defined in the CMD command of the Dockerfile.

Red Hat CodeReady Workspaces uses such images with a wrapper script to provide permission configurations on different infrastructures with advanced security, for example on OpenShift.

Example of a wrapper script:

#!/bin/sh

set -e

export USER_ID=$(id -u)
export GROUP_ID=$(id -g)

if ! whoami >/dev/null 2>&1; then
    echo "${USER_NAME:-user}:x:${USER_ID}:0:${USER_NAME:-user} user:${HOME}:/bin/sh" >> /etc/passwd
fi

# Grant access to projects volume in case of non root user with sudo rights
if [ "${USER_ID}" -ne 0 ] && command -v sudo >/dev/null 2>&1 && sudo -n true > /dev/null 2>&1; then
    sudo chown "${USER_ID}:${GROUP_ID}" /projects
fi

exec "$@"

Example of a Dockerfile with a wrapper script:
Dockerfile example
```
FROM alpine:3.10.2

ENV HOME=/home/theia

RUN mkdir /projects ${HOME} && \
    # Change permissions to let any arbitrary user
    for f in "${HOME}" "/etc/passwd" "/projects"; do \
      echo "Changing permissions on ${f}" && chgrp -R 0 ${f} && \
      chmod -R g+rwX ${f}; \
    done

ADD entrypoint.sh /entrypoint.sh

ENTRYPOINT [ "/entrypoint.sh" ]
CMD ${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}
```
In this example, the container launches the /entrypoint.sh script defined in the ENTRYPOINT command of the Dockerfile. The script configures the permissions and executes the command using exec $@. CMD is the argument for ENTRYPOINT, and the exec $@ command calls ${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}. A remote plug-in endpoint then starts in the container after permission configuration.

4.1.6.2. Defining a launch remote plug-in endpoint in a `meta.yaml` file

Use this method to re-use images to start remote a plug-in endpoint without modifications.

Procedure

Modify the plug-in meta.yaml file properties command and args:

command - Red Hat CodeReady Workspaces uses to override Dockerfile#ENTRYPOINT.
args - Red Hat CodeReady Workspaces uses to override Dockerfile#CMD.

Example of a YAML file with the command and args properties modified:

apiVersion: v2
category: Language
description: "Typescript language features"
displayName: Typescript
firstPublicationDate: "2019-10-28"
icon: "https://www.eclipse.org/che/images/logo-eclipseche.svg"
name: typescript
publisher: che-incubator
repository: "https://github.com/Microsoft/vscode"
title: "Typescript language features"
type: "VS Code extension"
version: remote-bin-with-override-entrypoint
spec:
  containers:
    - image: "example/fedora-for-ts-remote-plugin-without-endpoint:latest"
      memoryLimit: 512Mi
      name: vscode-typescript
      command:
        - sh
        - -c
      args:
        - ${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}
  extensions:
    - "https://github.com/che-incubator/ms-code.typescript/releases/download/v1.35.1/che-typescript-language-1.35.1.vsix"

Modify args instead of command to use an image with a wrapper script pattern and to keep a call of the entrypoint.sh script:

apiVersion: v2
category: Language
description: "Typescript language features"
displayName: Typescript
firstPublicationDate: "2019-10-28"
icon: "https://www.eclipse.org/che/images/logo-eclipseche.svg"
name: typescript
publisher: che-incubator
repository: "https://github.com/Microsoft/vscode"
title: "Typescript language features"
type: "VS Code extension"
version: remote-bin-with-override-entrypoint
spec:
  containers:
    - image: "example/fedora-for-ts-remote-plugin-without-endpoint:latest"
      memoryLimit: 512Mi
      name: vscode-typescript
      args:
        - sh
        - -c
        - ${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}
  extensions:
    - "https://github.com/che-incubator/ms-code.typescript/releases/download/v1.35.1/che-typescript-language-1.35.1.vsix"

Red Hat CodeReady Workspaces calls the entrypoint.sh wrapper script defined in the ENTRYPOINT command of the Dockerfile. The script executes [ ‘sh’, ‘-c”, ‘ ${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}’ ] using the exec “$@” command.

Note

To execute a service when starting the container and also to start a remote plug-in endpoint, use meta.yaml with modified command and args properties. Start the service, detach the process, and start the remote plug-in endpoint, and they then work in parallel.

4.2. Using alternative IDEs in CodeReady Workspaces

Extending Red Hat CodeReady Workspaces developer workspaces using different IDEs (integrated development environments) enables:

Re-purposing the environment for different use cases.
Providing a dedicated custom IDE for specific tools.
Providing different perspectives for individual users or groups of users.

Red Hat CodeReady Workspaces provides a default web IDE to be used with the developer workspaces. This IDE is completely decoupled. You can bring your own custom IDE for Red Hat CodeReady Workspaces:

Built from Eclipse Theia, which is a framework to build web IDEs. Example: Sirius on the web.
Completely different web IDEs, such as Jupyter, Eclipse Dirigible, or others. Example: Jupyter in Red Hat CodeReady Workspaces workspaces.

Bringing custom IDE built from Eclipse Theia

Creating your own custom IDE based on Eclipse Theia.
Adding CodeReady Workspaces-specific tools to your custom IDE.
Packaging your custom IDE into the available editors for CodeReady Workspaces.

Bringing your completely different web IDE into CodeReady Workspaces

Packaging your custom IDE into the available editors for CodeReady Workspaces.

4.3. Adding tools to CodeReady Workspaces after creating a workspace

When installed in a workspace, CodeReady Workspaces plug-ins bring new capabilities to CodeReady Workspaces. Plug-ins consist of a Che-Theia plug-in, metadata, and a hosting container. These plug-ins may provide the following capabilities:

Integrating with other systems, including OpenShift.
Automating some developer tasks, such as formatting, refactoring, and running automated tests.
Communicating with multiple databases directly from the IDE.
Enhanced code navigation, auto-completion and error highlighting.

This chapter provides basic information about installing, enabling, and using CodeReady Workspaces plug-ins in workspaces.

4.3.1. Additional tools in the CodeReady Workspaces workspace

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). Plug-ins can also include metadata to define a description, categorization tags, and an icon. CodeReady Workspaces provides a registry of plug-ins available for installation into the user’s workspace.

The Che-Theia IDE is generally compatible with the VS Code extensions API. This means that many VS Code extensions are automatically compatible with Che-Theia, and can be packaged as CodeReady Workspaces plug-ins by combining them container that contains their dependencies. By default, CodeReady Workspaces includes a plug-in registry containing common plug-ins.

From the Dashboard, plug-ins in the registry can be added from the Plugin tab in the Workspace details page, or by adding them directly into a devfile. The devfile can also be used for further configuration of the plug-in, such defining memory or CPU usage. Alternatively, plug-ins can also be installed from within the Che-Theia IDE by pressing Ctrl+Shift+J or by navigating to View Plugins.

Additional resources

Section 3.2.4.2, “Adding components to a devfile”

4.3.2. Adding a language support plug-in to a CodeReady Workspaces workspace

This procedure describes adding a tool to an 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.

Prerequisites

A running instance of Red Hat CodeReady Workspaces. To install an instance of Red Hat CodeReady Workspaces, see Installing CodeReady Workspaces on OpenShift Container Platform.
An existing workspace defined in this instance of Red Hat CodeReady Workspaces; see:
- Section 3.3, “Creating and configuring a new CodeReady Workspaces 2.4 workspace”
- Section 3.6.2, “Creating a workspace from Custom Workspace view of User Dashboard”
The workspace must be in a stopped state. To stop a workspace,
1. Navigate to the CodeReady Workspaces Dashboard. See Section 1.1, “Navigating CodeReady Workspaces using the Dashboard”.
2. In the Dashboard, click the Workspaces menu to open the workspaces list and locate the workspace.
3. On the same row with the displayed workspace, on the right side of the screen, click the square Stop button to stop the workspace.
4. Wait a few seconds for the workspace to stop (the workspace’s icon on the list will turn grey), then configure the workspace by clicking on it.

Procedure

To add the plug-in from the Plug-in registry to an existing CodeReady Workspaces workspace, use one of the following methods:

Installing the plug-in from the Plugin tab.
1. Navigate to the Plugin tab. The list of available plug-ins is displayed.
2. Enable the desired plug-in, for example, the Language Support for Java 11, by using the Enable slide-toggle. This will add the plug-in’s ID to the workspace’s devfile, enabling the plug-in.
3. On the bottom right side of the screen, save the changes by clicking the Save button. After changes are saved, the workspace can be restarted and will include the new plug-in.

Installing the plug-in by adding content to the devfile.

Navigate to the Devfile tab. The devfile YAML is displayed.

Locate the components section of the devfile and add the following lines to add the Java language plugin with Java 8 to the workspace:

 - id: redhat/java8/latest
   type: chePlugin

An example of the final result:

components:
 - id: redhat/php/latest
   memoryLimit: 1Gi
   type: chePlugin
 - id: redhat/php-debugger/latest
   memoryLimit: 256Mi
   type: chePlugin
 - mountSources: true
   endpoints:
     - name: 8080/tcp
       port: 8080
   memoryLimit: 512Mi
   type: dockerimage
   volumes:
     - name: composer
       containerPath: {prod-home}/.composer
     - name: symfony
       containerPath: {prod-home}/.symfony
   alias: php
   image: 'quay.io/eclipse/che-php-7:nightly'
 - id: redhat/java8/latest
   type: chePlugin

On the bottom right side of the screen, save the changes by clicking the Save button. After changes are saved, the workspace can be restarted and will include the new plug-in.

Additional resources

Devfile specifications

Chapter 4. Customizing developer environments

4.1. What is a Che-Theia plug-in

4.1.1. Features and benefits of Che-Theia plug-ins

4.1.2. Che-Theia plug-in concept in detail

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

4.1.2.2. Che-Theia plug-in APIs

4.1.2.3. Che-Theia plug-in capabilities

4.1.2.4. VS Code extensions and Eclipse Theia plug-ins

4.1.3. Che-Theia plug-in metadata

4.1.4. Che-Theia plug-in lifecycle

4.1.5. Embedded and remote Che-Theia plug-ins

4.1.5.1. Embedded (or local) plug-ins

4.1.5.2. Remote plug-ins

4.1.5.3. Comparison matrix

4.1.6. Remote plug-in endpoint

4.1.6.1. Defining a launch remote plug-in endpoint using Dockerfile

4.1.6.1.1. Using a wrapper script

4.1.6.2. Defining a launch remote plug-in endpoint in a `meta.yaml` file

4.2. Using alternative IDEs in CodeReady Workspaces

4.3. Adding tools to CodeReady Workspaces after creating a workspace

4.3.1. Additional tools in the CodeReady Workspaces workspace

4.3.2. Adding a language support plug-in to a CodeReady Workspaces workspace

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links

Chapter 4. Customizing developer environments

4.1. What is a Che-Theia plug-in

4.1.1. Features and benefits of Che-Theia plug-ins

4.1.2. Che-Theia plug-in concept in detail

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

4.1.2.2. Che-Theia plug-in APIs

4.1.2.3. Che-Theia plug-in capabilities

4.1.2.4. VS Code extensions and Eclipse Theia plug-ins

4.1.3. Che-Theia plug-in metadata

4.1.4. Che-Theia plug-in lifecycle

4.1.5. Embedded and remote Che-Theia plug-ins

4.1.5.1. Embedded (or local) plug-ins

4.1.5.2. Remote plug-ins

4.1.5.3. Comparison matrix

4.1.6. Remote plug-in endpoint

4.1.6.1. Defining a launch remote plug-in endpoint using Dockerfile

4.1.6.1.1. Using a wrapper script

4.1.6.2. Defining a launch remote plug-in endpoint in a meta.yaml file

4.2. Using alternative IDEs in CodeReady Workspaces

4.3. Adding tools to CodeReady Workspaces after creating a workspace

4.3.1. Additional tools in the CodeReady Workspaces workspace

4.3.2. Adding a language support plug-in to a CodeReady Workspaces workspace

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links

4.1.6.2. Defining a launch remote plug-in endpoint in a `meta.yaml` file