User guide

Verification

1. Start a new workspace with a clone of the Git repository.
2. Verify that the specified IDE loads in the browser tab of the started workspace.

Procedure

1. Get the publisher and extension names of each chosen extension:

   1. Find the extension on the Open VSX registry website and copy the URL of the extension’s listing page.

   2. Extract the <publisher> and <extension> names from the copied URL:

      https://www.open-vsx.org/extension/<publisher>/<extension>

      Copy to Clipboard
2. Create a .vscode/extensions.json file in the remote Git repository.

3. Add the <publisher> and <extension> names to the extensions.json file as follows:

     {
       "recommendations": [
         "<publisher_A>.<extension_B>",
         "<publisher_C>.<extension_D>",
         "<publisher_E>.<extension_F>"
       ]
     }

   Copy to Clipboard

Verification

1. Start a new workspace by using the URL of the remote Git repository that contains the created extensions.json file.
2. In the IDE of the workspace, press Ctrl+Shift+X or go to Extensions to find each of the extensions listed in the file.
3. The extension has the label This extension is enabled globally.

Procedure

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

   Important

   Personal access tokens are sensitive information and should be kept confidential. Treat them like passwords. If you are having trouble with authentication, ensure you are using the correct token and have the appropriate permissions for cloning repositories:

   1. Open a terminal locally on your computer
   2. Use the git command to clone the repository using your personal access token. The format of the git command vary based on the Git Provider. As an example, GitHub personal access token verification can be done using the following command:

   git clone https://<PAT>@github.com/username/repo.git

   Copy to Clipboard

   Replace <PAT> with your personal access token, and username/repo with the appropriate repository path. If the token is valid and has the necessary permissions, the cloning process should be successful. Otherwise, this is an indicator of incorrect personal access token, insufficient permissions, or other issues.

   Important

   For GitHub Enterprise Cloud, verify that the token is authorized for use within the organization.

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. Go to https://<openshift_dev_spaces_fqdn>/api/user/id in the web browser to get your OpenShift Dev Spaces user ID.

4. 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-organization: <git_provider_organization>

   4

   
   data:
     token: <Base64_encoded_access_token>
   type: Opaque

   Copy to Clipboard

   1

   Your OpenShift Dev Spaces user ID.

   2

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

   3

   The Git provider URL.

   4

   This line is only applicable to azure-devops: your Git provider user organization.

5. Visit https://<openshift_dev_spaces_fqdn>/api/kubernetes/namespace to get your OpenShift Dev Spaces user namespace as name.

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

7. Apply the Secret.

   Tip

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

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

   Copy to Clipboard

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. Prepare a new OpenShift ConfigMap.

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: workspace-userdata-gitconfig-configmap
     namespace: <user_namespace> 

   1

   
     labels:
       controller.devfile.io/mount-to-devworkspace: 'true'
       controller.devfile.io/watch-configmap: 'true'
     annotations:
       controller.devfile.io/mount-as: subpath
       controller.devfile.io/mount-path: /etc/
   data:
     gitconfig: "[user] \n  name = <git_user_name> \n  email = <git_user_email>" 

   2

   Copy to Clipboard

   1

   A user namespace. Visit https://<openshift_dev_spaces_fqdn>/api/kubernetes/namespace to get your OpenShift Dev Spaces user namespace as name.

   2

   Your Git user name and email.

2. Apply the ConfigMap.

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

   Copy to Clipboard

Verification

1. Start a new workspace by using the URL of a remote Git repository that the Git provider hosts.
2. Once the workspace is started, open a new terminal in the tools container and run git config --get-regexp user.*. Your Git user name and email should appear in the output.

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

   Copy to Clipboard

   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>

   Copy to Clipboard
3. Optional: When using JBoss 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

   Copy to Clipboard

   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

   Copy to Clipboard

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

   Copy to Clipboard

   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

   Copy to Clipboard

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

   Copy to Clipboard
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

   Copy to Clipboard

   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/

   Copy to Clipboard

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

   Copy to Clipboard

   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

   Copy to Clipboard

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

   Copy to Clipboard

   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

   Copy to Clipboard

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

   Copy to Clipboard

   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

   Copy to Clipboard

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>

   Copy to Clipboard

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

   Copy to Clipboard
   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-devworkspace

   1

   
     namespace: user1-dev

   2

   
   spec:
     routingClass: che
     started: true

   3

   
     contributions:

   4

   
       - name: ide
         uri: https://<openshift_dev_spaces_fqdn>/plugin-registry/v3/plugins/che-incubator/che-code/latest/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

   Copy to Clipboard

   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

   Copy to Clipboard

   Example 8.4. Output

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

   Copy to Clipboard

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

   Copy to Clipboard

   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.