Branding Che-Theia

This chapter describes how to customize the Che-Theia interface and branding. Customization is possible for the following elements:

Welcome page and About dialog:
- Product name
- Product logo
- Description
- List of helpful resources (Help section of the Welcome page)

To start using the customized Che-Theia:

Build a container image with the customized Che-Theia.
Define an editor meta.yaml that uses the custom image.
Create a workspace from a devfile using the custom editor.

Defining custom branding values for Che-Theia

This section describes how to customize definitions of basic branding elements of Che-Theia.

Procedure

Create a product.json file with a new name of the product, logo, description, and list of hyperlinks on the Welcome page (an example of product.json:

{
    "name": "Red Hat OpenShift Dev Spaces", (1)
    "icon": "icon.png", (2)
    "logo": { (3)
        "dark": "logo-light.png",
        "light": "logo-dark.png"
    },
    "welcome": { (4)
        "title": "Welcome to Your Workspace",
        "links": ["website", "documentation"]
    },
    "links": { (5)
        "website": {
            "name": "Discover Red Hat OpenShift Dev Spaces",
            "url": "https://developers.redhat.com/products/openshift-dev-spaces/overview"
        },
        "documentation": {
            "name": "Browse Documentation",
            "url": "https://www.redhat.com/docs"
        }
    }
}

1	`name`: tab title for the Welcome page and the About dialog.
2	`icon`: icon for the Welcome page tab title.
3	`logo`: product logo for dark and light themes on the Welcome page (maximum height 80 pixels) and in the About dialog (maximum height 100 pixels). Use an image with a transparent background. Define a relative path, an absolute path, or a URL to an image.
4	`welcome`: the behavior of the Welcome page. Customize the invitation title and the links in the Help section. When the `welcome/links` property is not defined, the Welcome page displays the links from the `links` section.
5	`links`: list of helpful resources for the product. Use tags to group links to make them easier to find.

To use only one logo image for both dark and light themes:

{
    ...
    "logo": "product-logo.png"
    ...
}

Building a Che-Theia container image with custom branding

This section describes how to build a Che-Theia container image with custom branding applied.

Prerequisites

A product.json file with custom branding definitions.

Procedure

Download an example Dockerfile.
In the Dockerfile directory, create a branding/ sub-directory. Place the custom product.json file and logo images into the branding/ directory.

Build the container image with Che-Theia and push the image to a container registry:

$ docker build -t username/che-theia-devspaces:next .
$ docker push username/che-theia-devspaces:next

Testing Che-Theia with custom branding

This section describes how to test a customized Che-Theia by opening a new workspace with custom branding.

Prerequisites

Che-Theia container image built with custom branding definitions.

Procedure

To test a custom Che-Theia image, create a new meta.yaml file describing a custom cheEditor, and use it in a devfile for the testing workspace.

Clone the che-plugin-registry repository and check out the version to deploy. See,

$ git clone git@github.com:eclipse/che-plugin-registry.git
$ cd che-plugin-registry
$ git checkout 7.50.x

Open the che-editors.yaml file.
Edit the entry where id equals eclipse/che-theia/next and replace the image value in the containers section to point to the custom Che-Theia container image.

Build the registry:

$ ./build.sh --organization <my-org> \
           --registry <my-registry> \
           --tag <my-tag>

Navigate to the ./che-plugin-registry/v3/plugins/eclipse/che-theia/next directory.
Publish the meta.yaml file in this directory to a publicly accessible location where it can be used as an HTTP resource.

Create a workspace using the sample che-theia-branding-example devfile to apply the changes.

Verify the reference field points to your published meta.yaml file:

metadata:
  name: che-theia-all
projects:
  - name: che-cheia-branding-example
    source:
      location: 'https://github.com/che-samples/che-theia-branding-example.git'
      type: git
      branch: master
components:
  - type: cheEditor
    reference: >-
      https://raw.githubusercontent.com/che-samples/che-theia-branding-example/master/che-editor.meta.yaml
apiVersion: 1.0.0

Run the workspace to see the changes:
- The dark theme of Che-Theia:
- The light theme of Che-Theia: