End-user Guide

Procedure

1. Navigate to the Red Hat CodeReady Workspaces URL to display the Red Hat CodeReady Workspaces login page.
2. Choose the OpenShift OAuth option.
3. The Authorize Access page is displayed.
4. Click on the Allow selected permissions button.
5. Update the account information: specify the Username, Email, First name and Last name fields and click the Submit button.

Procedure

1. Navigate to the Red Hat CodeReady Workspaces URL to display the Red Hat CodeReady Workspaces login page.
2. Choose the Register as a new user option.
3. Update the account information: specify the Username, Email, First name and Last name field and click the Submit button.

Procedure

1. To retrieve the CodeReady Workspaces cluster URL from the checluster CR (Custom Resource), run:

   $ oc get checluster --output jsonpath='{.items[0].status.cheURL}'

2. Alternatively, to retrieve the CodeReady Workspaces cluster URL from the OpenShift logs, run:

   $ oc logs --tail=10 `(oc get pods -o name | grep operator)` | \
     grep "available at" | \
     awk -F'available at: ' '{print $2}' | sed 's/"//'

Procedure

1. Navigate to URL where CodeReady Workspaces is deployed.

2. Save the certificate:

   1. Click the warning or open lock icon on the left of the address bar.
   2. Click Certificates and navigate to the Details tab.

   3. Select the top-level certificate which is the Root certificate authority and export it:

      • On Linux, click the Export button.
      • On Windows, click the Save to file button.
3. Go to Google Chrome Settings, then to the Authorities tab
4. In the left panel, select Advanced and continue to Privacy and security.
5. At the center of the screen, click Manage certificates and navigate to Authorities tab.
6. Click the Import button and open the saved certificate file.
7. Select Trust this certificate for identifying websites and click the OK button.
8. After adding the CodeReady Workspaces certificate to the browser, the address bar displays the closed lock icon next to the URL, indicating a secure connection.

Procedure

1. Navigate to URL where CodeReady Workspaces is deployed.

2. Save the certificate:

   1. Click the lock icon on the left of the address bar.
   2. Click Certificates.
   3. Select the certificate to use and drag and drop its displayed large icon to the desktop.
3. Open the Keychain Access application.
4. Select the System keychain and drag and drop the saved certificate file to it.
5. Double-click the imported CA, then go to Trust and select When using this certificate: Always Trust.
6. Restart the browser for the added certificated to take effect.

Procedure

1. Navigate to URL where CodeReady Workspaces is deployed.

2. Save the certificate:

   1. Click the lock icon on the left of the address bar.
   2. Click the > button next to the Connection not secure warning.
   3. Click the More information button.
   4. Click the View Certificate button on the Security tab.
   5. Select the second certificate tab. The certificate Common Name should start with ingress-operator
   6. Click the PEM (cert) link and save the certificate.
3. Navigate to about:preferences, search for certificates, and click View Certificates.
4. Go to the Authorities tab, click the Import button, and open the saved certificate file.
5. Check Trust this CA to identify websites and click OK.
6. Restart Firefox for the added certificated to take effect.
7. After adding the CodeReady Workspaces certificate to the browser, the address bar displays the closed lock icon next to the URL, indicating a secure connection.

Procedure

1. Open the Topology view to list all projects.
2. In the Select an Application search field, type workspace to list all workspaces.

3. Click the workspace to edit.

   The deployments are displayed as graphical circles surrounded by circular buttons. One of these buttons is Edit Source Code.

   
4. To edit the code of an application using CodeReady Workspaces, click the Edit Source Code button. This redirects to a workspace with the cloned source code of the application component.

Procedure

1. Open the Red Hat Applications menu by clicking the three-by-three square icon (░) in the upper right corner of the main screen.

   The drop-down menu displays the available applications.

   
2. Click the CodeReady Workspaces link. This creates a new workspace or redirects to an existing one. For source links pointing to publicly accessible GitHub repositories that contain a devfile.yaml file, this file is be used to configure the workspace. Otherwise, a default workspace is created.

1. Click Debug → Add Configuration to add debugging or launch configuration to the project.

   

2. From the pop-up menu, select the appropriate configuration for the application that you want to debug.

   

3. Update the configuration by modifying or adding attributes.

   

4. Breakpoints can be toggled by clicking the editor margin.

   

5. After opening a context menu, use the Edit Breakpoint command to add conditions.

   

   The IDE then displays the Expresion input field.

   

6. To start debugging, click View→Debug.

   

7. In the Debug view, select the configuration and press F5 to debug the application. Or, start the application without debugging by pressing Ctrl+F5.

   

1. Edit the tasks.json or launch.json configuration files.

2. Add new definitions to the configuration file or modify the existing ones.

   Note

   The changes are stored in the configuration file.

3. To customize the task configuration provided by plug-ins, select the Terminal → Configure Tasks menu option, and choose the task to configure. The configuration is then copied to the tasks.json file and is available for editing.

1. Open File > Settings > Open Preferences:

   

2. In the opened window, navigate to the Git section, and find:

    user.name
    user.email

   Configure the identity.

1. Navigate to the My Workspace view, and open Plugins > theia-ide…​ > New terminal:

   

2. Execute the following commands:

   $ git config --global user.name "John Doe"
   $ git config --global user.email johndoe@example.com

1. Use the clone command provided by the Visual Studio Code Git extension.

1. Navigate to destination folder using the cd command.

2. Use git clone to clone a repository:

   $ git clone <link>

   Red Hat CodeReady Workspaces supports Git self-signed TLS certificates. See https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.4/html-single/installation_guide/index#deploying-codeready-workspaces-with-support-for-git-repositories-with-self-signed-certificates_crw to learn more.

Procedure

1. Execute the workspace by opening the following URL: https://codeready-<openshift_deployment_name>.<domain_name>/f?url=https://<yourhosturl>/devfile.yaml

Procedure

1. Open the workspace by navigating to the following URL: https://codeready-<openshift_deployment_name>.<domain_name>/f?url=https://<hostURL>/devfile.yaml&override.<parameter.path>=<value>

Procedure

1. Run a workspace from a devfile using the workspace:start parameter with the crwctl tool as follows:

1. In the Workspaces window, click the Add Workspace button. The Custom Workspace page should be opened.

2. Scroll down to the Devfile section. In the Devfile editor, add necessary changes.

   
   Example: add a project

   To add a project into the workspace, add or edit the following section:

   projects:
     - name: che
       source:
         type: git
         location: 'https://github.com/eclipse/che.git'

   See the Section 3.2.4, “Devfile reference”.

1. Navigate to Workspaces page and click the workspace you want to update.

   Here you have two ways to add a project to your workspace:

2. From the Projects tab.

   1. Open the Projects tab, and then click the Add Project button.

   2. Choose if you want to import the project by Git URL or from your GitHub account.

      

3. From the Devfile tab.

   1. Open the Devfile tab.

   2. In the Devfile editor, add projects section with desired project.

      
      Example: add a project

      To add a project into the workspace, add or edit the following section:

      projects:
        - name: che
          source:
            type: git
            location: 'https://github.com/eclipse/che.git'

      See the Section 3.2.4, “Devfile reference”.

4. Once the project is added, click Save button to save this workspace configuration, or click Apply button to apply changes to the running workspace.

   

Procedure

1. Create the simplest devfile:

   apiVersion: 1.0.0
   metadata:
    name: minimal-workspace 1

   1

   Only the name minimal-workspace is specified. After the CodeReady Workspaces server processes this devfile, the devfile is converted to a minimal CodeReady Workspaces workspace that only has the default editor (Che-Theia) and the default editor plug-ins, including, for example, the terminal.

2. To add OpenShift applications to a workspace, modify the devfile and add the OpenShift component type.

   For example, to embed the NodeJS-Mongo application in the minimal-workspace:

   apiVersion: 1.0.0
   metadata:
    name: minimal-workspace
   components:
    - type: kubernetes
      reference: https://raw.githubusercontent.com/.../mongo-db.yaml
    - alias: nodejs-app
      type: kubernetes
      reference: https://raw.githubusercontent.com/.../nodejs-app.yaml
      entrypoints:
        - command: ['sleep']  1
          args: ['infinity']

   1

   The sleep infinity command is added as the entrypoint of the Node.js application. The command prevents the application from starting at the workspace start phase. This configuration allows the user to start the application when needed for testing or debugging purposes.

3. Add the commands in the devfile to make it easier for a developer to test the application:

   apiVersion: 1.0.0
   metadata:
    name: minimal-workspace
   components:
    - type: kubernetes
      reference: https://raw.githubusercontent.com/.../mongo-db.yaml
    - alias: nodejs-app
      type: kubernetes
      reference: https://raw.githubusercontent.com/.../nodejs-app.yaml
      entrypoints:
        - command: ['sleep']
          args: ['infinity']
   commands:
    - name: run  1
      actions:
        - type: exec
          component: nodejs-app
          command: cd ${CHE_PROJECTS_ROOT}/nodejs-mongo-app/EmployeeDB/ && npm install && sed -i -- ''s/localhost/mongo/g'' app.js && node app.js

   1

   The run command added to the devfile is available as a task in Che-Theia from the command palette. When executed, the command starts the Node.js application.

4. Use the devfile to create and start a workspace:

   $ crwctl worspace:start --devfile <devfile-path>

Procedure

1. After the creation of a workspace, use the Workspace menu and then the Configure workspace icon to manage the workspace.

   

2. To modify the workspace details, use the Devfile tab. The workspace details are displayed in this tab in the devfile format.

   
3. To add a OpenShift component, use the Devfile editor on the dashboard.
4. For the changes to take effect, save the devfile and restart the CodeReady Workspaces workspace.

Procedure

1. Use the crwctl devfile:generate command to generate a devfile:

   $ crwctl devfile:generate

   • The user can also use the crwctl devfile:generate command to generate a devfile from, for example, the NodeJS-MongoDB application.

     The following example generates a devfile that includes the NodeJS component:

     $ crwctl devfile:generate --selector="app=nodejs"
     apiVersion: 1.0.0
     metadata:
       name: crwctl-generated
     components:
       - type: kubernetes
         alias: app=nodejs
         referenceContent: |
           kind: List
           apiVersion: v1
           metadata:
             name: app=nodejs
           items:
             - apiVersion: apps/v1
               kind: Deployment
               metadata:
                 labels:
                   app: nodejs
                 name: web
     (...)

     The Node.js application YAML definition is available in the devfile, inline, using the referenceContent attribute.

   • To include support for a language, use the --language parameter:

     $ crwctl devfile:generate --selector="app=nodejs" --language="typescript"
     apiVersion: 1.0.0
     metadata:
       name: crwctl-generated
     components:
       - type: kubernetes
         alias: app=nodejs
         referenceContent: |
           kind: List
           apiVersion: v1
     (...)
       - type: chePlugin
         alias: typescript-ls
         id: che-incubator/typescript/latest

2. Use the generated devfile to start a CodeReady Workspaces workspace with crwctl.

Procedure

1. Use the exec command to open a remote shell.

2. To find the name of the OpenShift project and the Pod that runs the CodeReady Workspaces workspace:

   $ oc  get pod -l che.workspace_id --all-namespaces
   NAMESPACE   NAME                                               READY   STATUS    RESTARTS   AGE
   che         workspace7b2wemdf3hx7s3ln.maven-74885cf4d5-kf2q4   4/4     Running   0          6m4s

1. To find the name of the container:

   $ NAMESPACE=che
   $ POD=workspace7b2wemdf3hx7s3ln.maven-74885cf4d5-kf2q4
   $ oc  get pod ${POD} -o custom-columns=CONTAINERS:.spec.containers[*].name
   CONTAINERS
   maven,che-machine-execpau,theia-ide6dj,vscode-javaw92

2. When you have the project, pod name, and the name of the container, use the `oc ` command to open a remote shell:

   $ NAMESPACE=che
   $ POD=workspace7b2wemdf3hx7s3ln.maven-74885cf4d5-kf2q4
   $ CONTAINER=maven
   $ oc exec -ti -n ${NAMESPACE} ${POD} -c ${CONTAINER} bash
   user@workspace7b2wemdf3hx7s3ln $

3. From the container, execute the build and run commands (as if from the CodeReady Workspaces workspace terminal):

   user@workspace7b2wemdf3hx7s3ln $ mvn clean install
   [INFO] Scanning for projects...
   (...)

Procedure

1. Navigate to the CodeReady Workspaces Dashboard. See Section 1.1, “Navigating CodeReady Workspaces using the Dashboard”.
2. In the left navigation panel, go to Get Started.
3. Click the Get Started tab.

4. In the gallery, there is list of samples that may be used to build and run projects.

   
   Changing resource limits

   Changing the memory requirements is only possible from the devfile. See Section 3.6.3, “Changing the configuration of an existing workspace”.

5. Start the workspace: click the chosen stack card.

   

Procedure

1. Navigate to the CodeReady Workspaces Dashboard. See Section 1.1, “Navigating CodeReady Workspaces using the Dashboard”.
2. In the left navigation panel, go to Get Started.
3. Click the Custom Workspace tab.

4. Define a Name for the workspace.

   New workspace name

   Workspace name can be auto-generated based on the underlying devfile of the stack. Generated names always consist of the devfile metadata.generateName property as the prefix and four random characters.

5. In the Devfile section, select the devfile template that will be used to build and run projects.

   
   Changing resource limits

   Changing the memory requirements is only possible from the devfile. See Section 3.6.3, “Changing the configuration of an existing workspace”.

6. Start the workspace: click the Create & Open button at the bottom of the form:

   

Procedure

1. Navigate to the CodeReady Workspaces Dashboard. See Section 1.1, “Navigating CodeReady Workspaces using the Dashboard”.
2. In the left navigation panel, go to Workspaces.
3. Click the name of a workspace to navigate to the configuration overview page.

4. Click the Overview tab and execute following actions:

   • Change the Workspace name.
   • Select Storage Type.
   • Export the workspace configuration to a file or private cloud.

   • Delete the workspace.

     

5. In the Projects section, choose the projects to integrate in the workspace.

   1. Click the Add Project button and do one of the following:

      1. Enter the project Git repository URL to integrate in the workspace:

         

      2. Connect your GitHub account and select projects to integrate:

         
   2. Click the Add button.

6. In the Plugins section, choose the plug-ins to integrate in the workspace.

   Example

   Start with a generic Java-based stack, then add support for Node.js or Python.

7. In the Editors section, choose the editors to integrate in the workspace. The CodeReady Workspaces 2.4 editor is based on Che-Theia.

8. From the Devfile tab, edit YAML configuration of the workspace. See Section 3.2, “Making a workspace portable using a devfile”.

   Example: add commands
   
   Example: add a project

   To add a project into the workspace, add or edit the following section:

   projects:
     - name: che
       source:
         type: git
         location: 'https://github.com/eclipse/che.git'

1. Import the project. There are at least two ways to import a project using the Dashboard.

   • From the Dashboard, select Workspaces, then select your workspace by clicking on its name. This will link you to the workspace’s Overview tab.
   • Or, use the gear icon. This will link to the Devfile tab where you can enter your own YAML configuration.
2. Click the Projects tab.
3. Click Add Project. You can then import project by a repository Git URL or from GitHub.

1. Start a workspace, then use the Git: Clone command from the command palette or the Welcome screen to import a project to a running workspace.

   

2. Open the command palette using F1 or CTRL-SHIFT-P, or from the link in the Welcome screen.

   

3. Enter the path to the project you want to clone.

   

Procedure

1. Create a new OpenShift secret in the OpenShift project where a CodeReady Workspaces workspace will be created.

   • The labels of the secret that is about to be created must match the set of labels configured in che.workspace.provision.secret.labels property of CodeReady Workspaces. The default labels are:
   • app.kubernetes.io/part-of: che.eclipse.org

   • app.kubernetes.io/component: workspace-secret:

     Note

     Note that the following example describes variations in the usage of the target-container annotation in versions 2.1 and 2.2 of Red Hat CodeReady Workspaces.

     Example:

     apiVersion: v1
     kind: Secret
     metadata:
       name: mvn-settings-secret
       labels:
         app.kubernetes.io/part-of: che.eclipse.org
         app.kubernetes.io/component: workspace-secret
     ...

     Annotations must indicate the given secret is mounted as a file, provide the mount path, and, optionally, specify the name of the container in which the secret is mounted. If there is no target-container annotation, the secret will be mounted into all user containers of the CodeReady Workspaces workspace, but this is applicable only for the CodeReady Workspaces version 2.1.

     apiVersion: v1
     kind: Secret
     metadata:
       name: mvn-settings-secret
       annotations:
         che.eclipse.org/target-container: maven
         che.eclipse.org/mount-path: {prod-home}/.m2/
         che.eclipse.org/mount-as: file
       labels:
     ...

     Since the CodeReady Workspaces version 2.2, the target-container annotation is deprecated and automount-workspace-secret annotation with Boolean values is introduced. Its purpose is to define the default secret mounting behavior, with the ability to be overridden in a devfile. The true value enables the automatic mounting into all workspace containers. In contrast, the false value disables the mounting process until it is explicitly requested in a devfile component using the automountWorkspaceSecrets:true property.

     apiVersion: v1
     kind: Secret
     metadata:
       name: mvn-settings-secret
       annotations:
         che.eclipse.org/automount-workspace-secret: true
         che.eclipse.org/mount-path: {prod-home}/.m2/
         che.eclipse.org/mount-as: file
       labels:
     ...

     Data of the OpenShift secret may contain several items, whose names must match the desired file name mounted into the container.

     apiVersion: v1
     kind: Secret
     metadata:
       name: mvn-settings-secret
       labels:
         app.kubernetes.io/part-of: che.eclipse.org
         app.kubernetes.io/component: workspace-secret
       annotations:
         che.eclipse.org/automount-workspace-secret: true
         che.eclipse.org/mount-path: {prod-home}/.m2/
         che.eclipse.org/mount-as: file
     data:
       settings.xml: <base64 encoded data content here>

     This results in a file named settings.xml being mounted at the /home/jboss/.m2/ path of all workspace containers.

     The secret-s mount path can be overridden for specific components of the workspace using devfile. To change mount path, an additional volume should be declared in a component of the devfile, with name matching overridden secret name, and desired mount path.

     apiVersion: 1.0.0
     metadata:
       ...
     components:
      - type: dockerimage
        alias: maven
        image: maven:3.11
        volumes:
          - name: <secret-name>
            containerPath: /my/new/path
        ...

     Note that for this kind of overrides, components must declare an alias to be able to distinguish containers which belong to them and apply override path exclusively for those containers.

Procedure

1. Create a new OpenShift secret in the k8s project where a CodeReady Workspaces workspace will be created.

   • The labels of the secret that is about to be created must match the set of labels configured in che.workspace.provision.secret.labels property of CodeReady Workspaces. By default, it is a set of two labels:
   • app.kubernetes.io/part-of: che.eclipse.org

   • app.kubernetes.io/component: workspace-secret:

     Note

     Note that the following example describes variations in the usage of the target-container annotation in versions 2.1 and 2.2 of Red Hat CodeReady Workspaces.

     Example:

     apiVersion: v1
     kind: Secret
     metadata:
       name: mvn-settings-secret
       labels:
         app.kubernetes.io/part-of: che.eclipse.org
         app.kubernetes.io/component: workspace-secret
     ...

     Annotations must indicate that the given secret is mounted as an environment variable, provides variable names, and optionally, specifies the container name where this mount will be applied. If there is no target-container annotation defined, the secret will be mounted into all user containers of the CodeReady Workspaces workspace, but this is applicable only for the CodeReady Workspaces version 2.1.

     apiVersion: v1
     kind: Secret
     metadata:
       name: mvn-settings-secret
       annotations:
         che.eclipse.org/target-container: maven
         che.eclipse.org/env-name: FOO_ENV
         che.eclipse.org/mount-as: env
       labels:
        ...
     data:
       mykey: myvalue

     This results in the environment variable named FOO_ENV and the value myvalue being provisioned into the container named maven.

     Since the CodeReady Workspaces version 2.2, the target-container annotation is deprecated and automount-workspace-secret annotation with Boolean values is introduced. Its purpose is to define the default secret mounting behavior, with the ability to be overridden in a devfile. The true value enables the automatic mounting into all workspace containers. In contrast, the false value disables the mounting process until it is explicitly requested in a devfile component using the automountWorkspaceSecrets:true property.

     apiVersion: v1
     kind: Secret
     metadata:
       name: mvn-settings-secret
       annotations:
         che.eclipse.org/automount-workspace-secret: true
         che.eclipse.org/env-name: FOO_ENV
         che.eclipse.org/mount-as: env
       labels:
        ...
     data:
       mykey: myvalue

     This results in the environment variable named FOO_ENV and the value myvalue being provisioned into all workspace containers.

     If the secret provides more than one data item, the environment variable name must be provided for each of the data keys as follows:

     apiVersion: v1
     kind: Secret
     metadata:
       name: mvn-settings-secret
       annotations:
         che.eclipse.org/automount-workspace-secret: true
         che.eclipse.org/mount-as: env
         che.eclipse.org/mykey_env-name: FOO_ENV
         che.eclipse.org/otherkey_env-name: OTHER_ENV
       labels:
        ...
     data:
       mykey: myvalue
       otherkey: othervalue

     This results in two environment variables with names FOO_ENV, OTHER_ENV, and values myvalue and othervalue, being provisioned into all workpsace containers.

     Note

     The maximum length of annotation names in a OpenShift secret is 63 characters, where 9 characters are reserved for a prefix that ends with /. This acts as a restriction for the maximum length of the key that can be used for the secret.

Procedure

1. Prepare git credential file in format https://git-scm.com/docs/git-credential-store#_storage_format.
2. Encode content of the file to the base64 format.

3. Create a new OpenShift secret in the OpenShift project where a CodeReady Workspaces workspace will be created.

   • The labels of the secret that is about to be created must match the set of labels configured in che.workspace.provision.secret.labels property of CodeReady Workspaces. The default labels are:
   • app.kubernetes.io/part-of: che.eclipse.org
   • app.kubernetes.io/component: workspace-secret:

1. CodeReady Workspaces master checks for plug-ins to start from the workspace definition.
2. Plug-in metadata is retrieved, and the type of each plug-in is recognized.
3. A broker is selected according to the plug-in type.
4. The broker processes the installation and deployment of the plug-in (the installation process is different for each broker).

1. The Che-Theia plug-in broker extracts the plug-in (from the .theia file) to get the sidecar containers that the plug-in needs.
2. The broker sends the appropriate container information to CodeReady Workspaces master.
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 workspace master then starts all the containers of the workspace.
5. Che-Theia is started in its own container and checks the correct folder to load the plug-ins.

1. When a user is opening a browser tab or window with Che-Theia, Che-Theia starts a new plug-in session (Web Worker for frontend or Node.js for backend). Every Che-Theia plug-in is notified that a new session has been started (the start() function of the plug-in triggered).
2. A Che-Theia plug-in session is running and interacting with the Che-Theia backend and frontend.
3. When the user is closing the browser tab or there is a timeout, every plug-in is notified (the stop() function of the plug-in triggered).

Procedure

1. Configure your settings.xml file to use artifact repositories at example.server.org:

   <settings>
     <profiles>
       <profile>
         <id>my-nexus</id>
         <pluginRepositories>
           <pluginRepository>
              <id>my-nexus-snapshots</id>
              <releases>
                <enabled>false</enabled>
              </releases>
              <snapshots>
                <enabled>true</enabled>
              </snapshots>
              <url>http://example.server.org/repository/maven-snapshots/</url>
           </pluginRepository>
           <pluginRepository>
              <id>my-nexus-releases</id>
              <releases>
                <enabled>true</enabled>
              </releases>
              <snapshots>
                <enabled>false</enabled>
              </snapshots>
              <url>http://example.server.org/repository/maven-releases/</url>
           </pluginRepository>
         </pluginRepositories>
         <repositories>
           <repository>
              <id>my-nexus-snapshots</id>
              <releases>
                <enabled>false</enabled>
              </releases>
              <snapshots>
                <enabled>true</enabled>
              </snapshots>
              <url>http://example.server.org/repository/maven-snapshots/</url>
           </repository>
           <repository>
              <id>my-nexus-releases</id>
              <releases>
                <enabled>true</enabled>
              </releases>
              <snapshots>
                <enabled>false</enabled>
              </snapshots>
              <url>http://example.server.org/repository/maven-releases/</url>
           </repository>
         </repositories>
       </profile>
     </profiles>
     <activeProfiles>
       <activeProfile>my-nexus</activeProfile>
     </activeProfiles>
   </settings>

Procedure

1. Convert settings.xml to base64:

   $ cat settings.xml | base64

2. Copy the output to a new file, secret.yaml, which also defines needed annotations and labels:

   apiVersion: v1
   kind: Secret
   metadata:
     name: maven-settings-secret
     labels:
       app.kubernetes.io/part-of: che.eclipse.org
       app.kubernetes.io/component: workspace-secret
     annotations:
       che.eclipse.org/automount-workspace-secret: true
       che.eclipse.org/mount-path: /home/jboss/.m2
       che.eclipse.org/mount-as: file
   type: Opaque
   data:
     settings.xml: PHNldHRpbmdzIHhtbG5zPSJodHRwOi8vbWF2ZW4uYXBhY2hlLm9yZy9TRVRUSU5HUy8xLjAuMCIKICAgICAgICAgIHhtbG5zOnhzaT0iaHR0cDovL3d3dy53My5vcmcvMjAwMS9YTUxTY2hlbWEtaW5zdGFuY2UiCiAgICAgICAgICB4c2k6c2NoZW1hTG9jYXRpb249Imh0dHA6Ly9tYXZlbi5hcGFjaGUub3JnL1NFVFRJTkdTLzEuMC4wCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIGh0dHBzOi8vbWF2ZW4uYXBhY2hlLm9yZy94c2Qvc2V0dGluZ3MtMS4wLjAueHNkIj4KICA8c2VydmVycz4KICAgIDxzZXJ2ZXI+CiAgICAgIDxpZD5yZXBvc2l0b3J5LWlkPC9pZD4KICAgICAgPHVzZXJuYW1lPnVzZXJuYW1lPC91c2VybmFtZT4KICAgICAgPHBhc3N3b3JkPnBhc3N3b3JkMTIzPC9wYXNzd29yZD4KICAgIDwvc2VydmVyPgogIDwvc2VydmVycz4KPC9zZXR0aW5ncz4K

3. Create this secret in the cluster:

   $ oc  apply -f secret.yaml

4. Start a new workspace. You will see /home/jboss/.m2/settings.xml with your original content in the maven container.

Procedure

1. Obtain a server certificate file from the repository server. It is often a file named tls.crt.

   1. Create a Java truststore file:

      $ keytool -import -file tls.crt -alias nexus -keystore truststore.jks -storepass changeit
      
      Trust this certificate? [no]:  yes
      Certificate was added to keystore
      Owner: CN=example.com
      Issuer: CN=example.com
      Serial number: 80ca0f6980c6019a
      Valid from: Thu Feb 06 11:00:29 CET 2020 until: Fri Feb 05 11:00:29 CET 2021
      Certificate fingerprints:
           MD5:  88:3C:EC:E1:BE:57:DD:9D:46:36:8E:DD:BF:14:04:22
           SHA1: 08:D8:79:D3:F8:6B:5C:3D:71:AA:23:CA:72:01:47:BD:9D:91:0A:AD
           SHA256: 5C:BB:66:81:44:D2:50:EE:EB:CE:D6:15:7E:63:E1:9A:71:EA:58:3F:14:01:15:4E:68:5D:71:0A:A0:31:33:29
      Signature algorithm name: SHA256withRSA
      Subject Public Key Algorithm: 4096-bit RSA key
      Version: 3
      
      Extensions:
      
      #1: ObjectId: 2.5.29.17 Criticality=false
      SubjectAlternativeName [
        DNSName: *.apps.example.com
      ]
      
      Trust this certificate? [no]:  yes
      Certificate was added to keystore

   2. Upload the truststore file to /projects/maven/truststore.jks to make it available for all containers.

2. Add the truststore file.

   • In the Maven container:

     1. Add the javax.net.ssl system property to the MAVEN_OPTS environment variable:

          - mountSources: true
            alias: maven
            type: dockerimage
            ...
            env:
               -name: MAVEN_OPTS
                value: >-
                  -Duser.home=/projects/maven -Djavax.net.ssl.trustStore=/projects/truststore.jks

     2. Restart the workspace.

   • In the Java plug-in container:

     In the devfile, add the javax.net.ssl system property for the Java language server:

     components:
       - id: redhat/java11/latest
         type: chePlugin
         preferences:
           java.jdt.ls.vmargs: >-
             -noverify -Xmx1G -XX:+UseG1GC -XX:+UseStringDeduplication
             -Duser.home=/projects/maven
             -Djavax.net.ssl.trustStore=/projects/truststore.jks
     [...]

Procedure

1. Obtain a server certificate file from the repository server. It is often a file named tls.crt.

   1. Create a Java truststore file:

      $ keytool -import -file tls.crt -alias nexus -keystore truststore.jks -storepass changeit
      
      Trust this certificate? [no]:  yes
      Certificate was added to keystore
      Owner: CN=example.com
      Issuer: CN=example.com
      Serial number: 80ca0f6980c6019a
      Valid from: Thu Feb 06 11:00:29 CET 2020 until: Fri Feb 05 11:00:29 CET 2021
      Certificate fingerprints:
           MD5:  88:3C:EC:E1:BE:57:DD:9D:46:36:8E:DD:BF:14:04:22
           SHA1: 08:D8:79:D3:F8:6B:5C:3D:71:AA:23:CA:72:01:47:BD:9D:91:0A:AD
           SHA256: 5C:BB:66:81:44:D2:50:EE:EB:CE:D6:15:7E:63:E1:9A:71:EA:58:3F:14:01:15:4E:68:5D:71:0A:A0:31:33:29
      Signature algorithm name: SHA256withRSA
      Subject Public Key Algorithm: 4096-bit RSA key
      Version: 3
      
      Extensions:
      
      #1: ObjectId: 2.5.29.17 Criticality=false
      SubjectAlternativeName [
        DNSName: *.apps.example.com
      ]
      
      Trust this certificate? [no]:  yes
      Certificate was added to keystore

   2. Upload the truststore file to /projects/gradle/truststore.jks to make it available for all containers.

2. Add the truststore file in the Gradle container.

   1. Add the javax.net.ssl system property to the JAVA_OPTS environment variable:

        - mountSources: true
          alias: maven
          type: dockerimage
          ...
          env:
             -name: JAVA_OPTS
              value: >-
                -Duser.home=/projects/gradle -Djavax.net.ssl.trustStore=/projects/truststore.jks

Procedure

1. Obtain the certificate from the non-standard repository and place the certificate file in the /projects/tls/rootCA.pem file to make it accessible from all your containers.

   Note

   pip accepts certificates in the Privacy-Enhanced Mail (PEM) format only. Convert the certificate to the PEM format using OpenSSL if necessary.

2. Configure the devfile:

    - id: ms-python/python/latest
       memoryLimit: 512Mi
       type: chePlugin
       env:
         - name: 'PIP_INDEX_URL'
           value: 'https://<username>:<password>@pypi.company.com/simple'
         - value: '/projects/tls/rootCA.pem'
           name: 'PIP_CERT'
     - mountSources: true
       memoryLimit: 512Mi
       type: dockerimage
       alias: python
       image: 'quay.io/eclipse/che-python-3.7:nightly'
       env:
         - name: 'PIP_INDEX_URL'
           value: 'https://<username>:<password>@pypi.company.com/simple'
         - value: '/projects/tls/rootCA.pem'
           name: 'PIP_CERT'

Procedure

1. Obtain the certificate used by the Athens server in the Privacy-Enhanced Mail (PEM) format and place it in the /projects/tls/rootCA.crt file to make it accessible from all your containers.
2. Right-click the project explorer and select Upload files to upload the rootCA.crt certificate file to your Red Hat CodeReady Workspaces workspace.

3. Add the appropriate environment variables to your devfile:

   components:
   - mountSources: true
     type: dockerimage
     alias: go-cli
     image: 'quay.io/eclipse/che-golang-1.12:7.7.0'
     ...
     - value: /tmp/.cache
       name: GOCACHE
     - value: 'http://your.athens.host'
       name: GOPROXY
     - value: 'on'
       name: GO111MODULE
     - value: '/projects/tls/rootCA.crt'
       name: SSL_CERT_FILE

Procedure

1. Obtain the certificate file of a non-standard repository and place it in the /projects/tls/rootCA.crt file to make it accessible from all your containers.

2. Specify the location of the certificate file in the SSL_CERT_FILE environment variable in your devfile for the OmniSharp plug-in and for the .NET container.

   Example of the devfile:

   components:
     - id: redhat-developer/che-omnisharp-plugin/latest
       memoryLimit: 1024Mi
       type: chePlugin
       alias: omnisharp
       env:
        - value: /projects/tls/rootCA.crt
          name: SSL_CERT_FILE
    - mountSources: true
      endpoints:
        - name: 5000/tcp
          port: 5000
      memoryLimit: 512Mi
      type: dockerimage
      volumes:
        - name: dotnet
          containerPath: /home/jboss
      alias: dotnet
      image: 'quay.io/eclipse/che-dotnet-2.2:7.7.1'
      env:
        - value: /projects/tls/rootCA.crt
          name: SSL_CERT_FILE

Procedure

1. Check browser support:

   1. Check that the WebSocket protocol is enabled using a realtime web test in one of the supported browsers.

      If the problem is not resolved, follow with the next step.

2. Check proxy servers and firewalls settings:

   1. Ask the system administrator to check if there is a proxy server or firewall that blocks WebSocket Secure (WSS) connections on port 443.

      Possible required actions:

      • Add an exception to the firewall.
      • Have the proxy intercept WebSocket connection.