Chapter 3. Customizing the registries

This chapter describes how to build and run custom registries for CodeReady Workspaces.

3.1. Understanding the CodeReady Workspaces registries

CodeReady Workspaces uses two registries: the plug-ins registry and the devfile registry. They are static websites publishing the metadata of CodeReady Workspaces plug-ins and devfiles. When built in offline mode they also include artifacts.

The devfile and plug-in registries run in two separate Pods. Their deployment is part of the CodeReady Workspaces installation.

The devfile and plug-in registries

The devfile registry
The devfile registry holds the definitions of the CodeReady Workspaces stacks. Stacks are available on the CodeReady Workspaces user dashboard when selecting Create Workspace. It contains the list of CodeReady Workspaces technological stack samples with example projects. When built in offline mode it also contains all sample projects referenced in devfiles as zip files.
The plug-in registry
The plug-in registry makes it possible to share a plug-in definition across all the users of the same instance of CodeReady Workspaces. When built in offline mode it also contains all plug-in or extension artifacts.

Additional resources

3.2. Building custom registry images

3.2.1. Building a custom devfile registry image

This section describes how to build a custom devfile registry image. The procedure explains how to add a devfile. The image contains all sample projects referenced in devfiles.

Prerequisites

Procedure

  1. Clone the devfile registry repository and check out the version to deploy: 

    $ git clone git@github.com:redhat-developer/codeready-workspaces.git
$ cd codeready-workspaces
$ git checkout crw-2.9-rhel-8

  2. In the ./dependencies/che-devfile-registry/devfiles/ directory, create a subdirectory <devfile-name>/ and add the devfile.yaml and meta.yaml files.

    Example 3.1. File organization for a devfile

    ./dependencies/che-devfile-registry/devfiles/
└── <devfile-name>
    ├── devfile.yaml
    └── meta.yaml
  3. Add valid content in the devfile.yaml file. For a detailed description of the devfile format, see Authoring devfiles version 2.

  4. Ensure that the meta.yaml file conforms to the following structure:

    Table 3.1. Parameters for a devfile meta.yaml

    AttributeDescription

    description

    Description as it appears on the user dashboard.

    displayName

    Name as it appears on the user dashboard.

    globalMemoryLimit

    The sum of the expected memory consumed by all the components launched by the devfile. This number will be visible on the user dashboard. It is informative and is not taken into account by the CodeReady Workspaces server.

    icon

    Link to an .svg file that is displayed on the user dashboard.

    tags

    List of tags. Tags typically include the tools included in the stack.

    Example 3.2. Example devfile meta.yaml

    displayName: Rust
description: Rust Stack with Rust 1.39
tags: ["Rust"]
icon: https://www.eclipse.org/che/images/logo-eclipseche.svg
globalMemoryLimit: 1686Mi

  5. Build a custom devfile registry image: 

    $ cd dependencies/che-devfile-registry
$ ./build.sh --organization <my-org> \
           --registry <my-registry> \
           --tag <my-tag>
    Note

    To display full options for the build.sh script, use the --help parameter.

Additional resources

3.2.2. Building a custom plug-ins registry image

This section describes how to build a custom plug-ins registry image. The procedure explains how to add a plug-in. The image contains plug-ins or extensions metadata.

Prerequisites

  • NodeJS 12.x
  • A running version of yarn. See: Installing Yarn.
  • ./node_modules/.bin is in the PATH environment variable.
  • A running installation of podman or docker.

Procedure

  1. Clone the plug-ins registry repository and check out the version to deploy: 

    $ git clone git@github.com:redhat-developer/codeready-workspaces.git
$ cd codeready-workspaces
$ git checkout crw-2.9-rhel-8
  2. In the ./dependencies/che-plugin-registry/ directory, edit the che-theia-plugins.yaml file.
  3. Add valid content to the che-theia-plugins.yaml file, for detailed information see: Adding a VS Code extension to the Che plug-ins registry.

  4. Build a custom plug-ins registry image: 

    $ cd dependencies/che-plugin-registry
$ ./build.sh --organization <my-org> \
           --registry <my-registry> \
           --tag <my-tag>
    Note

    To display full options for the build.sh script, use the --help parameter. To include the plug-in binaries in the registry image, add the --offline parameter.

  5. Observe the contents of ./dependencies/che-plugin-registry/v3/plugins/ present in the container after building the registry. All meta.yaml files resulting from a successful plug-ins registry build will be located here. 

    ./dependencies/che-plugin-registry/v3/plugins/
├── <publisher>
│   └── <plugin-name>
│       ├── latest
│       │   └── meta.yaml
│       └── latest.txt

    Additional resources

3.3. Running custom registries

Prerequisites

The my-plug-in-registry and my-devfile-registry images used in this section are built using the docker command. This section assumes that these images are available on the OpenShift cluster where CodeReady Workspaces is deployed.

These images can be then pushed to:

  • A public container registry such as quay.io, or the DockerHub.
  • A private registry.

3.3.1. Deploying registries in OpenShift

Procedure

An OpenShift template to deploy the plug-in registry is available in the deploy/openshift/ directory of the GitHub repository.

  1. To deploy the plug-in registry using the OpenShift template, run the following command: 

    NAMESPACE=<namespace-name>  1
IMAGE_NAME="my-plug-in-registry"
IMAGE_TAG="latest"
oc new-app -f openshift/che-plugin-registry.yml \
 -n "$\{NAMESPACE}" \
 -p IMAGE="$\{IMAGE_NAME}" \
 -p IMAGE_TAG="$\{IMAGE_TAG}" \
 -p PULL_POLICY="Always"
    1
    If installed using crwctl, the default CodeReady Workspaces project is openshift-workspaces. The OperatorHub installation method deploys CodeReady Workspaces to the users current project.

  2. The devfile registry has an OpenShift template in the deploy/openshift/ directory of the GitHub repository. To deploy it, run the command: 

    NAMESPACE=<namespace-name>  1
IMAGE_NAME="my-devfile-registry"
IMAGE_TAG="latest"
oc new-app -f openshift/che-devfile-registry.yml \
 -n "$\{NAMESPACE}" \
 -p IMAGE="$\{IMAGE_NAME}" \
 -p IMAGE_TAG="$\{IMAGE_TAG}" \
 -p PULL_POLICY="Always"
    1
    If installed using crwctl, the default CodeReady Workspaces project is openshift-workspaces. The OperatorHub installation method deploys CodeReady Workspaces to the users current project.

Verification steps

  1. The <plug-in> plug-in is available in the plug-in registry.

    Example 3.3. Find <plug-in> requesting the plug-in registry API.

    $ URL=$(oc  get route -l app=che,component=plugin-registry \
  -o 'custom-columns=URL:.spec.host' --no-headers)
$ INDEX_JSON=$(curl -sSL http://${URL}/v3/plugins/index.json)
$ echo ${INDEX_JSON} | jq '.[] | select(.name == "<plug-in>")'

  2. The <devfile> devfile is available in the devfile registry.

    Example 3.4. Find <devfile> requesting the devfile registry API.

    $ URL=$(oc  get route -l app=che,component=devfile-registry \
  -o 'custom-columns=URL:.spec.host' --no-headers)
$ INDEX_JSON=$(curl -sSL http://${URL}/v3/plugins/index.json)
$ echo ${INDEX_JSON} | jq '.[] | select(.name == "<devfile>")'

  3. CodeReady Workspaces server points to the URL of the plug-in registry.

    Example 3.5. Compare the value of the CHE_WORKSPACE_PLUGIN__REGISTRY__URL parameter in the che ConfigMap with the URL of the plug-in registry route.

    Get the value of the CHE_WORKSPACE_PLUGIN__REGISTRY__URL parameter in the che ConfigMap.

    $ oc  get cm/che \
  -o "custom-columns=URL:.data['CHE_WORKSPACE_PLUGIN__REGISTRY__URL']" \
  --no-headers

    Get the URL of the plug-in registry route.

    $ oc  get route -l app=che,component=plugin-registry \
  -o 'custom-columns=URL: .spec.host' --no-headers

  4. CodeReady Workspaces server points to the URL of the devfile registry.

    Example 3.6. Compare the value of the CHE_WORKSPACE_DEVFILE__REGISTRY__URL parameter in the che ConfigMap with the URL of the devfile registry route.

    Get the value of the CHE_WORKSPACE_DEVFILE__REGISTRY__URL parameter in the che ConfigMap.

    $ oc  get cm/che \
  -o "custom-columns=URL:.data['CHE_WORKSPACE_DEVFILE__REGISTRY__URL']" \
  --no-headers

    Get the URL of the devfile registry route.

    $ oc  get route -l app=che,component=devfile-registry \
  -o 'custom-columns=URL: .spec.host' --no-headers

  5. If the values do not match, update the ConfigMap and restart the CodeReady Workspaces server. 

    $ oc  edit cm/codeready
(...)
$ oc  scale --replicas=0 deployment/codeready
$ oc  scale --replicas=1 deployment/codeready

  • The plug-ins are available in the:

    • Completion to chePlugin components in the Devfile tab of a workspace details
    • Plugin Che-Theia view of a workspace

  • The devfiles are available in the Get Started and Create Custom Workspace tab of the user dashboard.

3.3.2. Adding a custom plug-in registry in an existing CodeReady Workspaces workspace

The following section describes two methods of adding a custom plug-in registry in an existing CodeReady Workspaces workspace:

3.3.2.1. Adding a custom plug-in registry using Command Palette

Prerequisites

  • An instance of CodeReady Workspaces

Procedure

  1. In the CodeReady Workspaces IDE, press F1 to open the Command Palette, or navigate to View → Find Command in the top menu.

    The command palette can be also activated by pressing Ctrl+Shift+p (or Cmd+Shift+p on macOS).

  2. Enter the Add Registry command into the search box and pres Enter once filled.

  3. Enter the registry name and registry URL in next two command prompts.

    • After adding a new plug-in registry, the list of plug-ins in the Plug-ins view is refreshed, and if the new plug-in registry is not valid, a user is notified by a warning message.

3.3.2.2. Adding a custom plug-in registry using the settings.json file

The following section describes the use of the main CodeReady Workspaces Settings menu to edit and add a new plug-in registry using the settings.json file.

Prerequisites

  • An instance of CodeReady Workspaces

Procedure

  1. From the main CodeReady Workspaces screen, select Open Preferences by pressing Ctrl+, or using the gear wheel icon on the left bar.

  2. Select Che Plug-ins and continue by Edit in setting.json link.

    The setting.json file is displayed.

  3. Add a new plug-in registry using the chePlugins.repositories attribute as shown below: 

    {
“application.confirmExit”: “never”,
“chePlugins.repositories”: {“test”: “https://test.com”}
}

  4. Save the changes to add a custom plug-in registry in an existing CodeReady Workspaces workspace.

    • A newly added plug-in validation tool checks the correctness of URL values set in the chePlugins.repositories field of the settings.json file.
    • After adding a new plug-in registry, the list of plug-ins in the Plug-ins view is refreshed, and if the new plug-in registry is not valid, a user is notified by a warning message. This check is also functional for plug-ins added using the Command palette command Add plugin registry.