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

This section describes how to build an image containing custom devfile and plug-in registry images. The procedure explains how to add a new devfile and plug-in. The devfile registry image contains all sample projects referenced in devfiles. The plug-in registry image contains plug-ins or extensions metadata.

Procedure

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

In the ./dependencies/che-devfile-registry/devfiles/ directory, create a subdirectory <devfile-name>/ and add the devfile.yaml and meta.yaml files.
File organization for a devfile
```
./dependencies/che-devfile-registry/devfiles/
└── <devfile-name>
    ├── devfile.yaml
    └── meta.yaml
```
Add valid content in the devfile.yaml file. For a detailed description of the devfile format, see https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.5/html-single/end-user_guide/index#making-a-workspace-portable-using-a-devfile_crw.

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

Table 3.1. Parameters for a devfile meta.yaml
Attribute	Description
`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 usually include the tools included in the stack.

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

In the ./dependencies/che-devfile-registry/devfiles/ directory, create a subdirectory <devfile-name>/ and add the devfile.yaml and meta.yaml files.
File organization for a devfile
```
./dependencies/che-devfile-registry/devfiles/
└── <devfile-name>
    ├── devfile.yaml
    └── meta.yaml
```
Add valid content in the devfile.yaml file. For a detailed description of the devfile format, see https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.5/html-single/end-user_guide/index#making-a-workspace-portable-using-a-devfile_crw.

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

Table 3.2. Parameters for a devfile meta.yaml
Attribute	Description
`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 usually 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

Build a custom devfile registry image:

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

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

Tip

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.

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 openshift/ directory of the GitHub repository.

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="IfNotPresent"
```
1
If installed using crwctl, the default CodeReady Workspaces project is workspaces. The OperatorHub installation method deploys CodeReady Workspaces to the users current project.
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="IfNotPresent"
```
1
If installed using crwctl, the default CodeReady Workspaces project is workspaces. The OperatorHub installation method deploys CodeReady Workspaces to the users current project.

Check if the registries are deployed successfully on OpenShift.

To verify that the new plug-in is correctly published to the plug-in registry, make a request to the registry path /v3/plugins/index.json (or /devfiles/index.json for the devfile registry).

$ URL=$(oc get -o 'custom-columns=URL:.spec.rules[0].host' \
  -l app=che-plugin-registry route --no-headers)
$ INDEX_JSON=$(curl -sSL http://${URL}/v3/plugins/index.json)
$ echo ${INDEX_JSON} | grep -A 4 -B 5 "\"name\":\"my-plug-in\""
,\{
 "id": "my-org/my-plug-in/1.0.0",
 "displayName":"This is my first plug-in for CodeReady Workspaces",
 "version":"1.0.0",
 "type":"VS Code extension",
 "name":"my-plug-in",
 "description":"This plugin shows that we are able to add plugins to the registry",
 "publisher":"my-org",
 "links": \{"self":"/v3/plugins/my-org/my-plug-in/1.0.0" }
}
--
--
,\{
 "id": "my-org/my-plug-in/latest",
 "displayName":"This is my first plug-in for CodeReady Workspaces",
 "version":"latest",
 "type":"VS Code extension",
 "name":"my-plug-in",
 "description":"This plugin shows that we are able to add plugins to the registry",
 "publisher":"my-org",
 "links": \{"self":"/v3/plugins/my-org/my-plug-in/latest" }
}

Verify that the CodeReady Workspaces server points to the URL of the registry. To do this, compare the value of the CHE_WORKSPACE_PLUGIN__REGISTRY__URL parameter in the che ConfigMap (or CHE_WORKSPACE_DEVFILE__REGISTRY__URL for the devfile registry):

$ oc get \
  -o "custom-columns=URL:.data['CHE_WORKSPACE_PLUGINREGISTRYURL']" \
  --no-headers cm/che
URL
http://che-plugin-registry-che.192.168.99.100.nip.io/v3

with the URL of the route:

$ oc get -o 'custom-columns=URL:.spec.rules[0].host' \
  -l app=che-plugin-registry route --no-headers
che-plugin-registry-che.192.168.99.100.nip.io

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

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

When the new registries are deployed and the CodeReady Workspaces server is configured to use them, the new plug-ins are available in the Plugin view of a workspace and the new stacks are displayed in the New Workspace tab of the user dashboard.

Chapter 3. Customizing the registries

3.1. Understanding the CodeReady Workspaces registries

3.2. Building custom registry images

3.3. Running custom registries

3.3.1. Deploying registries in OpenShift

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links