Chapter 3. Customizing the devfile and plug-in registries

Procedure

1. Clone the devfile registry repository:

   $ git clone git@github.com:redhat-developer/codeready-workspaces.git
   $ cd codeready-workspaces/dependencies/che-devfile-registry

2. In the ./che-devfile-registry/devfiles/ directory, create a subdirectory <devfile-name>/ and add the devfile.yaml and meta.yaml files.

   File organization for a devfile

   ./che-devfile-registry/devfiles/
   └── <devfile-name>
       ├── devfile.yaml
       └── meta.yaml

3. Add valid content in the devfile.yaml file. For a detailed description of the devfile format, see https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.4/html-single/end-user_guide/index#making-a-workspace-portable-using-a-devfile_crw.

4. Ensure that the meta.yaml file conforms to the following structure:

   Table 3.1. Parameters for a devfile meta.yaml

   Attribute	Description
   description	Description as it appears on the user dashboard.
   displayName	Name as it appears on the user dashboard.
   globalMemoryLimit	The sum of the expected memory consumed by all the components launched by the devfile. This number will be visible on the user dashboard. It is informative and is not taken into account by the CodeReady Workspaces server.
   icon	Link to an .svg file that is displayed on the user dashboard.
   tags	List of tags. Tags usually include the tools included in the stack.

   Example devfile meta.yaml

   displayName: Rust
   description: Rust Stack with Rust 1.39
   tags: ["Rust"]
   icon: https://www.eclipse.org/che/images/logo-eclipseche.svg
   globalMemoryLimit: 1686Mi

5. Build the containers for the custom devfile registry:

   $ docker build -t my-devfile-registry .

Procedure

1. Clone the plug-in registry repository:

   $ git clone git@github.com:redhat-developer/codeready-workspaces.git
   $ cd codeready-workspaces/dependencies/che-plugin-registry

2. In the ./che-plugin-registry/v3/plugins/ directory, create new directories <publisher>/<plugin-name>/<plugin-version>/ and a meta.yaml file in the last directory.

   File organization for a plugin

   ./che-plugin-registry/v3/plugins/
   ├── <publisher>
   │   └── <plugin-name>
   │       ├── <plugin-version>
   │       │   └── meta.yaml
   │       └── latest.txt

3. Add valid content to the meta.yaml file. See the “Using a Visual Studio Code extension in CodeReady Workspaces” section or the README.md file in the eclipse/che-plugin-registry repository for a detailed description of the meta.yaml file format.

4. Create a file named latest.txt with content the name of the latest <plugin-version> directory.

   Example

   $ tree che-plugin-registry/v3/plugins/redhat/java/
   che-plugin-registry/v3/plugins/redhat/java/
   ├── 0.38.0
   │   └── meta.yaml
   ├── 0.43.0
   │   └── meta.yaml
   ├── 0.45.0
   │   └── meta.yaml
   ├── 0.46.0
   │   └── meta.yaml
   ├── 0.50.0
   │   └── meta.yaml
   └── latest.txt
   $ cat che-plugin-registry/v3/plugins/redhat/java/latest.txt
   0.50.0

5. Build the containers for the custom plug-in registry:

   ./build.sh

1. Check out the plugin registry sources.

   $ git clone https://github.com/redhat-developer/codeready-workspaces; \
     cd codeready-workspaces/dependencies/che-plugin-registry

2. Create a meta.yaml in some local folder. This can be done from scratch or by copying from an existing plug-in’s meta.yaml file.

   $ PLUGIN="v3/plugins/new-org/new-plugin/0.0.1"; \
     mkdir -p ${PLUGIN}; cp v3/plugins/che-incubator/cpptools/0.1/* ${PLUGIN}/
     echo "${PLUGIN##*/}" > ${PLUGIN}/../latest.txt

3. If copying from an existing plug-in, make changes to the meta.yaml file to suit your needs. Make sure the new plug-in has a unique title, displayName and description. Update the firstPublicationDate to today’s date.

4. These fields in meta.yaml must match the path defined in PLUGIN above.

   publisher: new-org
   name: new-plugin
   version: 0.0.1

5. Get the name of the Pod that hosts the plug-in registry container. To do this, filter the component=plugin-registry label:

   $ PLUGIN_REG_POD=$(oc get -o custom-columns=NAME:.metadata.name \
     --no-headers pod -l component=plugin-registry)

6. Regenerate the registry’s index.json file to include the new plug-in.

   $ cd codeready-workspaces/dependencies/che-plugin-registry; \
       "$(pwd)/build/scripts/generate_latest_metas.sh" v3 && \
       "$(pwd)/build/scripts/check_plugins_location.sh" v3 && \
       "$(pwd)/build/scripts/set_plugin_dates.sh" v3 && \
       "$(pwd)/build/scripts/check_plugins_viewer_mandatory_fields.sh" v3 && \
       "$(pwd)/build/scripts/index.sh" v3 > v3/plugins/index.json

7. Copy the new index.json and meta.yaml files from the new local plug-in folder to the container.

   $ cd codeready-workspaces/dependencies/che-plugin-registry; \
     LOCAL_FILES="$(pwd)/${PLUGIN}/meta.yaml $(pwd)/v3/plugins/index.json"; \
     oc exec ${PLUGIN_REG_POD} -i -t -- mkdir -p /var/www/html/$/{PLUGIN}; \
     for f in $LOCAL_FILES; do e=${f/$(pwd)\//}; echo "Upload ${f} -> /var/www/html/${e}"; \
       oc cp "${f}" ${PLUGIN_REG_POD}:/var/www/html/${e}; done

8. The new plug-in can now be used from the existing CodeReady Workspaces instance of the plug-in registry. To discover it, go to the CodeReady Workspaces dashboard, then click the Workspaces link. From there, click the gear icon to configure one of your workspaces. Select the Plugins tab to see the updated list of available plug-ins.

1. Check out the devfile registry sources.

   $ git clone https://github.com/redhat-developer/codeready-workspaces; \
     cd codeready-workspaces/dependencies/che-devfile-registry

2. Create a devfile.yaml and meta.yaml in some local folder. This can be done from scratch or by copying from an existing devfile.

   $ STACK="new-stack"; \
     mkdir -p devfiles/${STACK}; cp devfiles/03_web-nodejs-simple/* devfiles/${STACK}/

3. If copying from an existing devfile, make changes to the devfile to suit your needs. Make sure the new devfile has a unique displayName and description.

4. Get the name of the Pod that hosts the devfile registry container. To do this, filter the component=devfile-registry label:

   $ DEVFILE_REG_POD=$(oc get -o custom-columns=NAME:.metadata.name \
     --no-headers pod -l component=devfile-registry)

5. Regenerate the registry’s index.json file to include the new devfile.

   $ cd codeready-workspaces/dependencies/che-devfile-registry; \
     "$(pwd)/build/scripts/check_mandatory_fields.sh" devfiles; \
     "$(pwd)/build/scripts/index.sh" > index.json

6. Copy the new index.json, devfile.yaml and meta.yaml files from the new local devfile folder to the container.

   $ cd che-devfile-registry; \
     oc exec ${DEVFILE_REG_POD} -i -t -- mkdir -p /var/www/html/devfiles/${STACK}; \
     oc cp $(pwd)/devfiles/${STACK}/meta.yaml ${DEVFILE_REG_POD}:/var/www/html/devfiles/${STACK}/meta.yaml; \
     oc cp $(pwd)/devfiles/${STACK}/devfile.yaml ${DEVFILE_REG_POD}:/var/www/html/devfiles/${STACK}/devfile.yaml; \
     oc cp $(pwd)/index.json ${DEVFILE_REG_POD}:/var/www/html/devfiles/index.json

7. The new devfile can now be used from the existing CodeReady Workspaces instance of the devfile registry. To discover it, go to the CodeReady Workspaces dashboard, then click the Workspaces link. From there, click Add Workspace to see the updated list of available devfiles.

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 (instead of an ID 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>/f?url=$(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.