From 88002fe4850ae5abc8425a04b6d9a49e7ccb1ffc Mon Sep 17 00:00:00 2001 From: Valeriy Svydenko Date: Tue, 5 Mar 2024 19:00:16 +0200 Subject: [PATCH 1/4] chore: add contribution part about editor definition Signed-off-by: Valeriy Svydenko --- CONTRIBUTE.md | 247 +++++++++++++++++++++++++++++++------------------- 1 file changed, 154 insertions(+), 93 deletions(-) diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md index a944908a5..21f2a895a 100644 --- a/CONTRIBUTE.md +++ b/CONTRIBUTE.md @@ -31,109 +31,168 @@ Che supports multiple editors and each workspace can use its own editor. In the Here is the expected format of a [`che-editors.yaml`](./che-editors.yaml) editor entry: ```yaml - - id: my/editor/1.0.0 - title: This is my editor - displayName: Editor Name - description: Run Editor Foo on top of Eclipse Che - icon: http://my-nice-icon.foobar/icon.png - repository: https://my-git-repository-foo-bar.com/ - firstPublicationDate: "2020-01-01" - endpoints: - - name: "editor-name" - public: true - targetPort: 8080 + - schemaVersion: 2.2.2 + metadata: + name: ws-skeleton/jupyter/5.7.0 + displayName: Jupyter Notebook + description: Jupyter Notebook for Eclipse Che + icon: /images/notebook.svg + attributes: + publisher: ws-skeleton + version: 5.7.0 + title: Jupyter Notebook for Eclipse Che + repository: 'https://github.com/ws-skeleton/che-editor-jupyter/' + firstPublicationDate: '2019-02-05' + components: + - name: jupyter-notebook + container: + image: "docker.io/ksmster/che-editor-jupyter:5.7.0" + env: + - name: JUPYTER_NOTEBOOK_DIR + value: /projects + mountSources: true + memoryLimit: 512M + endpoints: + - name: jupyter + targetPort: 8888 + exposure: public + protocol: https + attributes: + type: main attributes: - protocol: http - type: main - containers: - - name: my-editor-container - image: "quay.io/image:foo" - mountSources: true - ports: - - exposedPort: 8080 - memoryLimit: "512M" + ports: + - exposedPort: 8888 ``` Here are all the supported values, including optional ones: ```yaml - # The ID of the editor - - id: my/editor/1.0.0 + # Version of the devile schema + - schemaVersion: 2.2.2 # Meta information of the editor - title: This is my editor - displayName: Editor Name - description: Run Editor Foo on top of Eclipse Che - icon: http://my-nice-icon.foobar/icon.png - firstPublicationDate: "2020-01-01" - # Repository information about the editor. - repository: https://my-git-repository-foo-bar.com/ - # Specify at least one endpoint - endpoints: - - # Name of the editor - name: "editor-name" - # public - public: true - # listening port of the editor in the container - targetPort: 8080 - # the type should be ide to be an editor + metadata: + # The name of the editor. It should include publisher, name and version of the editor + name: publisher/name/version + displayName: Editor Name + description: Run Editor Foo on top of Eclipse Che + # Editor's icon. The icon should be located in /images folder. + icon: /images/editor_icon.svg + # (OPTIONAL) Additional attributes + attributes: + title: This is my editor + publisher: publisher + version: version + repository: https://github.com/editor/repository/ + firstPublicationDate: '2024-01-01' + # List of editor components + components: + # Name of the component + - name: che-code-injector + # Configuration of devworkspace-related container + container: + # Image of the container + image: 'quay.io/che-incubator/che-code:insiders' + # The command to run in the dockerimage component instead of the default one provided in the image + command: + - /entrypoint-init-container.sh + # (OPTIONAL) List of volumes mounts that should be mounted in this container + volumeMounts: + # The name of the mount + - name: checode + # The path of the mount + path: /checode + # (OPTIONAL) The memory limit of the container + memoryLimit: 256Mi + # (OPTIONAL) The memory request of the container + memoryRequest: 32Mi + # (OPTIONAL) The CPU limit of the container + cpuLimit: 500m + # (OPTIONAL) The CPU request of the container + cpuRequest: 30m + # Name of the component + - name: che-code-runtime-description + # (OPTIONAL) Map of implementation-dependant free-form YAML attributes attributes: - protocol: http - type: main - # Specify at least one container - containers: - - # Name of the container - name: my-editor-container - # image of the container - image: "quay.io/image:foo" - # (OPTIONAL) Any environment variable entry for the container - env: - # The name of the environment variable - - name: MY_KEY - # The value of the environment variable - value: my-value - # (OPTIONAL) mount the source code of the projects in the container - # Should be true for the editor's container as usually editor is to open files from projects - mountSources: true - # (OPTIONAL) ports exposed by this container - ports: - - - # Should at least expose the port used by the default endpoint - exposedPort: 8080 - # (OPTIONAL) The memory limit of the container - memoryLimit: "1500Mi" - # (OPTIONAL) The memory request of the container - memoryRequest: "1000Mi" - # (OPTIONAL) The CPU limit of the container - cpuLimit: "500m" - # (OPTIONAL) The CPU request of the container - cpuRequest: "125m" - # (OPTIONAL) Any volume mounting information for the container - volumeMounts: - # The name of the mount - - name: m2 - # The path of the mount - path: "/home/user/.m2" - - # (OPTIONAL) Any init container - initContainers: - - # Name of the container - name: my-editor-container - # image of the container - image: "quay.io/image:foo" - # (OPTIONAL) Any environment variable entry for the container - env: - # The name of the environment variable - - name: MY_KEY - # The value of the environment variable - value: my-value - # (OPTIONAL) Any volume mounting information for the container - volumeMounts: - # The name of the mount - - name: my-path - # The path of the mount - path: "/home/user/path" + app.kubernetes.io/component: che-code-runtime + app.kubernetes.io/part-of: che-code.eclipse.org + # Defines a container component as a "container contribution". If a flattened DevWorkspace has a container component with the merge-contribution attribute, then any container contributions are merged into that container component + controller.devfile.io/container-contribution: true + container: + # Can be dummy image because the compoent is expected to be injected into workspace dev component + image: quay.io/devfile/universal-developer-image:latest + # (OPTIONAL) List of volumes mounts that should be mounted in this container + volumeMounts: + # The name of the mount + - name: checode + # (OPTIONAL) The path in the component container where the volume should be mounted. If not path is mentioned, default path is the is / + path: /checode + # (OPTIONAL) The memory limit of the container + memoryLimit: 1024Mi + # (OPTIONAL) The memory request of the container + memoryRequest: 256Mi + # (OPTIONAL) The CPU limit of the container + cpuLimit: 500m + # (OPTIONAL) The CPU request of the container + cpuRequest: 30m + # (OPTIONAL) Environment variables used in this container + env: + - name: ENV_NAME + value: value + # Component endpoints + endpoints: + # Name of the editor + - name: che-code + # (OPTIONAL) Map of implementation-dependant string-based free-form attributes + attributes: + # Type of the endpoint + type: main + cookiesAuthEnabled: true + discoverable: false + urlRewriteSupported: true + # Port number to be used within the container component + targetPort: 3100 + # (OPTIONAL) Describes how the endpoint should be exposed on the network (public, internal, none) + exposure: public + # (OPTIONAL) Describes whether the endpoint should be secured and protected by some authentication process + secure: true + # (OPTIONAL) Describes the application and transport protocols of the traffic that will go through this endpoint + protocol: https + # Mandatory name that allows referencing the component from other elements + - name: checode + # (OPTIONAL) Allows specifying the definition of a volume shared by several other components. Ephemeral volumes are not stored persistently across restarts. Defaults to false + volume: {ephemeral: true} + # (OPTIONAL) Bindings of commands to events. Each command is referred-to by its name + events: + # IDs of commands that should be executed before the devworkspace start. This commands would typically be executed in init container + preStart: + - init-container-command + # IDs of commands that should be executed after the devworkspace is completely started. In the case of Che-Theia, these commands should be executed after all plugins and extensions have started, including project cloning. This means that those commands are not triggered until the user opens the IDE in his browser + postStart: + - init-che-code-command + # (OPTIONAL) Predefined, ready-to-use, devworkspace-related commands + commands: + # Mandatory identifier that allows referencing this command + - id: init-container-command + apply: + # Describes component to which given action relates + component: che-code-injector + # Mandatory identifier that allows referencing this command + - id: init-che-code-command + # CLI Command executed in an existing component container + exec: + # Describes component to which given action relates + component: che-code-runtime-description + # The actual command-line string + commandLine: 'nohup /checode/entrypoint-volume.sh > /checode/entrypoint-logs.txt + 2>&1 &' ``` +To run the workspace using a new editor you need to build a link: +`https:///#?che-editor=`. Where: +- `che-host` is an Eclipse Che instance like `https://che-dogfooding.apps.che-dev.x6e0.p1.openshiftapps.com` +- `git-repo` is a repository with a project that should be cloned into the workspace +- `editor-definition-raw-url` is an URL to the raw content of your editor definition + ## Registry Publishing ### Pull Requests All PRs in the plugin registry are published to [surge.sh](https://surge.sh/), for ease of testing. This means that a CI job will automatically build the plugin registry with a PR's changes, and publish it. The resulting link can then be used to test the PR inside Che, without needing to create a `devfile.yaml` file. @@ -145,6 +204,8 @@ For example, build of PR 805 would be hosted at: https://pr-check-805-che-plugin ### Next A next build of the plugin registry is published on both [surge.sh](https://che-plugin-registry.surge.sh/), and [GitHub Pages](https://eclipse-che.github.io/che-plugin-registry/main/). Both are updated upon every commit merged to the main branch. +The editor definition can be found by URL: `https://pr-check--che-plugin-registry.surge.sh/v3/plugins////devfile.yaml` + ### Versioned Releases Versioned releases of the che-plugin-registry are also published to GitHub Pages. The version of the release is name of the last folder in the URL. From aa29295517f7a64a2518ec413a9fefa2adc55721 Mon Sep 17 00:00:00 2001 From: Valeriy Svydenko Date: Wed, 6 Mar 2024 11:08:20 +0200 Subject: [PATCH 2/4] add more comments Signed-off-by: Valeriy Svydenko --- CONTRIBUTE.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md index 21f2a895a..f6ee84119 100644 --- a/CONTRIBUTE.md +++ b/CONTRIBUTE.md @@ -113,7 +113,9 @@ Here are all the supported values, including optional ones: - name: che-code-runtime-description # (OPTIONAL) Map of implementation-dependant free-form YAML attributes attributes: + # The component within the architecture app.kubernetes.io/component: che-code-runtime + # The name of a higher level application this one is part of app.kubernetes.io/part-of: che-code.eclipse.org # Defines a container component as a "container contribution". If a flattened DevWorkspace has a container component with the merge-contribution attribute, then any container contributions are merged into that container component controller.devfile.io/container-contribution: true @@ -144,10 +146,13 @@ Here are all the supported values, including optional ones: - name: che-code # (OPTIONAL) Map of implementation-dependant string-based free-form attributes attributes: - # Type of the endpoint + # Type of the endpoint. It only allows for it's value to be set to main which indicates that the endpoint should be used as the mainUrl in the workspace status (i.e. it should be the URL used to access the editor in this context) type: main + # An attribute that instructs the service to automatically redirect the unauthenticated requests for current user authentication. Setting this attribute to true has security consequences because it makes Cross-site request forgery (CSRF) attacks possible. The default value of the attribute is false. cookiesAuthEnabled: true + # Defines an endpoint as "discoverable", meaning that a service should be created using the endpoint name (i.e. instead of generating a service name for all endpoints, this endpoint should be statically accessible) discoverable: false + # Used to secure the endpoint with authorization on OpenShift, so that not anyone on the cluster can access the endpoint, the attribute enables authentication. urlRewriteSupported: true # Port number to be used within the container component targetPort: 3100 @@ -187,7 +192,7 @@ Here are all the supported values, including optional ones: 2>&1 &' ``` -To run the workspace using a new editor you need to build a link: +To run a workspace using a new editor you need to build a link: `https:///#?che-editor=`. Where: - `che-host` is an Eclipse Che instance like `https://che-dogfooding.apps.che-dev.x6e0.p1.openshiftapps.com` - `git-repo` is a repository with a project that should be cloned into the workspace From 10b100d2f27d6906628054857842c015fb5999ab Mon Sep 17 00:00:00 2001 From: Valeriy Svydenko Date: Wed, 6 Mar 2024 17:56:25 +0200 Subject: [PATCH 3/4] address comments Signed-off-by: Valeriy Svydenko --- CONTRIBUTE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md index f6ee84119..7dbd7a8d5 100644 --- a/CONTRIBUTE.md +++ b/CONTRIBUTE.md @@ -171,7 +171,7 @@ Here are all the supported values, including optional ones: # IDs of commands that should be executed before the devworkspace start. This commands would typically be executed in init container preStart: - init-container-command - # IDs of commands that should be executed after the devworkspace is completely started. In the case of Che-Theia, these commands should be executed after all plugins and extensions have started, including project cloning. This means that those commands are not triggered until the user opens the IDE in his browser + # IDs of commands that should be executed after the devworkspace is completely started. In the case of Che-Code, these commands should be executed after all plugins and extensions have started, including project cloning. This means that those commands are not triggered until the user opens the IDE in his browser postStart: - init-che-code-command # (OPTIONAL) Predefined, ready-to-use, devworkspace-related commands @@ -194,7 +194,7 @@ Here are all the supported values, including optional ones: To run a workspace using a new editor you need to build a link: `https:///#?che-editor=`. Where: -- `che-host` is an Eclipse Che instance like `https://che-dogfooding.apps.che-dev.x6e0.p1.openshiftapps.com` +- `che-host` is an Eclipse Che instance like `https://devspaces.apps.sandbox-stage.gb17.p1.openshiftapps.com/` - `git-repo` is a repository with a project that should be cloned into the workspace - `editor-definition-raw-url` is an URL to the raw content of your editor definition From fb4cf2d7dbdd8a25cd6e60bff73c6b1f323ed8d9 Mon Sep 17 00:00:00 2001 From: Valeriy Svydenko Date: Wed, 6 Mar 2024 17:59:51 +0200 Subject: [PATCH 4/4] address comments Signed-off-by: Valeriy Svydenko --- CONTRIBUTE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md index 7dbd7a8d5..cf809314d 100644 --- a/CONTRIBUTE.md +++ b/CONTRIBUTE.md @@ -194,7 +194,7 @@ Here are all the supported values, including optional ones: To run a workspace using a new editor you need to build a link: `https:///#?che-editor=`. Where: -- `che-host` is an Eclipse Che instance like `https://devspaces.apps.sandbox-stage.gb17.p1.openshiftapps.com/` +- `che-host` is an Eclipse Che instance like `https://devspaces.apps.sandbox-m4.g2pi.p1.openshiftapps.com/` - `git-repo` is a repository with a project that should be cloned into the workspace - `editor-definition-raw-url` is an URL to the raw content of your editor definition