Chapter 3. Customizing the registries

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.15-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 https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.15/html-single/end-user_guide/index#authoring-devfiles-version-2.adoc.

4. 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

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.

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.15-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: 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.

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

   • Section 3.3, “Running custom registries”.

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