Chapter 5. 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 IDE (web or desktop based). 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 5.1. CodeReady Workspaces extensibility A user can extend CodeReady Workspaces by using self-hosted mode, which CodeReady Workspaces provides by default. Section 5.1, "What is a Che-Theia plug-in" Section 5.6, "Using alternative IDEs in CodeReady Workspaces" Section 5.2, "Adding a Visual Studio Code extension to a workspace" Section 5.10, "Using private container registries" 5.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, code formatting, and syntax highlighting: Enhance comfort of use with supported programming languages. Keybindings: Add new keyboard mapping and popular keybindings to make the environment feel natural. 5.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. Visual Studio Code Extension Compatibility Extend the capabilities of the IDE with existing Visual Studio Code Extensions. Target multiple platform. Allow easy discovery of Visual Studio Code Extension with required installation. 5.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. 5.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 5.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). 5.1.2.2. Che-Theia plug-in APIs To provide 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 Visual Studio 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. 5.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. Task plug-in CodeReady Workspaces Extended Terminal Allows to provide terminal for any of the containers of the workspace. Extended Terminal extension CodeReady Workspaces Factory Handles the Red Hat CodeReady Workspaces Factories Workspace plug-in 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 plug-in Dashboard Integrates the IDE with the Dashboard and facilitate the navigation. Che-Theia Dashbord extension CodeReady Workspaces APIs Extends the IDE APIs to allow interacting with CodeReady Workspaces-specific components (workspaces, preferences). Che-Theia API extension 5.1.2.4. Visual Studio Code extensions and Eclipse Theia plug-ins A Che-Theia plug-in can be based on a Visual Studio Code extension or an Eclipse Theia plug-in. A Visual Studio Code extension To repackage a Visual Studio 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 Section 5.2, "Adding a Visual Studio Code extension to a workspace" . 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 5.1.5, "Embedded and remote Che-Theia plug-ins" 5.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. These files can be referenced in a devfile to include Che-Theia plug-ins in a workspace. Here is an overview of all fields that can be available in plug-in meta YAML files. This document represents the plugin meta YAML structure (version 3) . Table 5.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 the plug-in purpose displayName Name shown in user dashboard deprecate Optional; section for deprecating plug-ins in favor of others * autoMigrate - boolean * migrateTo - new org/plugin-id/version , for example redhat/vscode-apache-camel/latest firstPublicationDate Not required to be in YAML; if it is not included, the plug-in registry dockerimage build generates it latestUpdateDate Not required to be in YAML; if it is not included, the plug-in registry dockerimage build generates it 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 plug-in repository, for example, GitHub title Plug-in title (long) type Che Plugin , Visual Studio Code extension version Version information, for example: 7.5.1, [-.a-z0-9] spec Specifications (see below) Table 5.2. spec attributes endpoints Optional; plug-in endpoint containers Optional; sidecar containers for the plug-in. Che Plug-in and Visual Studio 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 Visual Studio Code and Che-Theia plug-ins in a form list of URLs to plug-in artefacts, such as .vsix or .theia files Table 5.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 plug-in Lifecycle Container lifecycle hooks. See lifecycle description Table 5.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 5.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 5.6. spec.containers.ports and spec.initContainers.ports attributes exposedPort Exposed port Table 5.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 5.8. spec.endpoints attributes name Name (no spaces allowed), must match [-a-z0-9] public true , false targetPort Target port attributes Endpoint attributes Table 5.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 requireSubdomain true , false . If true , the endpoint is exposed on subdomain in single-host mode. Table 5.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/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 Visual Studio 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: Visual Studio 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 5.1.4. Che-Theia plug-in lifecycle Every time a user starts a Che workspace, a Che-Theia plug-in life cycle process starts. The steps of this process are as follows: CodeReady Workspaces server checks for plug-ins to start from the workspace definition. CodeReady Workspaces server retrieves plug-in metadata, recognizes each plug-in type, and stores them in memory. CodeReady Workspaces server selects a broker according to the plug-in type. The broker processes the installation and deployment of the plug-in. The installation process of the plug-in differs for each specific broker. Note Plug-ins exist in various types. A broker ensures the success of a plug-in deployment by meeting all installation requirements. Figure 5.3. Che-Theia plug-in lifecycle Before a CodeReady Workspaces workspace is launched, CodeReady Workspaces server starts the workspace containers: The Che-Theia plug-in broker extracts the information about sidecar containers that a particular plug-in needs from the .theia file. The broker sends the appropriate container information to CodeReady Workspaces server. The broker copies the Che-Theia plug-in to a volume to have it available for the Che-Theia editor container. CodeReady Workspaces server then starts all the containers of the workspace. Che-Theia starts in its container and checks the correct folder to load the plug-ins. A user experience with Che-Theia plug-in lifecycle When a user opens a browser tab with Che-Theia, Che-Theia starts a new plug-in session with: Web Worker for frontend Node.js for backend Che-Theia notifies all Che-Theia plug-ins with the start of the new session by calling the start() function for each triggered plug-in. A Che-Theia plug-in session runs and interacts with the Che-Theia backend and frontend. When the user closes the Che-Theia browser tab, or the session ended on a timeout limit, Che-Theia notifies all plug-ins with the stop() function for each triggered plug-in. 5.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. Based on the required dependencies, Che-Theia plug-in can run as: Embedded, also know as local Remote 5.1.5.1. Embedded (local) plug-ins The Embedded plug-ins are plug-ins without specific dependencies that are injected into the Che-Theia IDE. These plug-ins use the Node.js runtime, which runs in the IDE container. Examples: Code linting New set of commands New UI components To include a Che-Theia plug-in or Visual Studio Code extension, define a URL to the plug-in .theia archive binary in the meta.yaml file. See Section 5.2, "Adding a Visual Studio Code extension to a workspace" 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. 5.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 Visual Studio 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. 5.1.5.3. Comparison matrix Embedded plug-ins are those Che-Theia plug-ins or Visual Studio Code extensions that do not require extra dependencies inside its container. Remote plug-ins are containers that contain a plug-in with all required dependencies. Table 5.11. Che-Theia plug-in comparison matrix: embedded compared to 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. 5.1.6. Remote plug-in endpoint Red Hat CodeReady Workspaces has a remote plug-in endpoint service to start Visual Studio 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. 5.1.6.1. Defining a launch remote plug-in endpoint using Dockerfile To start a remote plug-in endpoint, set 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 Start a remote plug-in endpoint using the ENTRYPOINT command in the Dockerfile: Dockerfile example 5.1.6.1.1. Using a wrapper script Some images use a wrapper script to configure permissions inside the container. The Dockertfile ENTRYPOINT command defines this script, which executes the main process defined in the CMD command of the Dockerfile. CodeReady Workspaces uses images with a wrapper script to provide permission configurations to different infrastructures protected by advanced security. OpenShift Container Platform is an example of such an infrastructure. Example of a wrapper script: #!/bin/sh set -e export USER_ID=USD(id -u) export GROUP_ID=USD(id -g) if ! whoami >/dev/null 2>&1; then echo "USD{USER_NAME:-user}:x:USD{USER_ID}:0:USD{USER_NAME:-user} user:USD{HOME}:/bin/sh" >> /etc/passwd fi # Grant access to projects volume in case of non root user with sudo rights if [ "USD{USER_ID}" -ne 0 ] && command -v sudo >/dev/null 2>&1 && sudo -n true > /dev/null 2>&1; then sudo chown "USD{USER_ID}:USD{GROUP_ID}" /projects fi exec "USD@" Example of a Dockerfile with a wrapper script: Dockerfile example Explanation: 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 USD@ . CMD is the argument for ENTRYPOINT , and the exec USD@ command calls USD{PLUGIN_REMOTE_ENDPOINT_EXECUTABLE} . The remote plug-in endpoint then starts in the container after permission configuration. 5.1.6.2. Defining a launch remote plug-in endpoint in a meta.yaml file Use this method to re-use images for starting a remote plug-in endpoint without any modifications. Procedure Modify the plug-in meta.yaml file properties command and args : command - CodeReady Workspaces uses the command properties to override the Dockerfile#ENTRYPOINT value. args - CodeReady Workspaces uses uses the args properties to override the Dockerfile#CMD value. 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: "Visual Studio 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: - USD{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: "Visual Studio 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 - USD{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", ' USD{PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}' ] using the exec "USD@" command. Note By modifying the command and args properties of the meta.yaml file, a user can: Execute a service at a container start Start a remote plug-in endpoint To make these actions run at the same time: Start the service. Detach the process. Start the remote plug-in endpoint. 5.2. Adding a Visual Studio Code extension to a workspace This section describes how to add a Visual Studio Code extension to a workspace using the workspace configuration. Prerequisites The Visual Studio Code extension is available in the CodeReady Workspaces plug-in registry, or metadata for the Visual Studio Code extension are available. See Section 5.4, "Publishing metadata for a Visual Studio Code extension" . 5.2.1. Adding a Visual Studio Code extension using the workspace configuration Prerequisites A running instance of CodeReady Workspaces. To install an instance of CodeReady Workspaces, see Installing CodeReady Workspaces . An existing workspace defined on this instance of CodeReady Workspaces. The Visual Studio Code extension is available in the CodeReady Workspaces plug-in registry, or metadata for the Visual Studio Code extension are available. See Section 5.4, "Publishing metadata for a Visual Studio Code extension" . Procedure To add a Visual Studio Code extension using the workspace configuration: Click the Workspaces tab on the Dashboard and select the plug-in destination workspace. The Workspace <workspace-name> window is opened showing the details of the workspace. Click the devfile tab. Locate the components section, and add a new entry with the following structure: - type: chePlugin id: 1 1 ID format: <publisher>/<plug-inName>/<plug-inVersion> CodeReady Workspaces automatically adds the other fields to the new component. Alternatively, you can link to a meta.yaml file hosted on GitHub, using the dedicated reference field. - type: chePlugin reference: 1 1 https://raw.githubusercontent.com/ <username> / <registryRepository> /v3/plugins/ <publisher> / <plug-inName> / <plug-inVersion> /meta.yaml Restart the workspace for the changes to take effect. 5.2.2. Adding a Visual Studio Code extension using recommendations Prerequisites A running instance of CodeReady Workspaces. To install an instance of CodeReady Workspaces, see Installing CodeReady Workspaces . Featured Visual Studio Code extensions are available in the CodeReady Workspaces plug-in registry. Procedure Open a workspace without any existing devfile using the CodeReady Workspaces dashboard : The recommendations plug-in will scan files, discover languages and install Visual Studio Code extensions matching these languages. Disable this feature by setting extensions.ignoreRecommendations to true in the devfile attributes. The recommendations plug-in can suggest Visual Studio Code extensions to install when opening files. It suggests extensions based on the workspace content, allowing the user to work with the given files. Enable this feature by setting extensions.openFileRecommendations to true in the devfile attributes. 5.3. Adding a Visual Studio Code extension to the CodeReady Workspaces plug-ins registry To use a Visual Studio Code extension in a CodeReady Workspaces workspace, CodeReady Workspaces need to consume metadata describing the extension. The CodeReady Workspaces plug-ins registry is a static website publishing metadata for common Visual Studio Code extensions. Visual Studio Code extension metadata for the CodeReady Workspaces plug-ins registry is generated from a central file named che-theia-plugins.yaml . To add or modify an extension in the CodeReady Workspaces plug-ins registry, edit the che-theia-plugins.yaml file and add relevant metadata. Note This article describes the steps needed to build the plug-ins registry with a custom plug-in definition. If you are looking to create a custom meta.yaml file that can be directly referenced in a devfile, see Section 5.4, "Publishing metadata for a Visual Studio Code extension" . Prerequisite A working knowledge of customizing the registries, see https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.15/html-single/administration_guide/index#customizing-the-registries.adoc A link to a sidecar container image, should the Visual Studio Code extension require one. Procedure Edit the che-theia-plugins.yaml file and create a new entry. - id: publisher/my-vscode-ext 1 repository: 2 url: https://github.com/publisher/my-vscode-ext 3 revision: 1.7.2 4 aliases: 5 - publisher/my-vscode-ext-revised preferences: 6 asciidoc.use_asciidoctorpdf: true shellcheck.executablePath: /bin/shellcheck solargraph.bundlerPath: /usr/local/bin/bundle solargraph.commandPath: /usr/local/bundle/bin/solargraph sidecar: 7 image: quay.io/repository/eclipse/che-plugin-sidecar:sonarlint-2fcf341 8 name: my-vscode-ext-sidecar 9 memoryLimit: "1500Mi" 10 memoryRequest: "1000Mi" 11 cpuLimit: "500m" 12 cpuRequest: "125m" 13 command: 14 - /bin/sh args: 15 - "-c" - "./entrypoint.sh" volumeMounts: 16 - name: vscode-ext-volume 17 path: "/home/theia/my-vscode-ext" 18 endpoints: 19 - name: "configuration-endpoint" 20 public: true 21 targetPort: 61436 22 attributes: 23 protocol: http extension: https://github.com/redhat-developer/vscode-yaml/releases/download/0.4.0/redhat.vscode-yaml-0.4.0.vsix 24 skipDependencies: 25 - id-of/extension1 - id-of/extension2 extraDependencies: 26 - id-of/extension1 - id-of/extension2 metaYaml: skipIndex: <true|false> 27 skipDependencies: 28 - id-of/extension1 - id-of/extension2 extraDependencies: 29 - id-of/extension1 - id-of/extension2 1 (OPTIONAL) The ID of the plug-in, useful if a plug-in has multiple entries for one repository. For example, Java 8 and Java 11. 2 Repository information about the plug-in. If ID is specified, then this field is not a list element. 3 The URL to the Git repository of the extension. 4 Tag or SHA1 ID of the upstream repository that hosts the extension, corresponding to a version, snapshot, or release. 5 (OPTIONAL) An alias for this plug-in. For anything listed here, a meta.yaml file is generated. 6 (OPTIONAL) Plug-in preferences in freeform format. 7 (OPTIONAL) If the plug-in runs in a sidecar container, then the sidecar information is specified here. 8 A location of a container image to be used as the plug-in sidecar. This line cannot be specified concurrently with directory . See above. 9 (OPTIONAL) The name of the sidecar container. 10 (OPTIONAL) The memory limit of the sidecar container. 11 (OPTIONAL) The memory request of the sidecar container. 12 (OPTIONAL) The CPU limit of the sidecar container. 13 (OPTIONAL) The CPU request of the sidecar container. 14 (OPTIONAL) Definitions of root process commands inside the container. 15 (OPTIONAL) Arguments for root process commands inside the container. 16 (OPTIONAL) Any volume mounting information for the sidecar container. 17 The name of the mount. 18 The path to the mount. 19 (OPTIONAL) Any endpoint information for the sidecar container. 20 Endpoint name. 21 A Boolean value determining whether the endpoint is exposed publicly. 22 The port number. 23 Attributes relating to the endpoint. 24 Direct link or links to the vsix files included with the plug-in. The vsix built by the repository specified, such as the main extension, must be listed first. 25 # TODO # 26 (OPTIONAL) Extra dependencies in addition to the one listed in extensionDependencies field of package.json. 27 (OPTIONAL) Do not include this plug-in in index.json if true. Useful in case of dependencies that you do not want to expose as standalone plug-ins. 28 (OPTIONAL) Do not examine specified dependencies from extensionDependencies field of package.json (only for meta.yaml generation). 29 (OPTIONAL) Extra dependencies in addition to the one listed in extensionDependencies field of package.json (only for meta.yaml generation). Run the build.sh script with the options of your choosing. The build process will generate meta.yaml files automatically, based on the entries in the che-theia-plugins.yaml file. Use the resulting plug-ins registry image in CodeReady Workspaces, or copy the meta.yaml file out of the registry container and reference it directly as an HTTP resource. 5.4. Publishing metadata for a Visual Studio Code extension To use a Visual Studio Code extension in a CodeReady Workspaces workspace, CodeReady Workspaces needs to consume metadata describing the extension. The CodeReady Workspaces plug-ins registry is a static website publishing metadata for common Visual Studio Code extensions. This article describes how to publish metadata for an additional extension, not available in the CodeReady Workspaces plug-ins registry, by using the extension configuration meta.yaml file. For details on adding a plug-in to an existing plug-in registry, see Section 5.3, "Adding a Visual Studio Code extension to the CodeReady Workspaces plug-ins registry" Prerequisite If the Visual Studio Code extension requires it, the required associated container image is available. Procedure Create a meta.yaml file. Edit the meta.yaml file and provide the necessary information. The file must have the following structure: apiVersion: v2 1 publisher: myorg 2 name: my-vscode-ext 3 version: 1.7.2 4 type: value 5 displayName: 6 title: 7 description: 8 icon: https://www.eclipse.org/che/images/logo-eclipseche.svg 9 repository: 10 category: 11 spec: containers: 12 - image: 13 memoryLimit: 14 memoryRequest: 15 cpuLimit: 16 cpuRequest: 17 extensions: 18 - https://github.com/redhat-developer/vscode-yaml/releases/download/0.4.0/redhat.vscode-yaml-0.4.0.vsix - https://github.com/SonarSource/sonarlint-vscode/releases/download/1.16.0/sonarlint-vscode-1.16.0.vsix 1 Version of the file structure. 2 Name of the plug-in publisher. Must be the same as the publisher in the path. 3 Name of the plug-in. Must be the same as in path. 4 Version of the plug-in. Must be the same as in path. 5 Type of the plug-in. Possible values: Che Plugin , Che Editor , Theia plugin , Visual Studio Code extension . 6 A short name of the plug-in. 7 Title of the plug-in. 8 A brief explanation of the plug-in and what it does. 9 The link to the plug-in logo. 10 Optional. The link to the source-code repository of the plug-in. 11 Defines the category that this plug-in belongs to. Should be one of the following: Editor , Debugger , Formatter , Language , Linter , Snippet , Theme , or Other . 12 If this section is omitted, the Visual Studio Code extension is added into the Che-Theia IDE container. 13 The Docker image from which the sidecar container will be started. Example: codeready-workspaces/theia-endpoint-rhel8 . 14 The maximum RAM which is available for the sidecar container. Example: "512Mi". This value might be overridden by the user in the component configuration. 15 The RAM which is given for the sidecar container by default. Example: "256Mi". This value might be overridden by the user in the component configuration. 16 The maximum CPU amount in cores or millicores (suffixed with "m") which is available for the sidecar container. Examples: "500m", "2". This value might be overridden by the user in the component configuration. 17 The CPU amount in cores or millicores (suffixed with "m") which is given for the sidecar container by default. Example: "125m". This value might be overridden by the user in the component configuration. 18 A list of Visual Studio Code extensions run in this sidecar container. Publish the meta.yaml file as an HTTP resource by creating a gist on GitHub or GitLab with a file content published there. 5.5. Testing a Visual Studio Code extension in CodeReady Workspaces Visual Studio Code (Visual Studio Code) extensions work in a workspace. Visual Studio Code extensions can run in the Che-Theia editor container, or in their own isolated and preconfigured containers with their prerequisites. This section describes how to test a Visual Studio Code extension in CodeReady Workspaces with workspaces and how to review the compatibility of Visual Studio Code extensions to check whether a specific API is available. Note The extension-hosting sidecar container and the use of the extension in a devfile are optional. 5.5.1. Testing a Visual Studio Code extension using GitHub gist Each workspace can have its own set of plug-ins. The list of plug-ins and the list of projects to clone are defined in the devfile.yaml file. For example, to enable an AsciiDoc plug-in from the Red Hat CodeReady Workspaces dashboard, add the following snippet to the devfile: components: - id: joaopinto/vscode-asciidoctor/latest type: chePlugin To add a plug-in that is not in the default plug-in registry, build a custom plug-in registry. See https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.15/html-single/administration_guide/index#customizing-the-registries.adoc , or, alternatively, use GitHub and the gist service. Prerequisites A running instance of CodeReady Workspaces. To install an instance of CodeReady Workspaces, see Installing CodeReady Workspaces . A GitHub account. Procedure Go to the gist webpage and create a README.md file with the following description: Try Bracket Pair Colorizer extension in Red Hat CodeReady Workspaces and content: Example Visual Studio Code extension . ( Bracket Pair Colorizer is a popular Visual Studio Code extension.) Click the Create secret gist button. Clone the gist repository by using the URL from the navigation bar of the browser: Example of the output of the git clone command 1 Each gist has a unique ID. Change the directory: 1 Directory name matching the gist ID. Download the plug-in from the Visual Studio Code marketplace or from its GitHub page , and store the plug-in file in the cloned directory. Create a plugin.yaml file in the cloned directory to add the definition of this plug-in. Example of the plugin.yaml file referencing the .vsix binary file extension apiVersion: v2 publisher: CoenraadS name: bracket-pair-colorizer version: 1.0.61 type: Visual Studio Code extension displayName: Bracket Pair Colorizer title: Bracket Pair Colorizer description: Bracket Pair Colorizer icon: https://raw.githubusercontent.com/redhat-developer/codeready-workspaces/crw-2-rhel-8/dependencies/che-plugin-registry/resources/images/default.svg?sanitize=true repository: https://github.com/CoenraadS/BracketPair category: Language firstPublicationDate: '2020-07-30' spec: 1 extensions: - "{{REPOSITORY}}/CoenraadS.bracket-pair-colorizer-1.0.61.vsix" 2 latestUpdateDate: "2020-07-30" 1 This extension requires a basic Node.js runtime, so it is not necessary to add a custom runtime image in plugin.yaml . 2 {{REPOSITORY}} is a macro for a pre-commit hook. Define a memory limit and volumes: spec: containers: - image: "quay.io/eclipse/che-sidecar-java:8-0cfbacb" name: vscode-java memoryLimit: "1500Mi" volumes: - mountPath: "/home/theia/.m2" name: m2 Create a devfile.yaml that references the plugin.yaml file: apiVersion: 1.0.0 metadata: generateName: java-maven- projects: - name: console-java-simple source: type: git location: "https://github.com/che-samples/console-java-simple.git" branch: java1.11 components: - type: chePlugin id: redhat/java11/latest - type: chePlugin 1 reference: "{{REPOSITORY}}/plugin.yaml" - type: dockerimage alias: maven image: quay.io/eclipse/che-java11-maven:nightly memoryLimit: 512Mi mountSources: true volumes: - name: m2 containerPath: /home/user/.m2 commands: - name: maven build actions: - type: exec component: maven command: "mvn clean install" workdir: USD{CHE_PROJECTS_ROOT}/console-java-simple - name: maven build and run actions: - type: exec component: maven command: "mvn clean install && java -jar ./target/*.jar" workdir: USD{CHE_PROJECTS_ROOT}/console-java-simple 1 Any other devfile definition is also accepted. The important information in this devfile are the lines defining this external component. It means that an external reference defines the plug-in and not an ID, which pointing to a definition in the default plug-in registry. Verify there are 4 files in the current Git directory: Before committing the files, add a pre-commit hook to update the {{REPOSITORY}} variable to the public external raw gist link: Create a .git/hooks/pre-commit file with this content: #!/bin/sh # get modified files FILES=USD(git diff --cached --name-only --diff-filter=ACMR "*.yaml" | sed 's| |\\ |g') # exit fast if no files found [ -z "USDFILES" ] && exit 0 # grab remote origin origin=USD(git config --get remote.origin.url) url="USD{origin}/raw" # iterate on files and add the good prefix pattern for FILE in USD{FILES}; do sed -e "s#{{REPOSITORY}}#USD{url}#g" "USD{FILE}" > "USD{FILE}.back" mv "USD{FILE}.back" "USD{FILE}" done # Add back to staging echo "USDFILES" | xargs git add exit 0 The hook replaces the {{REPOSITORY}} macro and adds the external raw link to the gist. Make the script executable: Commit and push the files: Visit the gist website and verify that all links have the correct public URL and do not contain any {{REPOSITORY}} variables. To reach the devfile: or: 5.5.2. Verifying the Visual Studio Code extension API compatibility level Che-Theia does not fully support the Visual Studio Code extensions API. The vscode-theia-comparator is used to analyze the compatibility between the Che-Theia plug-in API and the Visual Studio Code extension API. This tool runs nightly, and the results are published on the vscode-theia-comparator GitHub page. Prerequisites Personal GitHub access token. See Creating a personal access token for the command line . A GitHub access token is required to increase the GitHub download limit for your IP address. Procedure To run the vscode-theia comparator manually: Clone the vscode-theia-comparator repository, and build it using the yarn command. Set the GITHUB_TOKEN environment variable to your token. Execute the yarn run generate command to generate a report. Open the out/status.html file to view the report. 5.6. Using alternative IDEs in CodeReady Workspaces Red Hat CodeReady Workspaces provides a default web IDE to use in the developer workspaces. To use another editor, see: Section 5.7, "Configuring a workspace to use an IDE based on the IntelliJ Platform" Section 5.8, "Theia-based IDEs" 5.7. Configuring a workspace to use an IDE based on the IntelliJ Platform This section describes how to configure a workspace to use an IDE based on the IntelliJ Platform . No initial repository checkout when running the CodeReady Workspaces Server workspaces engine When the CodeReady Workspaces instance is running the CodeReady Workspaces Server workspaces engine, the workspace starts without an initial checkout of the code repositories referenced in the devfile. Workarounds In the IDE, click Get from VCS to checkout a repository. To enable the automatic initial checkout of the code repositories in the devfile, use the Dev Workspace operator. 5.7.1. Configuring a workspace to use IntelliJ IDEA Community This section describes how to configure a workspace devfile to use IntelliJ IDEA Community. Procedure Add the following component to the workspace devfile: components: - type: cheEditor id: registry.redhat.io/codeready-workspaces/idea-rhel8:2.15 Remove the plugins or commands defined for the Theia IDE from the workspace devfile. Restart the workspace. 5.7.2. Configuring a workspace to use PyCharm Community This section describes how to configure a workspace devfile to use PyCharm Community. Procedure Add the following component to the workspace devfile: components: - type: cheEditor reference: https://raw.githubusercontent.com/che-incubator/jetbrains-editor-images/meta/che-pycharm/latest.meta.yaml Remove the plugins or commands defined for the Theia IDE from the workspace devfile. Restart the workspace. 5.7.3. Configuring a workspace to use a custom image with an IDE based on the IntelliJ Platform This section describes how to configure a workspace to use an IDE based on the IntelliJ Platform. Prerequisites CodeReady Workspaces has access to metadata and image with the desired IDE based on the IntelliJ Platform. See Section 5.7.4, "Building images for IDEs based on the IntelliJ Platform" . Procedure Add the following component to the workspace devfile: components: - type: cheEditor reference: " <URL_to_meta.yaml> " 1 1 <URL_to_meta.yaml> : HTTPS resource defining the IDE metadata, see Section 5.7.4, "Building images for IDEs based on the IntelliJ Platform" . Remove the plugins or commands defined for the Theia IDE from the workspace devfile. Restart the workspace. 5.7.4. Building images for IDEs based on the IntelliJ Platform This section describes how to build images for IDEs based on the IntelliJ Platform version 2020.3 . 5.7.4.1. Building an image for IntelliJ IDEA Community or PyCharm Community This procedure describes how to build an image for IntelliJ IDEA Community or PyCharm Community. Prerequisites The build host has at least 2 GB of available RAM. The following tools are installed on the build host: Docker version 18.09 or greater, supporting BuildKit Git GNU getopt GNU wget Java Development Kit (JDK) version 11 jq Procedure Get a local copy of the JetBrains Projector Editor Images repository . Run the build script and select the IDE package and package version: To test the image, run it locally and go to http://localhost:8887 to access the IDE. Publish the image to a registry accessible by CodeReady Workspaces, and remember the location: <registry>/<image>:<tag> . Create a meta.yaml file with the following content: apiVersion: v2 publisher: <publisher> 1 name: intellij-ide version: latest type: Che Editor displayName: IntelliJ Platform IDE title: IDE based on the IntelliJ Platform description: IDE based on the IntelliJ Platform running using Projector icon: https://www.jetbrains.com/apple-touch-icon.png category: Editor repository: https://github.com/che-incubator/jetbrains-editor-images firstPublicationDate: "2021-04-10" spec: endpoints: - name: intellij public: true targetPort: 8887 attributes: protocol: http type: ide path: /projector-client/index.html?backgroundColor=434343&wss containers: - name: intellij-ide image: <registry>/<image>:<tag> 2 mountSources: true volumes: - mountPath: "/home/projector-user" name: projector-user ports: - exposedPort: 8887 memoryLimit: "4096M" 1 <publisher> : Your publisher name. 2 <registry>/<image>:<tag> : Location of the IDE image in a registry accessible by CodeReady Workspaces. Publish the meta.yaml file to an HTTPS resource accessible by CodeReady Workspaces and copy the resulting URL for use as <URL_to_meta.yaml> when configuring a workspace to use this IDE. steps Section 5.7, "Configuring a workspace to use an IDE based on the IntelliJ Platform" 5.7.4.2. Building an image for an IDE based on the IntelliJ Platform This procedure describes how to build an image for an IDE based on the IntelliJ Platform version 2020.3 . For JetBrains IDEs, the IDE version number corresponds to the version of the IntelliJ Platform. See the list of compatible IDEs . Prerequisites The build host has at least 2 GB of available RAM. The following tools are installed on the build host: Docker version 18.09 or greater, supporting BuildKit Git GNU getopt GNU wget Java Development Kit (JDK) version 11 jq Procedure Get a local copy of the JetBrains Projector Editor Images repository . Run the build script with parameters: --tag <tag> The name and tag to apply to the image after build in name:tag format. --url <url> The URL pointing to an archive of the IDE based on the IntelliJ Platform version 2020.3 . The archive must target the Linux platform, be in tar.gz format, and include JetBrains Runtime (JBR). Example 5.1. Building the image with IntelliJ IDEA Community 2020.3.3 Example 5.2. Building the image with PyCharm Community 2020.3.5 Example 5.3. Building the image with WebStorm 2020.3.3 Example 5.4. Building the image with IntelliJ IDEA Ultimate 2020.2.2 Example 5.5. Building the image with Android Studio 4.2.0.22 To test the image, run it locally and go to http://localhost:8887 to access the IDE. Example 5.6. Testing the image with IntelliJ IDEA Community 2020.3.3 Example 5.7. Testing the image with PyCharm 2020.3.5 Example 5.8. Testing the image with WebStorm 2020.3.3 Example 5.9. Testing the image with IntelliJ IDEA Ultimate 2020.2.2 Example 5.10. Testing the image with Android Studio 4.2.0.22 Publish the image to a registry accessible by CodeReady Workspaces, and remember the location: <registry>/<image>:<tag> . Create a meta.yaml file containing the IDE metadata for CodeReady Workspaces: apiVersion: v2 publisher: <publisher> 1 name: intellij-ide version: latest type: Che Editor displayName: IntelliJ Platform IDE title: IDE based on the IntelliJ Platform description: IDE based on the IntelliJ Platform running using Projector icon: https://www.jetbrains.com/apple-touch-icon.png category: Editor repository: https://github.com/che-incubator/jetbrains-editor-images firstPublicationDate: "2021-04-10" spec: endpoints: - name: intellij public: true targetPort: 8887 attributes: protocol: http type: ide path: /projector-client/index.html?backgroundColor=434343&wss containers: - name: intellij-ide image: <registry>/<image>:<tag> 2 mountSources: true volumes: - mountPath: "/home/projector-user" name: projector-user ports: - exposedPort: 8887 memoryLimit: "4096M" 1 <publisher> : Your publisher name. 2 <registry>/<image>:<tag> : Location of the IDE image in a registry accessible by CodeReady Workspaces. Publish the meta.yaml file to an HTTPS resource accessible by CodeReady Workspaces and copy the resulting URL for use as <URL_to_meta.yaml> when configuring a workspace to use this IDE. steps Section 5.7, "Configuring a workspace to use an IDE based on the IntelliJ Platform" 5.7.5. Provisioning the JetBrains offline activation code Some editions of JetBrains IDEs require a paid subscription beyond the evaluation period, which means buying a license from JetBrains. To register a license, you need to provision to CodeReady Workspaces the JetBrains activation code for offline usage. When you renew your subscription, you will need to generate and provision a new offline activation code. Prerequisites An active JetBrains subscription associated to an active JetBrains account . The OpenSSL and oc tools are installed. An image containing the IDE. See Section 5.7.4, "Building images for IDEs based on the IntelliJ Platform" . A workspace running with the IDE. See Section 5.7, "Configuring a workspace to use an IDE based on the IntelliJ Platform" . Procedure Log in to your JetBrains account , choose the desired subscription, and click on the Download activation code for offline usage link. Extract from the downloaded zip archive the file named <License ID> - for 2018.1 or later.txt . Convert the activation code to a base64 encoded single line for use in the step as <base64_encoded_activation_code> . Create a secret.yaml file defining the OpenShift Secret to provision the activation code to CodeReady Workspaces. apiVersion: v1 kind: Secret metadata: name: jetbrains-offline-activation-code labels: app.kubernetes.io/component: workspace-secret app.kubernetes.io/part-of: che.eclipse.org annotations: che.eclipse.org/automount-workspace-secret: 'false' 1 che.eclipse.org/mount-path: /tmp/ che.eclipse.org/mount-as: file data: idea.key: <base64_encoded_activation_code> pycharm.key: <base64_encoded_activation_code> webstorm.key: <base64_encoded_activation_code> phpstorm.key: <base64_encoded_activation_code> goland.key: <base64_encoded_activation_code> 1 che.eclipse.org/automount-workspace-secret: 'false' : disables the mounting process until a workspace component explicitly requests it with the automountWorkspaceSecrets: true property. Apply the OpenShift Secret to the OpenShift project running the workspace. To mount the activation codes into a workspace, update the workspace devfile configuration to set automountWorkspaceSecrets: true . components: - type: cheEditor automountWorkspaceSecrets: true reference: " <URL_to_meta.yaml> " Restart the workspace. 5.8. Theia-based IDEs This section describes how to provide a custom IDE, based on Eclipse Theia framework. To use a Theia-based IDE in Red Hat CodeReady Workspaces as an editor, you need to prepare two main components: a Docker image containing your IDE the Che editor descriptor file - meta.yaml Procedure Describe the IDE with an editor descriptor - meta.yaml file: version: 1.0.0 editors: - id: eclipse/che-theia/ title: Eclipse Theia development version. displayName: theia-ide description: Eclipse Theia, get the latest release each day. icon: https://raw.githubusercontent.com/theia-ide/theia/master/logo/theia-logo-no-text-black.svg?sanitize=true repository: https://github.com/eclipse-che/che-theia firstPublicationDate: "2021-01-01" endpoints: - name: "theia" public: true targetPort: 3100 attributes: protocol: http type: ide secure: true cookiesAuthEnabled: true discoverable: false containers: - name: theia-ide image: "<your-ide-image>" mountSources: true ports: - exposedPort: 3100 memoryLimit: "512M" targetPort and exposedPort must be the same as the Theia-based IDE running inside the container. Replace <your-ide-image> with the name of the IDE image. The meta.yaml file should be publicly accessible through an HTTP(S) link. Add your editor to a Devfile: apiVersion: 1.0.0 metadata: name: che-theia-based-ide components: - type: cheEditor reference: '<meta.yaml URL>' <meta.yaml URL> should point to the publicly hosted meta.yaml file described in the step. 5.9. 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. Section 5.9.1, "Additional tools in the CodeReady Workspaces workspace" Section 5.9.2, "Adding a language support plug-in to a CodeReady Workspaces workspace" 5.9.1. Additional tools in the CodeReady Workspaces workspace CodeReady Workspaces plug-ins are extensions to the Che-Theia IDE that come bundled with container images. These images contain the native prerequisites of their respective extensions. For example, the OpenShift command-line tool is bundled with a command to install it, which ensures the proper functionality of the OpenShift Connector plug-in, all available in the dedicated image. 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 Visual Studio Code extensions API and Visual Studio Code extensions are automatically compatible with Che-Theia. These extensions are possible to package as CodeReady Workspaces plug-ins by combining them with their dependencies. By default, CodeReady Workspaces includes a plug-in registry containing common plug-ins. Adding a plug-in Using the Dashboard: Add a plug-in directly into a devfile using the Devfile tab. The devfile can also further the plug-in configuration, such as defining memory or CPU consumption. Using the Che-Theia IDE: By pressing Ctrl + Shift + J or by navigating to View Plugins . Additional resources Adding components to a devfile 5.9.2. Adding a language support plug-in to a CodeReady Workspaces workspace This procedure describes adding a tool to a created workspace by enabling a dedicated plug-in from the Dashboard. Edit the workspace devfile from the Dashboard Devfile tab. Prerequisites A running instance of CodeReady Workspaces. See Installing CodeReady Workspaces . A created workspace that is defined in this instance of Red Hat CodeReady Workspaces. See ] and xref:creating-a-workspace-from-a-code-sample_crw[ . The workspace must be in a stopped state. The steps to stop a workspace: Navigate to the CodeReady Workspaces Dashboard, as explained in Section 1.1, "Navigating CodeReady Workspaces using the Dashboard" . In the Dashboard , click the Workspaces menu to open the workspaces list and locate the workspace. On the same row with the displayed workspace, on the right side of the screen, click Stop to stop the workspace. Wait a few seconds for the workspace to stop, and then configure the workspace by selecting it. Procedure To add a plug-in from the plug-in registry to a created CodeReady Workspaces workspace, install the plug-in as follows by adding content to the devfile: Navigate to the Devfile tab, where the devfile YAML is displayed. In the components devfile section, add the following lines: id and type . Example: Adding the Java 8 language plug-in - id: redhat/java8/latest type: chePlugin Example: The end 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 Click Save to save the changes. Restart the workspace. Verify that the workspace includes the new plug-in. Additional resources Devfile specifications 5.10. Using private container registries This section describes the necessary steps to use container images from private container registries. Prerequisites A running instance of CodeReady Workspaces. See https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.15/html-single/installation_guide/index#installing-che.adoc . Procedure Navigate to the CodeReady Workspaces Dashboard. See Section 1.1, "Navigating CodeReady Workspaces using the Dashboard" . Navigate to User Preferences . Click on your username in the top right corner. Click the User Preferences tab. Click the Add Container Registry button in Container Registries tab and execute following actions: Enter the container registry domain name in the Registry field. Optionally, enter the username of your account at this registry in the Username field. Enter the password in the Password field to authenticate in the container registry. Click the Add button. Verification See that there is a new entry in the Container Registries tab. Create a workspace that uses a container image from the specified container registry. See Section 4.2, "Authoring a devfile 2" . Additional resources Kubernetes documentation: Pull an Image from a Private Registry

Commands:
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/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']
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: Visual Studio 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
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 "USD{HOME}" CMD USD{PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}
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 "USD{HOME}" ENTRYPOINT USD{PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}
#!/bin/sh set -e export USER_ID=USD(id -u) export GROUP_ID=USD(id -g) if ! whoami >/dev/null 2>&1; then echo "USD{USER_NAME:-user}:x:USD{USER_ID}:0:USD{USER_NAME:-user} user:USD{HOME}:/bin/sh" >> /etc/passwd fi Grant access to projects volume in case of non root user with sudo rights if [ "USD{USER_ID}" -ne 0 ] && command -v sudo >/dev/null 2>&1 && sudo -n true > /dev/null 2>&1; then sudo chown "USD{USER_ID}:USD{GROUP_ID}" /projects fi exec "USD@"
FROM alpine:3.10.2 ENV HOME=/home/theia RUN mkdir /projects USD{HOME} && # Change permissions to let any arbitrary user for f in "USD{HOME}" "/etc/passwd" "/projects"; do echo "Changing permissions on USD{f}" && chgrp -R 0 USD{f} && chmod -R g+rwX USD{f}; done ADD entrypoint.sh /entrypoint.sh ENTRYPOINT [ "/entrypoint.sh" ] CMD USD{PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}
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: "Visual Studio 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: - USD{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"
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: "Visual Studio 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 - USD{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"
- type: chePlugin id: 1
- type: chePlugin reference: 1
- id: publisher/my-vscode-ext 1 repository: 2 url: https://github.com/publisher/my-vscode-ext 3 revision: 1.7.2 4 aliases: 5 - publisher/my-vscode-ext-revised preferences: 6 asciidoc.use_asciidoctorpdf: true shellcheck.executablePath: /bin/shellcheck solargraph.bundlerPath: /usr/local/bin/bundle solargraph.commandPath: /usr/local/bundle/bin/solargraph sidecar: 7 image: quay.io/repository/eclipse/che-plugin-sidecar:sonarlint-2fcf341 8 name: my-vscode-ext-sidecar 9 memoryLimit: "1500Mi" 10 memoryRequest: "1000Mi" 11 cpuLimit: "500m" 12 cpuRequest: "125m" 13 command: 14 - /bin/sh args: 15 - "-c" - "./entrypoint.sh" volumeMounts: 16 - name: vscode-ext-volume 17 path: "/home/theia/my-vscode-ext" 18 endpoints: 19 - name: "configuration-endpoint" 20 public: true 21 targetPort: 61436 22 attributes: 23 protocol: http extension: https://github.com/redhat-developer/vscode-yaml/releases/download/0.4.0/redhat.vscode-yaml-0.4.0.vsix 24 skipDependencies: 25 - id-of/extension1 - id-of/extension2 extraDependencies: 26 - id-of/extension1 - id-of/extension2 metaYaml: skipIndex: <true|false> 27 skipDependencies: 28 - id-of/extension1 - id-of/extension2 extraDependencies: 29 - id-of/extension1 - id-of/extension2
apiVersion: v2 1 publisher: myorg 2 name: my-vscode-ext 3 version: 1.7.2 4 type: value 5 displayName: 6 title: 7 description: 8 icon: https://www.eclipse.org/che/images/logo-eclipseche.svg 9 repository: 10 category: 11 spec: containers: 12 - image: 13 memoryLimit: 14 memoryRequest: 15 cpuLimit: 16 cpuRequest: 17 extensions: 18 - https://github.com/redhat-developer/vscode-yaml/releases/download/0.4.0/redhat.vscode-yaml-0.4.0.vsix - https://github.com/SonarSource/sonarlint-vscode/releases/download/1.16.0/sonarlint-vscode-1.16.0.vsix
components: - id: joaopinto/vscode-asciidoctor/latest type: chePlugin
git clone https://gist.github.com/ <your-github-username> / <gist-id>
git clone https://gist.github.com/benoitf/85c60c8c439177ac50141d527729b9d9 1 Cloning into '85c60c8c439177ac50141d527729b9d9' remote: Enumerating objects: 3, done. remote: Counting objects: 100% (3/3), done. remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 Unpacking objects: 100% (3/3), done.
cd <gist-directory-name> 1
apiVersion: v2 publisher: CoenraadS name: bracket-pair-colorizer version: 1.0.61 type: Visual Studio Code extension displayName: Bracket Pair Colorizer title: Bracket Pair Colorizer description: Bracket Pair Colorizer icon: https://raw.githubusercontent.com/redhat-developer/codeready-workspaces/crw-2-rhel-8/dependencies/che-plugin-registry/resources/images/default.svg?sanitize=true repository: https://github.com/CoenraadS/BracketPair category: Language firstPublicationDate: '2020-07-30' spec: 1 extensions: - "{{REPOSITORY}}/CoenraadS.bracket-pair-colorizer-1.0.61.vsix" 2 latestUpdateDate: "2020-07-30"
spec: containers: - image: "quay.io/eclipse/che-sidecar-java:8-0cfbacb" name: vscode-java memoryLimit: "1500Mi" volumes: - mountPath: "/home/theia/.m2" name: m2
apiVersion: 1.0.0 metadata: generateName: java-maven- projects: - name: console-java-simple source: type: git location: "https://github.com/che-samples/console-java-simple.git" branch: java1.11 components: - type: chePlugin id: redhat/java11/latest - type: chePlugin 1 reference: "{{REPOSITORY}}/plugin.yaml" - type: dockerimage alias: maven image: quay.io/eclipse/che-java11-maven:nightly memoryLimit: 512Mi mountSources: true volumes: - name: m2 containerPath: /home/user/.m2 commands: - name: maven build actions: - type: exec component: maven command: "mvn clean install" workdir: USD{CHE_PROJECTS_ROOT}/console-java-simple - name: maven build and run actions: - type: exec component: maven command: "mvn clean install && java -jar ./target/*.jar" workdir: USD{CHE_PROJECTS_ROOT}/console-java-simple
ls -la .git CoenraadS.bracket-pair-colorizer-1.0.61.vsix README.md devfile.yaml plugin.yaml
#!/bin/sh get modified files FILES=USD(git diff --cached --name-only --diff-filter=ACMR "*.yaml" | sed 's| |\\ |g') exit fast if no files found [ -z "USDFILES" ] && exit 0 grab remote origin origin=USD(git config --get remote.origin.url) url="USD{origin}/raw" iterate on files and add the good prefix pattern for FILE in USD{FILES}; do sed -e "s#{{REPOSITORY}}#USD{url}#g" "USD{FILE}" > "USD{FILE}.back" mv "USD{FILE}.back" "USD{FILE}" done Add back to staging echo "USDFILES" | xargs git add exit 0
chmod u+x .git/hooks/pre-commit
Add files git add * Commit git commit -m "Initial Commit for the test of our extension" [main 98dd370] Initial Commit for the test of our extension 3 files changed, 61 insertions(+) create mode 100644 CoenraadS.bracket-pair-colorizer-1.0.61.vsix create mode 100644 devfile.yaml create mode 100644 plugin.yaml and push the files to the main branch git push origin
echo "USD(git config --get remote.origin.url)/raw/devfile.yaml"
echo "https:// <che-server> /#USD(git config --get remote.origin.url)/raw/devfile.yaml"
components: - type: cheEditor id: registry.redhat.io/codeready-workspaces/idea-rhel8:2.15
components: - type: cheEditor reference: https://raw.githubusercontent.com/che-incubator/jetbrains-editor-images/meta/che-pycharm/latest.meta.yaml
components: - type: cheEditor reference: " <URL_to_meta.yaml> " 1
git clone https://github.com/che-incubator/jetbrains-editor-images cd jetbrains-editor-images
./projector.sh build [info] Select the IDE package to build (default is 'IntelliJ IDEA Community'): 1) IntelliJ IDEA Community 2) PyCharm Community [info] Select the IDE package version to build (default is '2020.3.3'): 1) 2020.3.3 2) 2020.3.2 3) 2020.3.1
./projector.sh run
apiVersion: v2 publisher: <publisher> 1 name: intellij-ide version: latest type: Che Editor displayName: IntelliJ Platform IDE title: IDE based on the IntelliJ Platform description: IDE based on the IntelliJ Platform running using Projector icon: https://www.jetbrains.com/apple-touch-icon.png category: Editor repository: https://github.com/che-incubator/jetbrains-editor-images firstPublicationDate: "2021-04-10" spec: endpoints: - name: intellij public: true targetPort: 8887 attributes: protocol: http type: ide path: /projector-client/index.html?backgroundColor=434343&wss containers: - name: intellij-ide image: <registry>/<image>:<tag> 2 mountSources: true volumes: - mountPath: "/home/projector-user" name: projector-user ports: - exposedPort: 8887 memoryLimit: "4096M"
git clone https://github.com/che-incubator/jetbrains-editor-images cd jetbrains-editor-images
./projector build --tag <tag> --url <URL>
./projector.sh build --tag che-idea:2020.3.3 --url https://download-cdn.jetbrains.com/idea/ideaIC-2020.3.3.tar.gz
./projector.sh build --tag che-pycharm:2020.3.5 --url https://download.jetbrains.com/python/pycharm-community-2020.3.5.tar.gz
./projector.sh build --tag che-webstorm:2020.3.3 --url https://download.jetbrains.com/webstorm/WebStorm-2020.3.3.tar.gz
./projector.sh build --tag che-idea-ultimate:2020.2.2 --url https://download.jetbrains.com/idea/ideaIU-2020.2.2.tar.gz
./projector.sh build --tag che-android-studio:4.2.0.22 --url https://redirector.gvt1.com/edgedl/android/studio/ide-zips/4.2.0.22/android-studio-ide-202.7188722-linux.tar.gz
./projector.sh run <tag>
./projector.sh run che-idea:2020.3.3
./projector.sh run che-pycharm:2020.3.5
./projector.sh run che-webstorm:2020.3.3
./projector.sh run che-idea-ultimate:2020.2.2
./projector.sh run che-android-studio:4.2.0.22
apiVersion: v2 publisher: <publisher> 1 name: intellij-ide version: latest type: Che Editor displayName: IntelliJ Platform IDE title: IDE based on the IntelliJ Platform description: IDE based on the IntelliJ Platform running using Projector icon: https://www.jetbrains.com/apple-touch-icon.png category: Editor repository: https://github.com/che-incubator/jetbrains-editor-images firstPublicationDate: "2021-04-10" spec: endpoints: - name: intellij public: true targetPort: 8887 attributes: protocol: http type: ide path: /projector-client/index.html?backgroundColor=434343&wss containers: - name: intellij-ide image: <registry>/<image>:<tag> 2 mountSources: true volumes: - mountPath: "/home/projector-user" name: projector-user ports: - exposedPort: 8887 memoryLimit: "4096M"
openssl base64 -e -A -in ' <License ID> - for 2018.1 or later.txt'
apiVersion: v1 kind: Secret metadata: name: jetbrains-offline-activation-code labels: app.kubernetes.io/component: workspace-secret app.kubernetes.io/part-of: che.eclipse.org annotations: che.eclipse.org/automount-workspace-secret: 'false' 1 che.eclipse.org/mount-path: /tmp/ che.eclipse.org/mount-as: file data: idea.key: <base64_encoded_activation_code> pycharm.key: <base64_encoded_activation_code> webstorm.key: <base64_encoded_activation_code> phpstorm.key: <base64_encoded_activation_code> goland.key: <base64_encoded_activation_code>
oc apply -f secret.yaml
components: - type: cheEditor automountWorkspaceSecrets: true reference: " <URL_to_meta.yaml> "
version: 1.0.0 editors: - id: eclipse/che-theia/next title: Eclipse Theia development version. displayName: theia-ide description: Eclipse Theia, get the latest release each day. icon: https://raw.githubusercontent.com/theia-ide/theia/master/logo/theia-logo-no-text-black.svg?sanitize=true repository: https://github.com/eclipse-che/che-theia firstPublicationDate: "2021-01-01" endpoints: - name: "theia" public: true targetPort: 3100 attributes: protocol: http type: ide secure: true cookiesAuthEnabled: true discoverable: false containers: - name: theia-ide image: "<your-ide-image>" mountSources: true ports: - exposedPort: 3100 memoryLimit: "512M"
apiVersion: 1.0.0 metadata: name: che-theia-based-ide components: - type: cheEditor reference: '<meta.yaml URL>'
- id: redhat/java8/latest type: chePlugin
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