Chapter 4. Customizing developer environments

1. CodeReady Workspaces server checks for plug-ins to start from the workspace definition.
2. CodeReady Workspaces server retrieves plug-in metadata, recognizes each plug-in type, and stores them in memory.
3. CodeReady Workspaces server selects a broker according to the plug-in type.
4. The broker processes the installation and deployment of the plug-in. The installation process of the plug-in differs for each specific broker.

1. The Che-Theia plug-in broker extracts the information about sidecar containers that a particular plug-in needs from the .theia file.
2. The broker sends the appropriate container information to CodeReady Workspaces server.
3. The broker copies the Che-Theia plug-in to a volume to have it available for the Che-Theia editor container.
4. CodeReady Workspaces server then starts all the containers of the workspace.
5. 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

1. 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
2. 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.
3. A Che-Theia plug-in session runs and interacts with the Che-Theia backend and frontend.
4. 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.

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

2. Click the devfile tab.

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

4. Restart the workspace for the changes to take effect.

Procedure

1. 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 VS Code extension. (Bracket Pair Colorizer is a popular VS Code extension.)
2. Click the Create secret gist button.

3. Clone the gist repository by using the URL from the navigation bar of the browser:

   $ git clone https://gist.github.com/<your-github-username>/<gist-id>

   Example of the output of the git clone command

   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.

   1

   Each gist has a unique ID.

4. Change the directory:

   $ cd <gist-directory-name> 1

   1

   Directory name matching the gist ID.

5. Download the plug-in from the VS Code marketplace or from its GitHub page, and store the plug-in file in the cloned directory.

6. 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: VS Code extension
   displayName: Bracket Pair Colorizer
   title: Bracket Pair Colorizer
   description: Bracket Pair Colorizer
   icon: https://raw.githubusercontent.com/redhat-developer/codeready-workspaces/master/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.

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

8. 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: ${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: ${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.

9. Verify there are 4 files in the current Git directory:

   $ ls -la
   .git
   CoenraadS.bracket-pair-colorizer-1.0.61.vsix
   README.md
   devfile.yaml
   plugin.yaml

10. Before committing the files, add a pre-commit hook to update the {{REPOSITORY}} variable to the public external raw gist link:

    1. Create a .git/hooks/pre-commit file with this content:

       #!/bin/sh
       
       # get modified files
       FILES=$(git diff --cached --name-only --diff-filter=ACMR "*.yaml" | sed 's| |\\ |g')
       
       # exit fast if no files found
       [ -z "$FILES" ] && exit 0
       
       # grab remote origin
       origin=$(git config --get remote.origin.url)
       url="${origin}/raw"
       
       # iterate on files and add the good prefix pattern
       for FILE in ${FILES}; do
        sed -e "s#{{REPOSITORY}}#${url}#g" "${FILE}" > "${FILE}.back"
        mv "${FILE}.back" "${FILE}"
       done
       
       # Add back to staging
       echo "$FILES" | xargs git add
       
       exit 0

       The hook replaces the {{REPOSITORY}} macro and adds the external raw link to the gist.

    2. Make the script executable:

       $ chmod u+x .git/hooks/pre-commit

11. Commit and push the files:

    # Add files
    $ git add *
    
    # Commit
    $ git commit -m "Initial Commit for the test of our extension"
    [master 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

12. 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:

    $ echo "$(git config --get remote.origin.url)/raw/devfile.yaml"

    or:

    $ echo "https://<che-server>/#$(git config --get remote.origin.url)/raw/devfile.yaml"

1. Clone the vscode-theia-comparator repository, and build it using the yarn command.
2. Set the GITHUB_TOKEN environment variable to your token.
3. Execute the yarn run generate command to generate a report.
4. Open the out/status.html file to view the report.

Procedure

1. Clone the che-editor-intellij-community repository, which is needed to build IntelliJ Idea Community Edition located under the che-incubator organization.

2. Build IntelliJ Idea Community Edition by calling the following command inside the repository folder:

   $ podman build -t idea-ic --build-arg PRODUCT_NAME=ideaIC .

   This command builds an image with a 2020.2.3 version by default.

3. Tag and push the built image to a user repository:

   $ podman tag idea-ic:latest <username>/idea-ic:latest
   $ podman push <username>/idea-ic:latest

4. Use this image as the CodeReady Workspaces editor. To achieve this, create two YAML configuration files:

   • workspace.yaml – workspace configuration. Do not forget to provide a correct URL to the meta.yaml file:

     metadata:
       name: che-ideaic
     components:
       - type: cheEditor
         reference: '<URL to the meta.yaml>'
         alias: ideaic-editor
     apiVersion: 1.0.0

   • meta.yaml – CodeReady Workspaces editor configuration. Do not forget to replace <username> with the user name of the repository to which the image is pushed:

     apiVersion: v2
     publisher: <username>
     name: ideaic-NOVNC
     version: 2020.2.3
     type: Che Editor
     displayName:  IntelliJ IDEA Community Edition
     title:  IntelliJ IDEA Community Edition (in browser using noVNC) as editor for Red Hat CodeReady Workspaces
     description:  IntelliJ IDEA Community Edition running on the Web with noVNC
     icon: https://resources.jetbrains.com/storage/products/intellij-idea/img/meta/intellij-idea_logo_300x300.png
     category: Editor
     repository: https://github.com/che-incubator/che-editor-intellij-community
     firstPublicationDate: "2020-10-27"
     spec:
       endpoints:
        - name: "intellij"
          public: true
          targetPort: 8080
          attributes:
            protocol: http
            type: ide
            path: /vnc.html?resize=remote&autoconnect=true&reconnect=true
       containers:
        - name: ideaic-novnc
          image: "<username>/idea-ic:latest"
          mountSources: true
          volumes:
           - mountPath: "/JetBrains/ideaIC"
             name: ideaic-configuration
          ports:
           - exposedPort: 8080
          memoryLimit: "2048M"

Procedure

1. Clone the che-editor-intellij-community repository, which is needed to build IntelliJ Idea Community Edition located under the che-incubator organization.

2. Build IntelliJ Idea Ultimate Edition by calling the following command inside the repository folder:

   $ podman build -t idea-iu --build-arg PRODUCT_NAME=ideaIU .

   This command builds an image with a 2020.2.3 version by default.

3. Tag and push the built image to a user repository:

   $ podman tag idea-iu:latest <username>/idea-iu:latest
   $ podman push <username>/idea-iu:latest

4. Provision the activation code for offline use to be able to use WebStorm with a registered license. See section Section 4.6.4, “Provisioning JetBrains activation code for offline use”.

5. Create a workspace with the following workspace.yaml and meta.yaml files:

   • workspace.yaml – workspace configuration. Do not forget to provide a correct URL to the meta.yaml file:

     metadata:
       name: che-ideaiu
     components:
       - type: cheEditor
         reference: '<URL to the meta.yaml>'
         alias: ideaiu-editor
         automountWorkspaceSecrets: true
     apiVersion: 1.0.0

     Note

     In the current workspace definition, there is a new property: automountWorkspaceSecrets: true. This property instructs Red Hat CodeReady Workspaces to provision secrets into a specific component. In this case, it provisions it into the CodeReady Workspaces editor based on IntelliJ Idea Ultimate Edition. This parameter is mandatory to successfully register the IDE with an activation code for offline use.

   • meta.yaml – CodeReady Workspaces editor configuration. Do not forget to replace <username> with the user name of the repository to which the image is pushed:

     apiVersion: v2
     publisher: <username>
     name: ideaIU-NOVNC
     version: 2020.2.3
     type: Che Editor
     displayName:  IntelliJ IDEA Ultimate Edition
     title:  IntelliJ IDEA Ultimate Edition (in browser using noVNC) as editor for Red Hat CodeReady Workspaces
     description:  IntelliJ IDEA Ultimate Edition running on the Web with noVNC
     icon: https://resources.jetbrains.com/storage/products/intellij-idea/img/meta/intellij-idea_logo_300x300.png
     category: Editor
     repository: https://github.com/che-incubator/che-editor-intellij-community
     firstPublicationDate: "2020-10-27"
     spec:
       endpoints:
        -  name: "intellij"
           public: true
           targetPort: 8080
           attributes:
             protocol: http
             type: ide
             path: /vnc.html?resize=remote&autoconnect=true&reconnect=true
       containers:
        - name: ideaiu-novnc
          image: "<username>/idea-iu:latest"
          mountSources: true
          volumes:
              - mountPath: "/JetBrains/ideaIU"
                name: ideaiu-configuration
          ports:
              - exposedPort: 8080
          memoryLimit: "2048M"

Procedure

1. Clone the che-editor-intellij-community repository, which is needed to build IntelliJ Idea Community Edition located under the che-incubator organization.

2. Build the image:

   $ podman build -t webstorm --build-arg PRODUCT_NAME=WebStorm .

   This command builds an image with a 2020.2.3 version by default.

3. Tag and push the built image to a user repository:

   $ podman tag webstorm:latest <username>/webstorm:latest
   $ podman push <username>/webstorm:latest

4. Provision the activation code for offline use to be able to use WebStorm with a registered license. See section Section 4.6.4, “Provisioning JetBrains activation code for offline use”.

5. Create a workspace with the following workspace.yaml and meta.yaml files:

   • workspace.yaml – workspace configuration. Do not forget to provide a correct URL to the meta.yaml file:

     metadata:
       name: che-webstorm
     components:
       - type: cheEditor
         reference: '<URL to meta.yaml>'
         alias: webstorm-editor
         automountWorkspaceSecrets: true
     apiVersion: 1.0.0

     Note

     In the current workspace definition, there is a new property: automountWorkspaceSecrets: true. This property instructs Red Hat CodeReady Workspaces to provision secrets into a specific component. In this case, it provisions it into the CodeReady Workspaces editor based on IntelliJ Idea Ultimate Edition. This parameter is mandatory to successfully register the IDE with an activation code for offline use.

   • meta.yaml – CodeReady Workspaces editor configuration. Do not forget to replace <username> with the user name of the repository to which the image is pushed:

     apiVersion: v2
     publisher: <username>
     name: webstorm-NOVNC
     version: 2020.2.3
     type: Che Editor
     displayName:  WebStorm
     title:  WebStorm (in browser using noVNC) as editor for Red Hat CodeReady Workspaces
     description:  WebStorm running on the Web with noVNC
     icon: https://resources.jetbrains.com/storage/products/webstorm/img/meta/webstorm_logo_300x300.png
     category: Editor
     repository: https://github.com/che-incubator/che-editor-intellij-community
     firstPublicationDate: "2020-10-27"
     spec:
       endpoints:
        - name: "intellij"
          public: true
          targetPort: 8080
          attributes:
            protocol: http
            type: ide
            path: /vnc.html?resize=remote&autoconnect=true&reconnect=true
       containers:
        - name: webstorm-novnc
          image: "<username>/webstorm:latest"
          mountSources: true
          volumes:
           - mountPath: "/JetBrains/WebStorm"
             name: webstorm-configuration
          ports:
           - exposedPort: 8080
          memoryLimit: "2048M"

Procedure

1. Retrieve the activation code from the JetBrains account:

   

   JetBrains provides a zip archive with two types of the activation code. Use the <License ID> - for 2018.1 or later.txt file:

   
2. Provision the activation code for offline use with Che. This procedure is performed through the OpenShift Secrets.

3. Create a OpenShift Secret to instruct CodeReady Workspaces to mount the activation code into a container based on JetBrains specific product:

   apiVersion: v1
   kind: Secret
   metadata:
     name: <secret name> 1
     labels:
       app.kubernetes.io/component: workspace-secret
       app.kubernetes.io/part-of: che.eclipse.org
     annotations:
       che.eclipse.org/automount-workspace-secret: 'false'
       che.eclipse.org/mount-path: /tmp/
       che.eclipse.org/mount-as: file
   data:
     <product name (ideaIU or WebStorm)>.key: <base64-encoded data content> 2

   1

   <secret name> – The section that specifies the secret name. It may have a different name, for example, ideaiu-offline-activation-code. Provide the secret name in lowercase.

   2

   Product name and activation code:

   • <product name (ideaIU or WebStorm)> – Replace with the JetBrains product name. See section Section 4.6.4.1, “JetBrains product-name mapping”.
   • <base64-encoded data content> – The activation code content encoded in base64.