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 Section 3.2, "Building custom registry images" Section 3.3, "Running custom registries" 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 A running installation of podman or docker . Valid content for the devfile to add. See: https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.15/html-single/end-user_guide/index#authoring-devfiles-version-2.adoc . Procedure Clone the devfile registry repository and check out the version to deploy: 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 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.15/html-single/end-user_guide/index#authoring-devfiles-version-2.adoc . 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. 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. globalMemoryLimit Optional parameter: 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. 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: Note To display full options for the build.sh script, use the --help parameter. Additional resources https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.15/html-single/end-user_guide/index#authoring-devfiles-version-2.adoc . Section 3.3, "Running custom registries" . 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 Node.js 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 Clone the plug-ins registry repository and check out the version to deploy: In the ./dependencies/che-plugin-registry/ directory, edit the che-theia-plugins.yaml file. Add valid content to the che-theia-plugins.yaml file, for detailed information see: https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.15/html-single/end-user_guide/index#adding-a-vs-code-extension-to-the-che-plugin-registry.adoc . Build a custom plug-ins registry image: 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. 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. Additional resources Section 3.3, "Running custom registries" . 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. To deploy the plug-in registry using the OpenShift template, run the following command: 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. The devfile registry has an OpenShift template in the deploy/openshift/ directory of the GitHub repository. To deploy it, run the command: 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 The <plug-in> plug-in is available in the plug-in registry. Example 3.3. Find <plug-in> requesting the plug-in registry API. The <devfile> devfile is available in the devfile registry. Example 3.4. Find <devfile> requesting the devfile registry API. 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. Get the URL of the plug-in registry route. 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. Get the URL of the devfile registry route. If the values do not match, update the ConfigMap and restart the CodeReady Workspaces server. 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 Quick Add and Custom Workspace tab of the Create Workspace page on 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: Adding a custom plug-in registry using Command palette - For adding a new custom plug-in registry quickly, with a use of text inputs from Command palette command. This method does not allow a user to edit already existing information, such as plug-in registry URL or name. Adding a custom plug-in registry using the settings.json file - For adding a new custom plug-in registry and editing of the already existing entries. 3.3.2.1. Adding a custom plug-in registry using Command Palette Prerequisites An instance of CodeReady Workspaces Procedure 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). Enter the Add Registry command into the search box and pres Enter once filled. Enter the registry name and registry URL in 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 From the main CodeReady Workspaces screen, select Open Preferences by pressing Ctrl + , or using the gear wheel icon on the left bar. Select Che Plug-ins and continue by Edit in setting.json link. The setting.json file is displayed. Add a new plug-in registry using the chePlugins.repositories attribute as shown below: { "application.confirmExit": "never", "chePlugins.repositories": {"test": "https://test.com"} } 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 .

Commands:
git clone git@github.com:redhat-developer/codeready-workspaces.git cd codeready-workspaces git checkout crw-2.15-rhel-8
./dependencies/che-devfile-registry/devfiles/ └── <devfile-name> ├── devfile.yaml └── 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
cd dependencies/che-devfile-registry ./build.sh --organization <my-org> --registry <my-registry> --tag <my-tag>
git clone git@github.com:redhat-developer/codeready-workspaces.git cd codeready-workspaces git checkout crw-2.15-rhel-8
cd dependencies/che-plugin-registry ./build.sh --organization <my-org> --registry <my-registry> --tag <my-tag>
./dependencies/che-plugin-registry/v3/plugins/ ├── <publisher> │ └── <plugin-name> │ ├── latest │ │ └── meta.yaml │ └── latest.txt
NAMESPACE= <namespace-name> 1 IMAGE_NAME="my-plug-in-registry" IMAGE_TAG="latest" new-app -f openshift/che-plugin-registry.yml -n "USD\{NAMESPACE}" -p IMAGE="USD\{IMAGE_NAME}" -p IMAGE_TAG="USD\{IMAGE_TAG}" -p PULL_POLICY="Always"
NAMESPACE= <namespace-name> 1 IMAGE_NAME="my-devfile-registry" IMAGE_TAG="latest" new-app -f openshift/che-devfile-registry.yml -n "USD\{NAMESPACE}" -p IMAGE="USD\{IMAGE_NAME}" -p IMAGE_TAG="USD\{IMAGE_TAG}" -p PULL_POLICY="Always"
URL=USD(oc get route -l app=che,component=plugin-registry -o 'custom-columns=URL:.spec.host' --no-headers) INDEX_JSON=USD(curl -sSL http://USD{URL}/v3/plugins/index.json) echo USD{INDEX_JSON} | jq '.[] | select(.name == " <plug-in> ")'
URL=USD(oc get route -l app=che,component=devfile-registry -o 'custom-columns=URL:.spec.host' --no-headers) INDEX_JSON=USD(curl -sSL http://USD{URL}/v3/plugins/index.json) echo USD{INDEX_JSON} | jq '.[] | select(.name == " <devfile> ")'
oc get cm/che -o "custom-columns=URL:.data['CHE_WORKSPACE_PLUGIN__REGISTRY__URL']" --no-headers
oc get route -l app=che,component=plugin-registry -o 'custom-columns=URL: .spec.host' --no-headers
oc get cm/che -o "custom-columns=URL:.data['CHE_WORKSPACE_DEVFILE__REGISTRY__URL']" --no-headers
oc get route -l app=che,component=devfile-registry -o 'custom-columns=URL: .spec.host' --no-headers
oc edit cm/codeready (...) oc scale --replicas=0 deployment/codeready oc scale --replicas=1 deployment/codeready
{ "application.confirmExit": "never", "chePlugins.repositories": {"test": "https://test.com"} }