User guide

Procedure

1. Use the pod-overrides attribute to add the required annotations defined in https://access.redhat.com/documentation/en-us/red_hat_openshift_dev_spaces/3.15/html-single/administration_guide/index#administration-guide:configuring-fuse to the workspace. The pod-overrides attribute allows merging certain fields in the workspace pod’s spec.

   For OpenShift versions older than 4.15:

   $ oc patch devworkspace <DevWorkspace_name> \
     --patch '{"spec":{"template":{"attributes":{"pod-overrides":{"metadata":{"annotations":{"io.kubernetes.cri-o.Devices":"/dev/fuse","io.openshift.podman-fuse":""}}}}}}}' \
     --type=merge

   For OpenShift version 4.15 and later:

   $ oc patch devworkspace <DevWorkspace_name> \
     --patch '{"spec":{"template":{"attributes":{"pod-overrides":{"metadata":{"annotations":{"io.kubernetes.cri-o.Devices":"/dev/fuse"}}}}}}}' \
     --type=merge

Verification steps

1. Start the workspace and verify that /dev/fuse is available in the workspace container.

   $ stat /dev/fuse

Procedure

1. Apply a ConfigMap that mounts a /home/user/.config/containers/storage.conf file in your project.

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: fuse-overlay
     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: /home/user/.config/containers
   data:
     storage.conf: |
       [storage]
       driver = "overlay"
   
       [storage.options.overlay]
       mount_program="/usr/bin/fuse-overlayfs"

Verification steps

1. Start the workspace containing the required annotations and verify that the storage driver is overlay.

   $ podman info | grep overlay

   Example output:

   graphDriverName: overlay
     overlay.mount_program:
       Executable: /usr/bin/fuse-overlayfs
       Package: fuse-overlayfs-1.12-1.module+el8.9.0+20326+387084d0.x86_64
         fuse-overlayfs: version 1.12
     Backing Filesystem: overlayfs

Procedure

1. In the GitHub repository, create a .github/workflows directory if it does not exist already.

2. Create an example.yml file in the .github/workflows directory with the following content:

   Example 2.1. example.yml

   name: Try in Web IDE example
   
   on:
     pull_request_target:
       types: [opened]
   
   jobs:
     add-link:
       runs-on: ubuntu-20.04
       steps:
         - name: Web IDE Pull Request Check
           id: try-in-web-ide
           uses: redhat-actions/try-in-web-ide@v1
           with:
             # GitHub action inputs
   
             # required
             github_token: ${{ secrets.GITHUB_TOKEN }}
   
             # optional - defaults to true
             add_comment: true
   
             # optional - defaults to true
             add_status: true

   This code snippet creates a workflow named Try in Web IDE example, with a job that runs the v1 version of the redhat-actions/try-in-web-ide community action. The workflow is triggered on the pull_request_target event, on the opened activity type.

3. Optionally configure the activity types from the on.pull_request_target.types field to customize when workflow trigger. Activity types such as reopened and synchronize can be useful.

   Example 2.2. Triggering the workflow on both opened and synchronize activity types

   on:
     pull_request_target:
       types: [opened, synchronize]

4. Optionally configure the add_comment and add_status GitHub action inputs within example.yml. These inputs are sent to the Try in Web IDE GitHub action to customize whether comments and status checks are to be made.

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>

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

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.

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

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

3. 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
   stringData:
     token: <Content_of_access_token>
   type: Opaque

   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.

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

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

6. 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. 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: <gitconfig content> 2

   1

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

   2

   The content of your gitconfig file content.

2. Apply the ConfigMap.

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

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

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

   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: /public-certs
       controller.devfile.io/mount-as: file
     labels:
       controller.devfile.io/mount-to-devworkspace: 'true'
       controller.devfile.io/watch-secret: 'true'
   data:
     nexus.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:
     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: http://devspaces-dashboard.openshift-devspaces.svc.cluster.local:8080/dashboard/api/editors/devfile?che-editor=che-incubator/che-code/latest
     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.

   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.