Describe process for making and testing Che 7 plugin from vscode plugin

[tsmaeder]

Write a small how-to on how to create and test a che 7 plugin from an existing vscode plugin. Add it to the Che wiki pages.

[tolusha]

How to create and test a Che 7 plugin from an existing VS Code extension

Complete the following steps to run a Che 7 plugin based on VS Code extension

1. Prepare a docker image based on wsskeleton/theia-endpoint-runtime. This image is used as runtime to launch VS Code plugins in sidecars and should additionally contain all necessary tools/software/plugin dependencies, for instance java, Go etc. A Dockerfile and image can be hosted anywhere and there are no restrictions or naming rules. Here is an example for java8 image.

2. Build and push image to Docker Hub. @riuvshin needs to be contacted if it is necessary to publish image under Eclipse foundation DockerHub account. It can be any other public Docker registry though.

3. Prepare meta.yaml for desired plugin. Take a look at an example for a node debug plugin:

id: ms-vscode.node-debug2
version: 1.31.1
type: VS Code extension
name: Node Debug
title: Node.js debugging support
description: Node Debug is the debugger for Node.js versions >= 8.0 https://marketplace.visualstudio.com/items?itemName=ms-vscode.node-debug2
icon: https://www.eclipse.org/che/images/logo-eclipseche.svg
attributes:
  extension: "vscode:extension/ms-vscode.node-debug2"
  container-image: "abazko/ms-vscode.node-debug2" 

• extension attribute consists of prefix vscode:extension/ and VS Code extension ID that can be retrieved from plugin details page at marketplace

• container-image attribute contains the image name from the step Update DTD for GWT-module descriptors #1 - registry/org/repo:tag. In the example abovce, registry is omitted since this is DockerHub. And if no tag is specified, latest is used by default.

4. Push meta.yaml to https://github.com. The list of available plugins. It may not be GitHub. It's enough to host your yaml anywhere it's accessible for plugin broker (Apache server etc).

5. Create workspace and add plugin url to the workspace config.

Important notes:

• plugin's url in the workspace config should be the url to the raw content, like:
• the version of the plugin in meta.yaml has to be the same as a name of parent folder which contains thats file

"attributes": {
    "editor": "org.eclipse.che.editor.theia:1.0.0",
    "plugins": "che-machine-exec-plugin:0.0.1,https://raw.githubusercontent.com/eclipse/che-plugin-registry/master/plugins/org.eclipse.che.samples.container-fortune:0.0.1"
  }

Please, note that the URL to meta.yaml should be a direct URL to file contents, not the page that contains/serves it (raw GitHub link in the example above).

[tolusha]

/cc
@garagatyi Could you check it out?

[tsmaeder]

@tolusha

• Where should the docker file live?
• What should the image be called?
• If they are under eclipse/ how do I get the images published?
• Probably you mean "push to docker hub", not pull?
• Which repository contains the meta.yaml and where should it be placed, how should it be named?
• The url to the list of available plugins is probably wrong: https://github.com/garagatyi/che-plugin-registry/tree/sonarlint/plugins ...sonarlint seems odd.

[tolusha]

Here are answers, if we agreed on them I will add to the how-to.

Where should the docker file live?

Basically anywhere, it doesn't matter, for instance in the user's github repository.

What should the image be called?

I am not aware of naming convention. ${username}/${plugin-id} sounds reasonable for me.
Does it really matter?

If they are under eclipse/ how do I get the images published?

I honestly do not know. @benoitf do you know the answer?

Probably you mean "push to docker hub", not pull?

fixed

Which repository contains the meta.yaml and where should it be placed, how should it be named?

${github-url}/${plugin-id}/${version}/meta.yaml Like https://github.com/eclipse/che-plugin-registry/blob/master/plugins/che-dummy-plugin/0.0.1/meta.yaml

The url to the list of available plugins is probably wrong

fixed

[tolusha]

@svor
in your documentation #12447 you have extension: vscode:extension/ms-vscode.node-debug2 in meta.yaml. What is vscode:extension/ms-vscode.node-debug2 and where I can find this info for my extension?

@tolusha
that's a very good question =)
here is the link https://marketplace.visualstudio.com/items?itemName=ms-vscode.node-debug2 for node debug extension vscode:extension/ is a prefix and it is the same for all plugins based on vscode extensions ms-vscode.node-debug2 comes from url

[svor]

@tolusha
1/ Plugin's url in the workspace config should be the url to the raw content, like:
https://raw.githubusercontent.com/eclipse/che-plugin-registry/master/plugins/org.eclipse.che.samples.container-fortune:0.0.1
2/ It is important to say that the plugin's version in meta.yaml should be the same as a name of parent folder which contains this file

[tolusha]

@svor
Cool thank you!

[garagatyi]

@tolusha yes, what you described is correct.
Just to echo your suggestions:
Dockerfile and image can be hosted anywhere and be named as plugin author wants.
For base java8 image I chose location here.
@riuvshin needs to be contacted if the user wants his image published under Eclipse foundation DockerHub account.

Also, a long link like provided by @svor can be used when meta.yaml is not yet merged in the registry, but when it is merged user can use UI to add such extension to a workspace. And plugin entry would be way shorter in the workspace definition then.
VS Code extension ID can be retrieved from the extension page on the marketplace on the bottom right of the page where the meta information of an extension is placed.

@tolusha Could you edit your description to reflect everything described and add also information in which fields docker image and extension ID should be placed in metafile?

[tolusha]

Added to the wiki
https://github.com/eclipse/che/wiki/CHE-7---Development-Workflow