User guide

Verification

1. Visit the URL for starting a new workspace.
2. Verify that the selected in-browser IDE loads in the browser tab of the started workspace.

Procedure

1. Generate your access token on your Git provider’s website.

2. Encode your access token to Base64.

   Tip

   If you have the base64 command-line tools installed in the operating system, you can use the command line:

   $ echo -n '<your_access_token_string>' | base64

3. Visit "https://devspaces-<openshift_deployment_name>.<domain_name>"/api/user in the web browser and copy the id value from the response. This is your OpenShift Dev Spaces user ID.

4. Get your Git provider user ID by following the Git provider’s API documentation:

   • GitHub: Get a user. See the id value in the response.
   • GitLab: List users: For normal users, use the username filter: /users?username=:username. See the id value in the response.
   • Bitbucket Server: Get users. See the id value in the response.

5. Prepare a new OpenShift Secret.

   kind: Secret
   apiVersion: v1
   metadata:
     name: personal-access-token-<your_choice_of_name_for_this_token>
     labels:
       app.kubernetes.io/component: scm-personal-access-token
       app.kubernetes.io/part-of: che.eclipse.org
     annotations:
       che.eclipse.org/che-userid: <devspaces_user_id>1
       che.eclipse.org/scm-personal-access-token-name: <git_provider_name>2
       che.eclipse.org/scm-url: <git_provider_endpoint>3
       che.eclipse.org/scm-userid: '<git_provider_user_id>'4
       che.eclipse.org/scm-username: <git_provider_username>
   data:
     token: <Base64_encoded_access_token>
   type: Opaque

   1

   Your OpenShift Dev Spaces user ID.

   2

   The Git provider name: github or gitlab or bitbucket-server.

   3

   The Git provider URL.

   4

   Your Git provider user ID.

6. Visit "https://devspaces-<openshift_deployment_name>.<domain_name>"/api/kubernetes/namespace to get your OpenShift Dev Spaces user namespace as name.

7. Switch to your OpenShift Dev Spaces user namespace in the cluster.

   Tip

   On OpenShift:

   • The oc command-line tool can return the namespace you are currently on in the cluster, which you can use to check your current namespace:

     $ oc project

   • You can switch to your OpenShift Dev Spaces user namespace on a command line if needed:

     $ oc project <your_user_namespace>

8. Apply the Secret.

   Tip

   On OpenShift, you can use the oc command-line tool:

   $ oc apply -f - <<EOF
   <Secret_prepared_in_step_5>
   EOF

Verification

1. Start a new workspace by using the URL of a remote Git repository that the Git provider hosts.
2. Make some changes and push to the remote Git repository from the workspace.

Procedure

1. In the <username>-devspaces namespace, apply the Secret for the TLS certificate:

   kind: Secret
   apiVersion: v1
   metadata:
     name: tls-cer
     annotations:
       controller.devfile.io/mount-path: /home/user/certs
       controller.devfile.io/mount-as: file
     labels:
       controller.devfile.io/mount-to-devworkspace: 'true'
       controller.devfile.io/watch-secret: 'true'
   data:
     tls.cer: >-
       <Base64_encoded_content_of_public_cert> 1

   1

   Base64 encoding with disabled line wrapping.

2. In the <username>-devspaces namespace, apply the ConfigMap to create the settings.xml file:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: settings-xml
     annotations:
       controller.devfile.io/mount-as: subpath
       controller.devfile.io/mount-path: /home/user/.m2
     labels:
       controller.devfile.io/mount-to-devworkspace: 'true'
       controller.devfile.io/watch-configmap: 'true'
   data:
     settings.xml: |
       <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
         <localRepository/>
         <interactiveMode/>
         <offline/>
         <pluginGroups/>
         <servers/>
         <mirrors>
           <mirror>
             <id>redhat-ga-mirror</id>
             <name>Red Hat GA</name>
             <url>https://<maven_artifact_repository_route>/repository/redhat-ga/</url>
             <mirrorOf>redhat-ga</mirrorOf>
           </mirror>
           <mirror>
             <id>maven-central-mirror</id>
             <name>Maven Central</name>
             <url>https://<maven_artifact_repository_route>/repository/maven-central/</url>
             <mirrorOf>maven-central</mirrorOf>
           </mirror>
           <mirror>
             <id>jboss-public-repository-mirror</id>
             <name>JBoss Public Maven Repository</name>
             <url>https://<maven_artifact_repository_route>/repository/jboss-public/</url>
             <mirrorOf>jboss-public-repository</mirrorOf>
           </mirror>
         </mirrors>
         <proxies/>
         <profiles/>
         <activeProfiles/>
       </settings>

3. Optional: When using EAP-based devfiles, apply a second settings-xml ConfigMap in the <username>-devspaces namespace, and with the same content, a different name, and the /home/jboss/.m2 mount path.

4. In the <username>-devspaces namespace, apply the ConfigMap for the TrustStore initialization script:

   Java 8

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: init-truststore
     annotations:
       controller.devfile.io/mount-as: subpath
       controller.devfile.io/mount-path: /home/user/
     labels:
       controller.devfile.io/mount-to-devworkspace: 'true'
       controller.devfile.io/watch-configmap: 'true'
   data:
     init-java8-truststore.sh: |
       #!/usr/bin/env bash
   
       keytool -importcert -noprompt -file /home/user/certs/tls.cer -trustcacerts -keystore ~/.java/current/jre/lib/security/cacerts -storepass changeit

   Java 11

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: init-truststore
     annotations:
       controller.devfile.io/mount-as: subpath
       controller.devfile.io/mount-path: /home/user/
     labels:
       controller.devfile.io/mount-to-devworkspace: 'true'
       controller.devfile.io/watch-configmap: 'true'
   data:
     init-java11-truststore.sh: |
       #!/usr/bin/env bash
   
       keytool -importcert -noprompt -file /home/user/certs/tls.cer -cacerts -storepass changeit

5. Start a Maven workspace.
6. Open a new terminal in the tools container.
7. Run ~/init-truststore.sh.

Procedure

1. Apply the Secret for the TLS certificate:

   kind: Secret
   apiVersion: v1
   metadata:
     name: tls-cer
     annotations:
       controller.devfile.io/mount-path: /home/user/certs
       controller.devfile.io/mount-as: file
     labels:
       controller.devfile.io/mount-to-devworkspace: 'true'
       controller.devfile.io/watch-secret: 'true'
   data:
     tls.cer: >-
       <Base64_encoded_content_of_public_cert> 1

   1

   Base64 encoding with disabled line wrapping.

2. Apply the ConfigMap for the TrustStore initialization script:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: init-truststore
     annotations:
       controller.devfile.io/mount-as: subpath
       controller.devfile.io/mount-path: /home/user/
     labels:
       controller.devfile.io/mount-to-devworkspace: 'true'
       controller.devfile.io/watch-configmap: 'true'
   data:
     init-truststore.sh: |
       #!/usr/bin/env bash
   
       keytool -importcert -noprompt -file /home/user/certs/tls.cer -cacerts -storepass changeit

3. Apply the ConfigMap for the Gradle init script:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: init-gradle
     annotations:
       controller.devfile.io/mount-as: subpath
       controller.devfile.io/mount-path: /home/user/.gradle
     labels:
       controller.devfile.io/mount-to-devworkspace: 'true'
       controller.devfile.io/watch-configmap: 'true'
   data:
     init.gradle: |
       allprojects {
         repositories {
           mavenLocal ()
           maven {
             url "https://<gradle_artifact_repository_route>/repository/maven-public/"
             credentials {
               username "admin"
               password "passwd"
             }
           }
         }
       }

4. Start a Gradle workspace.
5. Open a new terminal in the tools container.
6. Run ~/init-truststore.sh.

Procedure

1. Apply the Secret for the TLS certificate:

   kind: Secret
   apiVersion: v1
   metadata:
     name: tls-cer
     annotations:
       controller.devfile.io/mount-path: /home/user/certs
       controller.devfile.io/mount-as: file
     labels:
       controller.devfile.io/mount-to-devworkspace: 'true'
       controller.devfile.io/watch-secret: 'true'
   data:
     tls.cer: >-
       <Base64_encoded_content_of_public_cert> 1

   1

   Base64 encoding with disabled line wrapping.

2. Apply the ConfigMap to set the following environment variables in the tools container:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: disconnected-env
     annotations:
       controller.devfile.io/mount-as: env
     labels:
       controller.devfile.io/mount-to-devworkspace: 'true'
       controller.devfile.io/watch-configmap: 'true'
   data:
     NODE_EXTRA_CA_CERTS: /home/user/certs/tls.cer
     NPM_CONFIG_REGISTRY: >-
       https://<npm_artifact_repository_route>/repository/npm-all/

Procedure

1. Apply the Secret for the TLS certificate:

   kind: Secret
   apiVersion: v1
   metadata:
     name: tls-cer
     annotations:
       controller.devfile.io/mount-path: /home/user/certs
       controller.devfile.io/mount-as: file
     labels:
       controller.devfile.io/mount-to-devworkspace: 'true'
       controller.devfile.io/watch-secret: 'true'
   data:
     tls.cer: >-
       <Base64_encoded_content_of_public_cert> 1

   1

   Base64 encoding with disabled line wrapping.

2. Apply the ConfigMap to set the following environment variables in the tools container:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: disconnected-env
     annotations:
       controller.devfile.io/mount-as: env
     labels:
       controller.devfile.io/mount-to-devworkspace: 'true'
       controller.devfile.io/watch-configmap: 'true'
   data:
     PIP_INDEX_URL: >-
       https://<python_artifact_repository_route>/repository/pypi-all/
     PIP_CERT: /home/user/certs/tls.cer

Procedure

1. Apply the Secret for the TLS certificate:

   kind: Secret
   apiVersion: v1
   metadata:
     name: tls-cer
     annotations:
       controller.devfile.io/mount-path: /home/user/certs
       controller.devfile.io/mount-as: file
     labels:
       controller.devfile.io/mount-to-devworkspace: 'true'
       controller.devfile.io/watch-secret: 'true'
   data:
     tls.cer: >-
       <Base64_encoded_content_of_public_cert> 1

   1

   Base64 encoding with disabled line wrapping.

2. Apply the ConfigMap to set the following environment variables in the tools container:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: disconnected-env
     annotations:
       controller.devfile.io/mount-as: env
     labels:
       controller.devfile.io/mount-to-devworkspace: 'true'
       controller.devfile.io/watch-configmap: 'true'
   data:
     GOPROXY: >-
       http://<athens_proxy_route>
     SSL_CERT_FILE: /home/user/certs/tls.cer

Procedure

1. Apply the Secret for the TLS certificate:

   kind: Secret
   apiVersion: v1
   metadata:
     name: tls-cer
     annotations:
       controller.devfile.io/mount-path: /home/user/certs
       controller.devfile.io/mount-as: file
     labels:
       controller.devfile.io/mount-to-devworkspace: 'true'
       controller.devfile.io/watch-secret: 'true'
   data:
     tls.cer: >-
       <Base64_encoded_content_of_public_cert> 1

   1

   Base64 encoding with disabled line wrapping.

2. Apply the ConfigMap to set the environment variable for the path of the TLS certificate file in the tools container:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: disconnected-env
     annotations:
       controller.devfile.io/mount-as: env
     labels:
       controller.devfile.io/mount-to-devworkspace: 'true'
       controller.devfile.io/watch-configmap: 'true'
   data:
     SSL_CERT_FILE: /home/user/certs/tls.cer

3. Apply the ConfigMap to create the nuget.config file:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: init-nuget
     annotations:
       controller.devfile.io/mount-as: subpath
       controller.devfile.io/mount-path: /projects
     labels:
       controller.devfile.io/mount-to-devworkspace: 'true'
       controller.devfile.io/watch-configmap: 'true'
   data:
     nuget.config: |
       <?xml version="1.0" encoding="UTF-8"?>
       <configuration>
         <packageSources>
           <add key="nexus2" value="https://<nuget_artifact_repository_route>/repository/nuget-group/"/>
         </packageSources>
         <packageSourceCredentials>
           <nexus2>
               <add key="Username" value="admin" />
               <add key="Password" value="passwd" />
           </nexus2>
         </packageSourceCredentials>
       </configuration>

Procedure

1. To prepare the DevWorkspace custom resource, copy the contents of the target Git repository’s devfile.

   Example 8.2. Copied devfile contents with schemaVersion: 2.2.0

   components:
     - name: tooling-container
       container:
         image: quay.io/devfile/universal-developer-image:ubi8-latest

   Tip

   For more details, see the devfile v2 documentation.

2. Create a DevWorkspace custom resource, pasting the devfile contents from the previous step under the spec.template field.

   Example 8.3. A DevWorkspace custom resource

   kind: DevWorkspace
   apiVersion: workspace.devfile.io/v1alpha2
   metadata:
     name: my-devworkspace1
     namespace: user1-dev2
   spec:
     routingClass: che
     started: true3
     contributions:4
       - name: ide
         uri: "https://devspaces-<openshift_deployment_name>.<domain_name>"/plugin-registry/v3/plugins/che-incubator/che-code/insiders/devfile.yaml
     template:
       projects:5
         - name: my-project-name
           git:
             remotes:
               origin: https://github.com/eclipse-che/che-docs
       components:6
         - name: tooling-container
           container:
             image: quay.io/devfile/universal-developer-image:ubi8-latest

   1

   Name of the DevWorkspace custom resource. This will be the name of the new workspace.

   2

   User namespace, which is the target project for the new workspace.

   3

   Determines whether the workspace must be started when the DevWorkspace custom resource is created.

   4

   URL reference to the Microsoft Visual Studio Code - Open Source IDE devfile from the plugin registry.

   5

   Details about the Git repository to clone into the workspace when it starts.

   6

   List of components such as workspace containers and volume components.

3. Apply the DevWorkspace custom resource to the cluster.

Verification

1. Verify that the workspace is starting by checking the PHASE status of the DevWorkspace.

   $ oc get devworkspaces -n <user_project> --watch

   Example 8.4. Output

   NAMESPACE        NAME                  DEVWORKSPACE ID             PHASE      INFO
   user1-dev        my-devworkspace       workspacedf64e4a492cd4701   Starting   Waiting for workspace deployment

2. When the workspace has successfully started, its PHASE status changes to Running in the output of the oc get devworkspaces command.

   Example 8.5. Output

   NAMESPACE            NAME                  DEVWORKSPACE ID             PHASE      INFO
   user1-dev            my-devworkspace       workspacedf64e4a492cd4701   Running    https://url-to-workspace.com

   You can then open the workspace by using one of these options:

   • Visit the URL provided in the INFO section of the output of the oc get devworkspaces command.
   • Open the workspace from the OpenShift Dev Spaces dashboard.

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 OpenShift Dev Spaces, 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 using the three-by-three matrix icon in the upper right corner of the main screen.

   The drop-down menu displays the available applications.

   
2. Click the OpenShift Dev Spaces link to open the Dev Spaces Dashboard.

Procedure

1. In the OpenShift Dev Spaces dashboard, go to Workspaces.
2. Click on a workspace name to display the workspace overview page. This page displays the OpenShift project name <project_name>.
3. Click on the upper right Applications menu, and click the OpenShift console link.
4. Run the next steps in the OpenShift console, in the Administrator perspective.
5. Click Workloads > Pods to see a list of all the active workspaces.
6. In the Project drop-down menu, select the <project_name> project to narrow the search.
7. Click on the name of the running pod that runs the workspace. The Details tab contains the list of all containers with additional information.
8. Go to the Logs tab.

Procedure

1. Configure the extension: click File > Preferences > Settings, expand the Extensions section, search for your extension, and set the trace.server or similar configuration to verbose, if such configuration exists. Refer to the extension documentation for further configuration.
2. View your language server logs by clicking View → Output, and selecting your language server in the drop-down list for the Output view.

Procedure

1. Using Dashboard, try to start a workspace.
2. When it fails to start, click on the displayed Open in Verbose mode link.
3. Check the Logs tab to find a reason for the workspace failure.

Procedure

1. Open the Workspaces tab.
2. On the left side of a row dedicated to the workspace, access the drop-down menu displayed as three horizontal dots and select the Open in Verbose mode option. Alternatively, this option is also available in the workspace details, under the Actions drop-down menu.
3. Check the Logs tab to find a reason for the workspace failure.