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. In your home directory, locate and open your .git-credentials file if you already have it. Alternatively, if you do not have this file, save a new .git-credentials file, using the Git credentials storage format. Each credential is stored on its own line in the file:

   https://<username>:<token>@<git_server_hostname>

   Example 6.1. A line in a .git-credentials file

   https://trailblazer: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@github.com

2. Select credentials from your .git-credentials file for the Secret. Encode the selected credentials to Base64 for the next step.

   Tip

   • To encode all lines in the file:

     $ cat .git-credentials | base64 | tr -d '\n'

   • To encode a selected line:

     $ echo -n '<copied_and_pasted_line_from_.git-credentials>' | base64

3. Create a new OpenShift Secret in your user project.

   apiVersion: v1
   kind: Secret
   metadata:
     name: git-credentials-secret
     labels:
       controller.devfile.io/git-credential: 'true' 1
       controller.devfile.io/watch-secret: 'true'
     annotations:
       controller.devfile.io/mount-path: /etc/secret 2
   data:
     credentials: <Base64_content_of_.git-credentials> 3

   1

   The controller.devfile.io/git-credential label marks the Secret as containing Git credentials.

   2

   A custom absolute path in the DevWorkspace containers. The Secret is mounted as the credentials file at this path. The default path is /.

   3

   The selected content from .git-credentials that you encoded to Base64 in the previous step.

   Tip

   You can create and apply multiple Git credentials Secrets in your user project. All of them will be copied into one Secret that will be mounted to the DevWorkspace containers. For example, if you set the mount path to /etc/secret, then the one Secret with all of your Git credentials will be mounted at /etc/secret/credentials. You must set all Git credentials Secrets in your user project to the same mount path. You can set the mount path to an arbitrary path because the mount path will be automatically set in the Git configuration file configured at /etc/gitconfig.

4. Apply the Secret.

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

Procedure

1. Copy your access token and encode it to Base64.

   $ echo -n '<your_access_token>' | base64

2. Prepare a new OpenShift Secret in your user project.

   kind: Secret
   apiVersion: v1
   metadata:
     name: personal-access-token-<your_chosen_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 Che user ID. You can retrieve <che-endpoint>/api/user to get the Che user data.

   2

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

   3

   The Git provider URL.

   4

   Your Git provider user ID, follow the API documentation to retrieve the user object:

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

3. Apply the Secret.

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

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. In your user project, create an image pull Secret with your private container registry details and credentials:

   $ oc create secret docker-registry <Secret_name> \
       --docker-server=<registry_server> \
       --docker-username=<username> \
       --docker-password=<password> \
       --docker-email=<email_address>

2. Add the following label to the image pull Secret:

   $ oc label secret <Secret_name> controller.devfile.io/devworkspace_pullsecret=true controller.devfile.io/watch-secret=true

Procedure

1. Encode the .dockercfg file to Base64:

   $ cat .dockercfg | base64 | tr -d '\n'

2. Create a new OpenShift Secret in your user project:

   apiVersion: v1
   kind: Secret
   metadata:
     name: <Secret_name>
     labels:
       controller.devfile.io/devworkspace_pullsecret: 'true'
       controller.devfile.io/watch-secret: 'true'
   data:
     .dockercfg: <Base64_content_of_.dockercfg>
   type: kubernetes.io/dockercfg

3. Apply the Secret:

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

Procedure

1. Encode the $HOME/.docker/config.json file to Base64.

   $ cat config.json | base64 | tr -d '\n'

2. Create a new OpenShift Secret in your user project:

   apiVersion: v1
   kind: Secret
   metadata:
     name: <Secret_name>
     labels:
       controller.devfile.io/devworkspace_pullsecret: 'true'
       controller.devfile.io/watch-secret: 'true'
   data:
     .dockerconfigjson: <Base64_content_of_config.json>
   type: kubernetes.io/dockerconfigjson

3. Apply the Secret:

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

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

Prerequisites

1. You have the .che/che-theia-plugins.yaml file in the root of the GitHub repository.

Procedure

1. Add the ID of the plug-in to the .che/che-theia-plugins.yaml file. Use the / sign to separate the publisher and plug-in name. The following example uses the IDs of Red Hat Visual Studio Code Java extension:

   - id: redhat/java/latest

Prerequisites

1. You have the .che/che-theia-plugins.yaml file in the root of the GitHub repository.

Procedure

1. Add an override section to the .che/che-theia-plugins.yaml file under the id of the plug-in.

2. Specify the memory limit for the extension. In the following example, OpenShift Dev Spaces automatically installs the Red Hat Visual Studio Code Java extension in the OpenShift Dev Spaces workspace and increases the memory of the workspace by two gigabytes:

     - id: redhat/java/latest
       override:
         sidecar:
           memoryLimit: 2Gi

Prerequisites

1. You have the .che/che-theia-plugins.yaml file in the root of the GitHub repository.

Procedure

1. Add an override section to the .che/che-theia-plugins.yaml file under the id of the extension.

2. Specify the preferences in the Preferences section. In the following example, OpenShift Dev Spaces automatically installs Red Hat Visual Studio Code Java extension in the OpenShift Dev Spaces workspace and sets the java.server.launchMode preference to LightWeight:

     - id: redhat/java/latest
       override:
         preferences:
           java.server.launchMode: LightWeight

Procedure

1. Add an attributes section to your devfile.yaml file.
2. Add .vscode/extensions.json to the atributes section. Add a | sign after the colon separator.

3. Paste the contents of the .vscode/extensions.json file after the | sign. The following example uses Red Hat Visual Studio Code Java extension attributes:

   schemaVersion: 2.2.0
   metadata:
     name: my-example
   attributes:
     .vscode/extensions.json: |
       {
         "recommendations": [
           "redhat.java"
         ]
       }

Procedure

1. Add an attributes section to your devfile.yaml file.
2. Add .vscode/extensions.json to the atributes section. Add a | sign after the colon separator.

3. Paste the content of the .che/che-theia-plugins.yaml file after the | sign. The following example uses Red Hat Visual Studio Code Java extension attributes:

   schemaVersion: 2.2.0
   metadata:
     name: my-example
   attributes:
     .che/che-theia-plugins.yaml: |
       - id: redhat/java/latest