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 Making a workspace portable using a Devfile.

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

   Table 1.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 codeready-workspaces/dependencies/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.

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. 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/crw/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/crw/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: ${CODEREADY_PROJECTS_ROOT}/console-java-simple
     -
       name: maven build and run
       actions:
         -
           type: exec
           component: maven
           command: "mvn clean install && java -jar ./target/*.jar"
           workdir: ${CODEREADY_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.

Procedure

1. In the terminal, run the following command to get the Pods:

   $ oc get pods

   Example

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

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

   $ oc logs <name-of-pod>

   Example

   $ oc logs codeready-11-j4w2b

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

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 CodeReady Workspaces traces collections to finish the procedure.

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 CodeReady Workspaces metrics collections to finish the procedure.

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

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

   

3. Add a default read-token role.

   

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>

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

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>

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>

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

1. Select a workspace in the user dashboard.
2. Navigate to the Share tab and enter the email IDs of the users. Use commas or spaces as separators for multiple emails.

Procedure

1. Use the following SQL script to create user and database for the CodeReady Workspaces server to persist workspaces metadata etc:

   CREATE USER <database-user> WITH PASSWORD '<database-password>' 1 2
   CREATE DATABASE <database>                                      3
   GRANT ALL PRIVILEGES ON DATABASE <database> TO <database-user>
   ALTER USER <database-user> WITH SUPERUSER

   1

   CodeReady Workspaces server database username

   2

   CodeReady Workspaces server database password

   3

   CodeReady Workspaces server database name

2. Use the following SQL script to create database for RH-SSO back end to persist user information:

   CREATE USER <identity-database-user> WITH PASSWORD '<identity-database-password>' 1 2
   CREATE DATABASE <identity-database>                                               3
   GRANT ALL PRIVILEGES ON DATABASE <identity-database> TO <identity-database-user>

   1

   RH-SSO database username

   2

   RH-SSO database password

   3

   RH-SSO database name

Procedure

1. Pre-create a project for CodeReady Workspaces:

   $ oc create project workspaces

2. Create a secret to store CodeReady Workspaces server database credentials:

   $ oc create secret generic <server-database-credentials> \ 1
   --from-literal=user=<database-user> \                            2
   --from-literal=password=<database-password> \                    3
   -n workspaces

   1

   Secret name to store CodeReady Workspaces server database credentials

   2

   CodeReady Workspaces server database username

   3

   CodeReady Workspaces server database password

3. Create a secret to store RH-SSO database credentials:

   $ oc create secret generic <identity-database-credentials> \ 1
   --from-literal=user=<identity-database-user> \                     2
   --from-literal=password=<identity-database-password> \             3
   -n workspaces

   1

   Secret name to store RH-SSO database credentials

   2

   RH-SSO database username

   3

   RH-SSO database password

4. To make the Operator skip deploying a database and pass connection details of an existing database to a CodeReady Workspaces server set the following values in the Custom Resource:

   spec:
     database:
       externalDb: true
       chePostgresHostName: <hostname>                     1
       chePostgresPort: <port>                             2
       chePostgresSecret: <server-database-credentials>    3
       chePostgresDb: <database>                           4
   spec:
     auth:
       identityProviderPostgresSecret: <identity-database-credentials> 5

   1

   External database hostname

   2

   External database port

   3

   Secret name with CodeReady Workspaces server database credentials

   4

   CodeReady Workspaces server database username

   5

   Secret name with RH-SSO database credentials

Procedure

1. Navigate to your OpenShift cluster console, navigate to Operators → OperatorHub.
2. Use the Filter by keyword box to search for OpenShift Image Puller Operator. Click the OpenShift Image Puller Operator.
3. Read the description of the Operator. Click Continue → Install.
4. Select A specific project on the cluster for the Installation Mode. In the drop-down find the project you created to install the image puller. Click Subscribe.
5. Wait for the Image Puller Operator to install. Click the OpenShiftImagePuller → Create instance.
6. In a redirected window with a YAML editor, make modifications to the OpenShiftImagePuller Custom Resource and click Create.
7. Navigate to the Workloads and Pods menu in the project and verify that the image puller is installed.

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.