Administration Guide

1. A user starts a CodeReady Workspaces workspace defined by:

   • An editor (the default is Che-Theia)
   • A list of plug-ins (for example, Java and OpenShift tools)
   • A list of runtime applications
2. wsmaster retrieves the editor and plug-in metadata from the plug-in registry.
3. For every plug-in type, wsmaster starts a specific plug-in broker.

4. The CodeReady Workspaces plug-ins broker transforms the plug-in metadata into a Che Plugin definition. It executes the following steps:

   1. Downloads a plug-in and extracts its content.
   2. Processes the plug-in meta.yaml file and sends it back to wsmaster in the format of a Che Plugin.
5. wsmaster starts the editor and the plug-in sidecars.
6. The editor loads the plug-ins from the plug-in persistent volume.

Procedure

1. Clone the devfile registry repository:

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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:

   Expand

   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.

   Show more

   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

   Copy to Clipboard Toggle word wrap

5. Build the containers for the custom devfile registry:

   $ docker build -t my-devfile-registry .

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   ./build.sh

   Copy to Clipboard Toggle word wrap

1. Check out the plugin registry sources.

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap
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

   Copy to Clipboard Toggle word wrap

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)

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap
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

   Copy to Clipboard Toggle word wrap

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}/

   Copy to Clipboard Toggle word wrap
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)

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap
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>

   Copy to Clipboard Toggle word wrap

   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.

   Copy to Clipboard Toggle word wrap

   1

   Each gist has a unique ID.

4. Change the directory:

   $ cd <gist-directory-name> 

   1

   Copy to Clipboard Toggle word wrap

   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"

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

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

       Copy to Clipboard Toggle word wrap

       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

       Copy to Clipboard Toggle word wrap

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

    Copy to Clipboard Toggle word wrap

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"

    Copy to Clipboard Toggle word wrap

    or:

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

    Copy to Clipboard Toggle word wrap

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. In the terminal, run the following command to get the Pods:

   $ oc get pods

   Copy to Clipboard Toggle word wrap

   Example

   $ oc get pods
   NAME            READY  STATUS   RESTARTS  AGE
   codeready-11-j4w2b    1/1    Running  0         3m

   Copy to Clipboard Toggle word wrap

2. To get the logs for a deployment, run the following command:

   $ oc logs <name-of-pod>

   Copy to Clipboard Toggle word wrap

   Example

   $ oc logs codeready-11-j4w2b

   Copy to Clipboard Toggle word wrap

Procedure

1. In the OpenShift Web Console, click Deployments.

2. In the Find by label search field, type:

   • app=che and press Enter

   • component=postgres and Enter

     The OpenShift Web Console now searches base on those two keys and displays PostgreSQL logs.

3. Click postgres deployment to open it.

4. Click the View log link for the active PostgreSQL deployment.

   The OpenShift Web Console displays the database logs.

Procedure

1. Open the OpenShift Container Platform console.
2. From the left menu of the main OpenShift Container Platform screen, navigate to Operators → OperatorHub.
3. In the Search by keyword search bar, type Jaeger Operator.
4. Click the Jaeger Operator tile.
5. Click the Install button in the Jaeger Operator pop-up window.
6. Select the installation method: A specific project on the cluster where the CodeReady Workspaces is deployed and leave the rest in its default values.
7. Click the Subscribe button.
8. From the left menu of the main OpenShift Container Platform screen, navigate to the Operators → Installed Operators section.
9. Red Hat CodeReady Workspaces is displayed as an Installed Operator, as indicated by the InstallSucceeded status.
10. Click the Jaeger Operator name in the list of installed Operators.
11. Navigate to the Overview tab.
12. In the Conditions sections at the bottom of the page, wait for this message: install strategy completed with no errors.
13. Jaeger Operator and additional Elasticsearch Operator is installed.
14. Navigate to the Operators → Installed Operators section.
15. Click Jaeger Operator in the list of installed Operators.
16. The Jaeger Cluster page is displayed.
17. In the lower left corner of the window, click Create Instance
18. Click Save.
19. OpenShift creates the Jaeger cluster jaeger-all-in-one-inmemory.
20. Follow the steps in Enabling metrics collection to finish the procedure.

Procedure

1. In the CodeReady Workspaces installation project of the OpenShift Container Platform cluster, use the oc client to create a new application for the Jaeger deployment.

   $ oc new-app -f / ${CHE_LOCAL_GIT_REPO}/deploy/openshift/templates/jaeger-all-in-one-template.yml:
   
   --> Deploying template "<project_name>/jaeger-template-all-in-one" for "/home/user/crw-projects/crw/deploy/openshift/templates/jaeger-all-in-one-template.yml" to project <project_name>
   
        Jaeger (all-in-one)
        ---------
        Jaeger Distributed Tracing Server (all-in-one)
   
        * With parameters:
           * Jaeger Service Name=jaeger
           * Image version=latest
           * Jaeger Zipkin Service Name=zipkin
   
   --> Creating resources ...
       deployment.apps "jaeger" created
       service "jaeger-query" created
       service "jaeger-collector" created
       service "jaeger-agent" created
       service "zipkin" created
       route.route.openshift.io "jaeger-query" created
   --> Success
       Access your application using the route: 'jaeger-query-<project_name>.apps.ci-ln-whx0352-d5d6b.origin-ci-int-aws.dev.rhcloud.com'
       Run 'oc status' to view your app.

   Copy to Clipboard Toggle word wrap
2. Using the Workloads → Deployments from the left menu of main OpenShift Container Platform screen, monitor the Jaeger deployment until it finishes successfully.
3. Select Networking → Routes from the left menu of the main OpenShift Container Platform screen, and click the URL link to access the Jaeger dashboard.
4. Follow the steps in Enabling metrics collection to finish the procedure.

1. Set scope to repo,user,write:public_key.

2. Set store tokens and stored tokens readable to ON.

   

   View larger image

   

3. Add a default read-token role.

   

   View larger image

   

Procedure

1. Set the following properties in the CheCluster Custom Resource (CR):

   spec:
     auth:
       externalIdentityProvider: true
       identityProviderURL: <auth-base-url>
       identityProviderRealm: <provider-realm-name>
       identityProviderClientId: <oidc-client-name>

   Copy to Clipboard Toggle word wrap

2. When installing CodeReady Workspaces with OpenShift OAuth support enabled, set the following properties in the CheCluster Custom Resource (CR):

   spec:
     auth:
       openShiftoAuth: true
   # Note: only if the OpenShift identity provider alias is different from 'openshift-v3' or 'openshift-v4'
   server:
     customCheProperties:
       CHE_INFRA_OPENSHIFT_OAUTH__IDENTITY__PROVIDER: <OpenShift identity provider alias>

   Copy to Clipboard Toggle word wrap

1. Go to che realm settings > Email.
2. Specify the host, port, username, and password.