Chapter 11. Configure dashboard

Procedure

1. Create a JSON file with the samples configuration. The file must contain an array of objects, where each object represents a sample.

   cat > my-samples.json <<EOF
   [
     {
       "displayName": "<display_name>",
       "description": "<description>",
       "tags": <tags>,
       "url": "<url>",
       "icon": {
         "base64data": "<base64data>",
         "mediatype": "<mediatype>"
       }
     }
   ]
   EOF

   where:

   displayName

   The display name of the sample.

   description

   The description of the sample.

   tags

   The JSON array of tags, for example, ["java", "spring"].

   url

   The URL to the repository containing the devfile.

   base64data

   The base64-encoded data of the icon.

   mediatype

   The media type of the icon. For example, image/png.

2. Create a ConfigMap with the samples configuration:

   oc create configmap getting-started-samples --from-file=my-samples.json -n openshift-devspaces

3. Add the required labels to the ConfigMap:

   oc label configmap getting-started-samples app.kubernetes.io/part-of=che.eclipse.org app.kubernetes.io/component=getting-started-samples -n openshift-devspaces

Procedure

1. Create the my-editor-definition-devfile.yaml YAML file with the editor definition configuration. Provide actual values for publisher and version under metadata.attributes because these construct the editor ID in the format publisher/name/version.

   For example:

   # Version of the devfile schema
   schemaVersion: 2.2.2
   # Meta information of the editor
   metadata:
     # (MANDATORY) The editor name
     # Must consist of lower case alphanumeric characters, '-' or '.'
     name: editor-name
     displayName: Display Name
     description: Run Editor Foo on top of OpenShift Dev Spaces
     # (OPTIONAL) Array of tags of the current editor. The Tech-Preview tag means the option is considered experimental and is not recommended for production environments. While it can include new features and improvements, it may still contain bugs or undergo significant changes before reaching a stable version.
     tags:
       - Tech-Preview
     # Additional attributes
     attributes:
       title: This is my editor
       # (MANDATORY) The supported architectures
       arch:
         - x86_64
         - arm64
       # (MANDATORY) The publisher name
       publisher: publisher
       # (MANDATORY) The editor version
       version: version
       repository: https://github.com/editor/repository/
       firstPublicationDate: '2024-01-01'
       iconMediatype: image/svg+xml
       iconData: |
         <icon-content>
   # List of editor components
   components:
     # Name of the component
     - name: che-code-injector
       # Configuration of devworkspace-related container
       container:
         # Image of the container
         image: 'quay.io/che-incubator/che-code:insiders'
         # The command to run in the dockerimage component instead of the default one provided in the image
         command:
           - /entrypoint-init-container.sh
         # (OPTIONAL) List of volumes mounts that should be mounted in this container
         volumeMounts:
             # The name of the mount
           - name: checode
             # The path of the mount
             path: /checode
         # (OPTIONAL) The memory limit of the container
         memoryLimit: 256Mi
         # (OPTIONAL) The memory request of the container
         memoryRequest: 32Mi
         # (OPTIONAL) The CPU limit of the container
         cpuLimit: 500m
         # (OPTIONAL) The CPU request of the container
         cpuRequest: 30m
     # Name of the component
     - name: che-code-runtime-description
       # (OPTIONAL) Map of implementation-dependant free-form YAML attributes
       attributes:
         # The component within the architecture
         app.kubernetes.io/component: che-code-runtime
         # The name of a higher level application this one is part of
         app.kubernetes.io/part-of: che-code.eclipse.org
         # Defines a container component as a "container contribution". If a flattened DevWorkspace has a container component with the merge-contribution attribute, then any container contributions are merged into that container component
         controller.devfile.io/container-contribution: true
       container:
         # Can be a placeholder image because the component is expected to be injected into workspace dev component
         image: quay.io/devfile/universal-developer-image:latest
         # (OPTIONAL) List of volume mounts that should be mounted in this container
         volumeMounts:
             # The name of the mount
           - name: checode
             # (OPTIONAL) The path in the component container where the volume should be mounted. If no path is defined, the default path is /<name>
             path: /checode
         # (OPTIONAL) The memory limit of the container
         memoryLimit: 1024Mi
         # (OPTIONAL) The memory request of the container
         memoryRequest: 256Mi
         # (OPTIONAL) The CPU limit of the container
         cpuLimit: 500m
         # (OPTIONAL) The CPU request of the container
         cpuRequest: 30m
         # (OPTIONAL) Environment variables used in this container
         env:
           - name: ENV_NAME
             value: value
         # Component endpoints
         endpoints:
           # Name of the editor
           - name: che-code
             # (OPTIONAL) Map of implementation-dependant string-based free-form attributes
             attributes:
               # Type of the endpoint. You can only set its value to main, indicating that the endpoint should be used as the mainUrl in the workspace status (i.e. it should be the URL used to access the editor in this context)
               type: main
               # An attribute that instructs the service to automatically redirect the unauthenticated requests for current user authentication. Setting this attribute to true has security consequences because it makes Cross-site request forgery (CSRF) attacks possible. The default value of the attribute is false.
               cookiesAuthEnabled: true
               # Defines an endpoint as "discoverable", meaning that a service should be created using the endpoint name (i.e. instead of generating a service name for all endpoints, this endpoint should be statically accessible)
               discoverable: false
               # Used to secure the endpoint with authorization on OpenShift, so that not anyone on the cluster can access the endpoint, the attribute enables authentication.
               urlRewriteSupported: true
             # Port number to be used within the container component
             targetPort: 3100
             # (OPTIONAL) Describes how the endpoint should be exposed on the network (public, internal, none)
             exposure: public
             # (OPTIONAL) Describes whether the endpoint should be secured and protected by some authentication process
             secure: true
             # (OPTIONAL) Describes the application and transport protocols of the traffic that will go through this endpoint
             protocol: https
       # Mandatory name that allows referencing the component from other elements
     - name: checode
       # (OPTIONAL) Allows specifying the definition of a volume shared by several other components. Ephemeral volumes are not stored persistently across restarts. Defaults to false
       volume: {ephemeral: true}
   # (OPTIONAL) Bindings of commands to events. Each command is referred-to by its name
   events:
     # IDs of commands that should be executed before the devworkspace start. These commands would typically be executed in an init container
     preStart:
       - init-container-command
     # IDs of commands that should be executed after the devworkspace has completely started. In the case of Che-Code, these commands should be executed after all plugins and extensions have started, including project cloning. This means that those commands are not triggered until the user opens the IDE within the browser
     postStart:
       - init-che-code-command
   # (OPTIONAL) Predefined, ready-to-use, devworkspace-related commands
   commands:
       # Mandatory identifier that allows referencing this command
     - id: init-container-command
       apply:
         # Describes the component for the apply command
         component: che-code-injector
       # Mandatory identifier that allows referencing this command
     - id: init-che-code-command
       # CLI Command executed in an existing component container
       exec:
         # Describes component for the exec command
         component: che-code-runtime-description
         # The actual command-line string
         commandLine: 'nohup /checode/entrypoint-volume.sh > /checode/entrypoint-logs.txt
           2>&1 &'

   where:

   <icon-content>

   The SVG icon data for the editor, displayed in the OpenShift Dev Spaces Dashboard editor selector.

2. Create a ConfigMap with the editor definition content:

   oc create configmap my-editor-definition --from-file=my-editor-definition-devfile.yaml -n openshift-devspaces

3. Add the required labels to the ConfigMap:

   oc label configmap my-editor-definition app.kubernetes.io/part-of=che.eclipse.org app.kubernetes.io/component=editor-definition -n openshift-devspaces

Procedure

1. Determine the IDs of the deprecated editors. An editor ID has the following format: publisher/name/version.

   oc exec deploy/devspaces-dashboard -n openshift-devspaces  \
       -- curl -s http://localhost:8080/dashboard/api/editors | jq -r '[.[] | select(.metadata.tags != null) | select(.metadata.tags[] | contains("Deprecate")) | "\(.metadata.attributes.publisher)/\(.metadata.name)/\(.metadata.attributes.version)"]'

2. Configure the CheCluster Custom Resource. See Section 2.2, “Use the CLI to configure the CheCluster Custom Resource”.

   spec:
     components:
       dashboard:
         deployment:
           containers:
           - env:
             - name: CHE_SHOW_DEPRECATED_EDITORS
               value: 'true'

Procedure

1. Determine the IDs of the available editors. An editor ID has the following format: publisher/name/version.

   oc exec deploy/devspaces-dashboard -n openshift-devspaces  \
       -- curl -s http://localhost:8080/dashboard/api/editors | jq -r '[.[] | "\(.metadata.attributes.publisher)/\(.metadata.name)/\(.metadata.attributes.version)"]'

2. Configure the defaultEditor:

   oc patch checluster/devspaces \
       --namespace openshift-devspaces \
       --type='merge' \
       -p '{"spec":{"devEnvironments":{"defaultEditor": "<default_editor>"}}}'

   where:

   <default_editor>

   The default editor specified as a plugin ID in publisher/name/version format or as a URI.

Procedure

1. Determine the IDs of the available editors. An editor ID has the following format: publisher/name/version.

   oc exec deploy/devspaces-dashboard -n openshift-devspaces  \
       -- curl -s http://localhost:8080/dashboard/api/editors | jq -r '[.[] | "\(.metadata.attributes.publisher)/\(.metadata.name)/\(.metadata.attributes.version)"]'

2. Configure the CheCluster Custom Resource. See Section 2.2, “Use the CLI to configure the CheCluster Custom Resource”.

   spec:
     components:
       dashboard:
         deployment:
           containers:
           - env:
             - name: CHE_HIDE_EDITORS_BY_ID
               value: 'che-incubator/che-webstorm-server/latest, che-incubator/che-webstorm-server/next'

   where:

   value

   A string containing comma-separated IDs of editors to hide.

Procedure

1. Determine the IDs of the available editors. An editor ID has the following format: publisher/name/version.

   oc exec deploy/devspaces-dashboard -n openshift-devspaces  \
       -- curl -s http://localhost:8080/dashboard/api/editors | jq -r '[.[] | "\(.metadata.attributes.publisher)/\(.metadata.name)/\(.metadata.attributes.version)"]'

2. Configure the download URLs for editors:

   oc patch checluster/devspaces \
     --namespace openshift-devspaces \
     --type='merge' \
     -p '{
       "spec": {
         "devEnvironments": {
           "editorsDownloadUrls": [
             { "editor": "publisher1/editor-name1/version1", "url": "https://example.com/editor1.tar.gz" },
             { "editor": "publisher2/editor-name2/version2", "url": "https://example.com/editor2.tar.gz" }
           ]
         }
       }
     }'

   where:

   editor

   The editor ID in the format publisher/name/version. Determine the IDs by running the command in step 1.

   url

   The URL of the editor archive to download.

Procedure

1. Create a Secret that mounts custom branding images into the dashboard:

   oc apply -f - <<EOF
   apiVersion: v1
   kind: Secret
   metadata:
     name: devspaces-dashboard-customization
     namespace: openshift-devspaces
     annotations:
       che.eclipse.org/mount-as: subpath
       che.eclipse.org/mount-path: /public/dashboard/assets/branding
     labels:
       app.kubernetes.io/component: devspaces-dashboard-secret
       app.kubernetes.io/part-of: che.eclipse.org
   data:
     che-logo.svg: <Base64_encoded_content_of_the_image>
     loader.svg: <Base64_encoded_content_of_the_image>
     favicon.ico: <Base64_encoded_content_of_the_image>
   type: Opaque
   EOF

   where:

   che-logo.svg

   The dashboard logo. Replace the value with the Base64-encoded content of your custom logo with disabled line wrapping.

   loader.svg

   The loader icon. Replace loader.svg with the filename matching your image format (for example, loader.png, loader.webp). The value is the Base64-encoded content of the image with disabled line wrapping.

   favicon.ico

   The favicon. The value is the Base64-encoded content of the .ico file with disabled line wrapping.

   Note

   You can override one or all images from the /public/dashboard/assets/branding directory in the dashboard pod. Only the images specified in the Secret data section are overridden. Unspecified images remain unchanged.

2. Verify that the rollout completes:

   $ oc rollout status deployment/devspaces-dashboard -n openshift-devspaces