Chapter 5. 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/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.

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"
    [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

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. Add the following component to the workspace devfile:

   components:
     - type: cheEditor
       id: registry.redhat.io/codeready-workspaces/idea-rhel8:2.13

2. Remove the plugins or commands defined for the Theia IDE from the workspace devfile.
3. Restart the workspace.

Procedure

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

2. Remove the plugins or commands defined for the Theia IDE from the workspace devfile.
3. Restart the workspace.

Procedure

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

2. Remove the plugins or commands defined for the Theia IDE from the workspace devfile.
3. Restart the workspace.

Procedure

1. Log in to your JetBrains account, choose the desired subscription, and click on the Download activation code for offline usage link.
2. Extract from the downloaded zip archive the file named <License ID> - for 2018.1 or later.txt.

3. Convert the activation code to a base64 encoded single line for use in the next step as <base64_encoded_activation_code>.

   $ openssl base64 -e -A -in '<License ID> - for 2018.1 or later.txt'

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

5. Apply the OpenShift Secret to the OpenShift project running the workspace.

   $ oc apply -f secret.yaml

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

7. Restart the workspace.

1. Navigate to the Devfile tab, where the devfile YAML is displayed.

2. In the components devfile section, add the following lines: id and type.

   Example: Adding the Java 8 language plugin

    - 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

3. Click Save to save the changes.
4. Restart the workspace.
5. Verify that the workspace includes the new plug-in.