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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap
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.7/html-single/end-user_guide/index#making-a-workspace-portable-using-a-devfile_crw.

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

   Expand

   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.

   Show more

   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

   Copy to Clipboard Toggle word wrap

5. Build a custom devfile registry image:

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

   Copy to Clipboard Toggle word wrap
   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.7-rhel-8

   Copy to Clipboard Toggle word wrap

2. In the ./dependencies/che-plugin-registry/v3/plugins/ directory, create new directories <publisher>/<plugin-name>/<plugin-version>/ and a meta.yaml file in the last directory.

   Example 3.3. File organization for a plugin

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

   Copy to Clipboard Toggle word wrap
3. Add valid content to the meta.yaml file. See: https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.7/html-single/end-user_guide/index#proc_publishing-metadata-for-a-vs-code-extension_crw.

4. Create a file named latest.txt with content the name of the latest <plugin-version> directory.

   Example 3.4. Example plug-in files tree

   $ tree che-plugin-registry/v3/plugins/redhat/java/
   che-plugin-registry/v3/plugins/redhat/java/
   ├── 0.38.0
   │   └── meta.yaml
   ├── 0.43.0
   │   └── meta.yaml
   ├── 0.45.0
   │   └── meta.yaml
   ├── 0.46.0
   │   └── meta.yaml
   ├── 0.50.0
   │   └── meta.yaml
   └── latest.txt
   $ cat che-plugin-registry/v3/plugins/redhat/java/latest.txt
   0.50.0

   Copy to Clipboard Toggle word wrap

5. Build a custom plug-ins registry image:

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

   Copy to Clipboard Toggle word wrap
   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.

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"

   Copy to Clipboard Toggle word wrap

   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"

   Copy to Clipboard Toggle word wrap

   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.5. 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>")'

   Copy to Clipboard Toggle word wrap

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

   Example 3.6. 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>")'

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

1. The plug-ins are available in the completion to chePlugin components in Devfile tab of a workspace details.

1. The plug-ins are available in the Plugin Theia view of a workspace.
2. The devfiles are available in the Get Started and Create Custom Workspace tab of the user dashboard.