Chapter 3. Developer workspaces

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.

   

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.

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

Procedure

1. Execute the workspace by opening the following URL: \https://codeready-<openshift_deployment_name>.<domain_name>/#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>

Verification steps

1. Using CodeReady Workspaces Dashboard, move to the Devfile tab of the newly created workspace and check its content.

Procedure

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

1. Get the name of the user’s namespace:

1. Using CodeReady Workspaces Dashboard, move to the Workspaces tab and read the name of the OpenShift namespace field.

1. Log in to the cluster:

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

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

   2. Log in:

      $ oc login -u <username> -p <password> <cluster_URL>

1. Display the deployment labels and annotations for all deployments in the project using the OpenShift namespace name from the first step:

   $ oc get deployment -n <NAMESPACE> -o=custom-columns="NAMESPACE:.metadata.namespace,NAME:.metadata.name,LABELS:.metadata.labels,ANNOTATIONS:.metadata.annotations"

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 by using F1, CTRL-SHIFT-P, or the link displayed on the Welcome screen.

   

3. Enter the path to the project that is about to be cloned.

   

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.
   • Review project.
5. From the Devfile tab, edit YAML configuration of the workspace. See Section 4.2, “Authoring devfiles version 2”.

1. Navigate to the Workspaces page and click the workspace, which is about to be updated.
2. Open the Devfile tab.

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

   

4. Once the project is added, click the Save button to save this workspace configuration.

   For demonstration example, see below:

   Example - Adding a .git project into a workspace using a devfile

   In the following instance, the project crw acts as the example of a user’s project. A user specifies this project using the name attribute of a devfile. The location attribute defines the source repository represented by an URL to a Git repository or ZIP archive.

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

   projects:
     - name: <crw>
       source:
         type: git
         location: 'https://github.com/<github-organization>/<crw>.git'

   For additional information, see the Section 4.1.5, “Devfile reference” section.

Procedure

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

4. Click on the Run button in the top right corner of the page.

   The workspace is started, and a browser does not navigates to the workspace.

Procedure

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

4. Click on the Open button in the top right corner of the page.

   The workspace is started, and a browser navigates to the workspace.

Procedure

1. Navigate to the CodeReady Workspaces Dashboard. See Section 1.1, “Navigating CodeReady Workspaces using the Dashboard”.
2. In the left navigation panel, in the Recent Workspaces section, right-click the name of a non-running workspace and click Run in the contextual menu to start it.

Procedure

1. Create the simplest devfile:

   apiVersion: 1.0.0
   metadata:
    name: minimal-workspace 1

   1

   Specify the name minimal-workspace. 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 Kubernetes component type.

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

   apiVersion: 1.0.0
   metadata:
    name: minimal-workspace
   components:
    - type: openshift
      reference: https://raw.githubusercontent.com/.../mongo-db.yaml
    - alias: nodejs-app
      type: openshift
      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: nodejs-with-db
   projects:
     - name: nodejs-mongo-app
       source:
         type: git
         location: 'https://github.com/ijason/NodeJS-Sample-App.git'
         commitId: 187d468 # refers to the last commitId the project compiles (with express3)
   components:
     - type: openshift
       reference: https://raw.githubusercontent.com/redhat-developer/devfile/master/samples/web-nodejs-with-db-sample/mongo-db.yaml
     - alias: nodejs-app
       type: openshift
       reference: https://raw.githubusercontent.com/redhat-developer/devfile/master/samples/web-nodejs-with-db-sample/nodejs-app.yaml
   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 workspace:start --devfile <devfile-path>

Procedure

1. After the creation of a workspace, use the Workspace menu and then click on the desired workspace.
2. Modify the workspace devfile, use the Devfile tab.
3. Add a OpenShift component.
4. For the changes to take effect, save the devfile and restart the CodeReady Workspaces workspace.

Procedure

1. To generate a devfile, use:

   $ crwctl devfile:generate

   • It is also possible to generate a devfile from, for example, the NodeJS-MongoDB application that includes the NodeJS component, using the crwctl devfile:generate command:

     Example:

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

   $ crwctl workspace:start --devfile=devfile​.yaml

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. In the OpenShift project where a CodeReady Workspaces workspace will be created, generate a new OpenShift secret.

   • The labels of the secret that is about to be generated 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 the 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. To obtain a user ID from a secret using a call to a REST API URL:

   • For Bitbucket:

     https://<bitbucket-hostname>/rest/api/1.0/users/<username>

   • For CodeReady Workspaces

     \https://codeready-<openshift_deployment_name>.<domain_name>/api/user

   • With the token credentials obtained from a secret, another secret is automatically created, allowing authorization to Git operations. This secret is mounted into a workspace container as a Git credentials file, and any additional configurations are not required to work with private Git repositories.
   • When a remote Git repository uses a self-signed certificate, add an additional server configuration. See Deploying CodeReady Workspaces with support for Git repositories with self-signed certificates.

1. To obtain a user ID from a secret, take a look into user profile page on GitLab web UI or make a call to a REST API URL:

   • For GitLab:

     https://<gitlab-hostname>/api/v4/users?username=<username>

   • For CodeReady Workspaces

     \https://codeready-<openshift_deployment_name>.<domain_name>/api/user

   • With the token credentials obtained from a secret, another secret is automatically created, allowing authorization to Git operations. This secret is mounted into a workspace container as a Git credentials file, and any additional configurations are not required to work with private Git repositories.
   • When a remote Git repository uses a self-signed certificate, add an additional server configuration. See: Deploying CodeReady Workspaces with support for Git repositories with self-signed certificates.