diff --git a/modules/administration-guide/examples/che-build-the-devfile-registry.adoc b/modules/administration-guide/examples/che-build-the-devfile-registry.adoc deleted file mode 100644 index 54c977ee3c..0000000000 --- a/modules/administration-guide/examples/che-build-the-devfile-registry.adoc +++ /dev/null @@ -1 +0,0 @@ -$ docker build -t my-devfile-registry . diff --git a/modules/administration-guide/examples/che-clone-the-devfile-registry-repository.adoc b/modules/administration-guide/examples/che-clone-the-devfile-registry-repository.adoc deleted file mode 100644 index 86b9068c3d..0000000000 --- a/modules/administration-guide/examples/che-clone-the-devfile-registry-repository.adoc +++ /dev/null @@ -1,2 +0,0 @@ -$ git clone git@github.com:eclipse/che-devfile-registry.git -$ cd che-devfile-registry diff --git a/modules/administration-guide/examples/che-clone-the-plug-in-registry-repository.adoc b/modules/administration-guide/examples/che-clone-the-plug-in-registry-repository.adoc deleted file mode 100644 index 4d481091f9..0000000000 --- a/modules/administration-guide/examples/che-clone-the-plug-in-registry-repository.adoc +++ /dev/null @@ -1,2 +0,0 @@ -$ git clone git@github.com:eclipse/che-plugin-registry.git -$ cd che-plugin-registry diff --git a/modules/administration-guide/examples/proc_che-including-the-plug-in-binaries-in-the-registry-image.adoc b/modules/administration-guide/examples/proc_che-including-the-plug-in-binaries-in-the-registry-image.adoc deleted file mode 100644 index b572eace03..0000000000 --- a/modules/administration-guide/examples/proc_che-including-the-plug-in-binaries-in-the-registry-image.adoc +++ /dev/null @@ -1,92 +0,0 @@ -The plug-in registry only hosts {prod-short} plug-in metadata. The binaries are usually referred through a link in the `meta.yaml` file. In some cases, such as in offline environments, it may be necessary to make the binaries available inside the registry image. - -This section describes how to modify a plug-in `meta.yaml` file to point to a local file inside the container and build a new registry that contains the modified plug-in `meta.yaml` file and the plug-in binary file. In the following example, the Java plug-in that refers to two remote VS Code extensions binaries is considered. - -.Prerequisites - -* An instance of {prod-short} is available. -* The `oc` tool is available. - -.Procedure - -. Clone the `che-plugin-registry` repository: -+ ----- -$ git clone https://github.com/eclipse/che-plugin-registry -$ cd che-plugin-registry ----- - -. Identify the binaries you wish to host locally in the custom plug-in registry. -+ -The `meta.yaml` file includes the `extension` section, which defines the URLs of required extensions for the plug-in. For example, the `redhat/java11/0.63.0` plug-in lists the following two extensions: -+ -.meta.yaml -[source,yaml] ----- -extensions: - - https://download.jboss.org/jbosstools/vscode/3rdparty/vscode-java-debug/vscode-java-debug-0.26.0.vsix - - https://download.jboss.org/jbosstools/static/jdt.ls/stable/java-0.63.0-2222.vsix ----- -+ -Download these two extensions and host them in the plug-in-registry. When using the `redhat/java11/0.63.0` plug-in, the binary will be fetched from the custom plug-in-registry server. Set the following environment variables to help with the subsequent commands: -+ ----- -ORG=redhat -NAME=java11 -CHE_PLUGIN_VERSION=0.63.0 -VSCODE_JAVA_DEBUG_VERSION=0.26.0 -VSCODE_JAVA_DEBUG_URL="https://download.jboss.org/jbosstools/vscode/3rdparty/vscode-java-debug/vscode-java-debug-0.26.0.vsix" -VSCODE_JAVA_DEBUG_BINARY_NAME="vscode-java-debug-0.26.0.vsix" -JAVA_LS_VERSION=0.63.0-2222 -JAVA_LS_URL="https://download.jboss.org/jbosstools/static/jdt.ls/stable/java-0.63.0-2222.vsix" -JAVA_LS_BINARY_NAME="java-0.63.0-2222.vsix" -OLD_JAVA_DEBUG_META_YAML_URL="https://download.jboss.org/jbosstools/vscode/3rdparty/vscode-java-debug/vscode-java-debug-0.26.0.vsix" -OLD_JAVA_LS_META_YAML_URL="https://download.jboss.org/jbosstools/static/jdt.ls/stable/java-0.63.0-2222.vsix" ----- - -. Download the binaries locally: -+ ----- -$ curl -sSL -o ./v3/plugins/${ORG}/${NAME}/${CHE_PLUGIN_VERSION}/${VSCODE_JAVA_DEBUG_BINARY_NAME} \ - ${VSCODE_JAVA_DEBUG_URL} -$ curl -sSL -o ./v3/plugins/${ORG}/${NAME}/${CHE_PLUGIN_VERSION}/${JAVA_LS_BINARY_NAME} \ - ${JAVA_LS_URL} ----- - -. Get the plug-in registry URL: -+ -[subs="+quotes,+attributes"] ----- -$ {orch-cli} get route plugin-registry -o jsonpath='\{.spec.host}' -n $\{CHE_NAMESPACE} ----- -+ -Save this value in a variable called `PLUGIN_REGISTRY_URL`. - -. Update the URLs in the `meta.yaml` file to point to the VS Code extension binaries that are saved in the registry container: -+ -IMPORTANT: By default, {prod-short} is deployed with TLS enabled. For installations that do not use TLS, use `http://` in the `NEW_JAVA_DEBUG_URL` and `NEW_JAVA_LS_URL` variables. -+ ----- -NEW_JAVA_DEBUG_URL=https://${PLUGIN_REGISTRY_URL}/v3/plugins/${ORG}/${NAME}/${CHE_PLUGIN_VERSION}/${VSCODE_JAVA_DEBUG_BINARY_NAME} -NEW_JAVA_LS_URL=https://${PLUGIN_REGISTRY_URL}/v3/plugins/${ORG}/${NAME}/${CHE_PLUGIN_VERSION}/${JAVA_LS_BINARY_NAME} -$ sed -i -e "s#${OLD_JAVA_DEBUG_META_YAML_URL}#${NEW_JAVA_DEBUG_URL}#g" \ - ./v3/plugins/${ORG}/${NAME}/${CHE_PLUGIN_VERSION}/meta.yaml -$ sed -i -e "s#${OLD_JAVA_LS_META_YAML_URL}#${NEW_JAVA_LS_URL}#g" \ - ./v3/plugins/${ORG}/${NAME}/${CHE_PLUGIN_VERSION}/meta.yaml ----- - -. Confirm that the `meta.yaml` has the correctly substituted the URLs: -+ ----- -$ cat ./v3/plugins/${ORG}/${NAME}/${CHE_PLUGIN_VERSION}/meta.yaml ----- -+ -.meta.yaml -[source,yaml] ----- -extensions: - - https://plugin-registry-che.apps-crc.testing/v3/plugins/redhat/java11/0.63.0/vscode-java-debug-0.26.0.vsix - - https://plugin-registry-che.apps-crc.testing/v3/plugins/redhat/java11/0.63.0/java-0.63.0-2222.vsix ----- - -. Build and deploy the plug-in registry using the instructions in the xref:building-and-running-a-custom-registry-image.adoc[] section. diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index 07ac030232..bb6ccefa3a 100644 --- a/modules/administration-guide/nav.adoc +++ b/modules/administration-guide/nav.adoc @@ -4,12 +4,6 @@ ** xref:che-workspace-controller.adoc[] ** xref:che-workspaces-architecture.adoc[] * xref:calculating-che-resource-requirements.adoc[] -* xref:customizing-the-devfile-and-plug-in-registries.adoc[] -** xref:building-and-running-a-custom-registry-image.adoc[] -** xref:including-the-plug-in-binaries-in-the-registry-image.adoc[] -** xref:editing-a-devfile-and-plug-in-at-runtime.adoc[] -** xref:using-a-visual-studio-code-extension-in-che.adoc[] -** xref:testing-a-visual-studio-code-extension-in-che.adoc[] * xref:retrieving-che-logs.adoc[] ** xref:viewing-kubernetes-events.adoc[] ** xref:viewing-operator-events.adoc[] diff --git a/modules/administration-guide/pages/building-and-running-a-custom-registry-image.adoc b/modules/administration-guide/pages/building-and-running-a-custom-registry-image.adoc deleted file mode 100644 index cae0e892a6..0000000000 --- a/modules/administration-guide/pages/building-and-running-a-custom-registry-image.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="building-and-running-a-custom-registry-image"] -// = Building and running a custom registry image -:navtitle: Building and running a custom registry image -:keywords: administration-guide, building-and-running-a-custom-registry-image -:page-aliases: .:building-and-running-a-custom-registry-image - -include::partial$assembly_building-and-running-a-custom-registry-image.adoc[] diff --git a/modules/administration-guide/pages/customizing-the-devfile-and-plug-in-registries.adoc b/modules/administration-guide/pages/customizing-the-devfile-and-plug-in-registries.adoc deleted file mode 100644 index 03986135cd..0000000000 --- a/modules/administration-guide/pages/customizing-the-devfile-and-plug-in-registries.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="customizing-the-devfile-and-plug-in-registries"] -// = Customizing devfile and plug-in registries -:navtitle: Customizing devfile and plug-in registries -:keywords: administration-guide, customizing-the-devfile-and-plug-in-registries -:page-aliases: .:customizing-the-devfile-and-plug-in-registries - -include::partial$assembly_customizing-the-devfile-and-plug-in-registries.adoc[] diff --git a/modules/administration-guide/pages/including-the-plug-in-binaries-in-the-registry-image.adoc b/modules/administration-guide/pages/including-the-plug-in-binaries-in-the-registry-image.adoc deleted file mode 100644 index dbc9f0a262..0000000000 --- a/modules/administration-guide/pages/including-the-plug-in-binaries-in-the-registry-image.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="including-the-plug-in-binaries-in-the-registry-image"] -// = Including the plug-in binaries in the registry image -:navtitle: Including the plug-in binaries in the registry image -:keywords: administration-guide, including-the-plug-in-binaries-in-the-registry-image -:page-aliases: .:including-the-plug-in-binaries-in-the-registry-image - -include::partial$proc_including-the-plug-in-binaries-in-the-registry-image.adoc[] diff --git a/modules/administration-guide/pages/using-a-visual-studio-code-extension-in-che.adoc b/modules/administration-guide/pages/using-a-visual-studio-code-extension-in-che.adoc deleted file mode 100644 index e31d424f69..0000000000 --- a/modules/administration-guide/pages/using-a-visual-studio-code-extension-in-che.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="using-a-visual-studio-code-extension-in-che"] -// = Using a VS Code extension in Che -:navtitle: Using a VS Code extension in Che -:keywords: administration-guide, using-a-visual-studio-code-extension-in-che -:page-aliases: .:using-a-visual-studio-code-extension-in-che - -include::partial$assembly_using-a-visual-studio-code-extension-in-che.adoc[] diff --git a/modules/administration-guide/partials/assembly_customizing-the-devfile-and-plug-in-registries.adoc b/modules/administration-guide/partials/assembly_customizing-the-devfile-and-plug-in-registries.adoc deleted file mode 100644 index eb93985371..0000000000 --- a/modules/administration-guide/partials/assembly_customizing-the-devfile-and-plug-in-registries.adoc +++ /dev/null @@ -1,27 +0,0 @@ - - -:parent-context-of-customizing-the-devfile-and-plug-in-registries: {context} - -[id="customizing-the-devfile-and-plug-in-registries_{context}"] -= Customizing the devfile and plug-in registries - -:context: customizing-the-devfile-and-plug-in-registries - -{prod-short} {prod-ver} introduces two registries: the plug-ins registry and the devfile registry. They are static websites where the metadata of {prod-short} plug-ins and {prod-short} devfiles is published. - -The plug-in registry makes it possible to share a plug-in definition across all the users of the same instance of {prod-short}. Only plug-ins that are published in a registry can be used in a devfile. - -The devfile registry holds the definitions of the {prod-short} stacks. Stacks are available on the {prod-short} user dashboard when selecting *Create Workspace*. It contains the list of {prod-short} technological stack samples with example projects. - -The devfile and plug-in registries run in two separate pods and are deployed when the {prod-short} server is deployed (that is the default behavior of the {prod-short} Operator). The metadata of the plug-ins and devfiles are versioned on GitHub and follow the {prod-short} server life cycle. - -In this document, the following two ways to customize the default registries that are deployed with {prod-short} (to modify the plug-ins or devfile metadata) are described: - -. Building a custom image of the registries -. Running the default images but modifying them at runtime - -* xref:building-and-running-a-custom-registry-image.adoc[] -* xref:including-the-plug-in-binaries-in-the-registry-image.adoc[] -* xref:editing-a-devfile-and-plug-in-at-runtime.adoc[] - -:context: {parent-context-of-customizing-the-devfile-and-plug-in-registries} diff --git a/modules/administration-guide/partials/assembly_publishing-a-vs-code-extension-into-the-che-plug-in-registry.adoc b/modules/administration-guide/partials/assembly_publishing-a-vs-code-extension-into-the-che-plug-in-registry.adoc deleted file mode 100644 index e821e1a836..0000000000 --- a/modules/administration-guide/partials/assembly_publishing-a-vs-code-extension-into-the-che-plug-in-registry.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// using-a-visual-studio-code-extension-in-{prod-id-short} - -:parent-context-of-publishing-a-vs-code-extension-into-the-che-plug-in-registry: {context} - -[id="publishing-a-vs-code-extension-into-the-{prod-id-short}-plug-in-registry_{context}"] -= Publishing a VS Code extension into the {prod-short} plug-in registry - -:context: publishing-a-vs-code-extension-into-the-{prod-id-short}-plug-in-registry - -The user of {prod-short} can use a workspace devfile to use any plug-in, also known as Visual Studio Code (VS Code) extension. This plug-in can be added to the plug-in registry, then easily reused by anyone in the same organization with access to that workspaces installation. - -Some plug-ins need a runtime dedicated container for code compilation. This fact makes those plug-ins a combination of a runtime sidecar container and a VS Code extension. - -The following section describes the portability of a plug-in configuration and associating an extension with a runtime container that the plug-in needs. - -include::partial$proc_writing-a-meta-yaml-file-and-adding-it-to-a-plug-in-registry.adoc[leveloffset=+1] - -// TODO: remove this condition when the downstream counterpart is fixed - currently commented out -ifeval::["{project-context}" == "che"] -.Additional resources -To set up a custom plug-in registry, see: {link-building-a-custom-plug-in-registry}. -endif::[] - -:context: {parent-context-of-publishing-a-vs-code-extension-into-the-che-plug-in-registry} diff --git a/modules/administration-guide/partials/proc_including-the-plug-in-binaries-in-the-registry-image.adoc b/modules/administration-guide/partials/proc_including-the-plug-in-binaries-in-the-registry-image.adoc deleted file mode 100644 index b79d34624f..0000000000 --- a/modules/administration-guide/partials/proc_including-the-plug-in-binaries-in-the-registry-image.adoc +++ /dev/null @@ -1,12 +0,0 @@ - - -:parent-context-of-including-the-plug-in-binaries-in-the-registry-image: {context} - -[id="including-the-plug-in-binaries-in-the-registry-image_{context}"] -= Including the plug-in binaries in the registry image - -:context: including-the-plug-in-binaries-in-the-registry-image - -include::example$proc_{project-context}-including-the-plug-in-binaries-in-the-registry-image.adoc[leveloffset+=1] - -:context: {parent-context-of-including-the-plug-in-binaries-in-the-registry-image} diff --git a/modules/administration-guide/examples/che-devfile-meta.adoc b/modules/contributor-guide/examples/che-devfile-meta.adoc similarity index 100% rename from modules/administration-guide/examples/che-devfile-meta.adoc rename to modules/contributor-guide/examples/che-devfile-meta.adoc diff --git a/modules/administration-guide/partials/proc_building-a-custom-devfile-registry.adoc b/modules/contributor-guide/examples/snip_customizing-the-devfile-registry.adoc similarity index 65% rename from modules/administration-guide/partials/proc_building-a-custom-devfile-registry.adoc rename to modules/contributor-guide/examples/snip_customizing-the-devfile-registry.adoc index 75f27b3de6..54c09c2f1c 100644 --- a/modules/administration-guide/partials/proc_building-a-custom-devfile-registry.adoc +++ b/modules/contributor-guide/examples/snip_customizing-the-devfile-registry.adoc @@ -1,22 +1,3 @@ -// building-and-running-a-custom-registry-image - -[id="building-a-custom-devfile-registry_{context}"] -= Building a custom devfile registry - -This section describes how to build a custom devfiles registry. Following operations are covered: - -* Getting a copy of the source code necessary to build a devfiles registry. -* Adding a new devfile. -* Building the devfiles registry. - -.Procedure - -. Clone the devfile registry repository: -+ ----- -include::example${project-context}-clone-the-devfile-registry-repository.adoc[] ----- - . In the `./che-devfile-registry/devfiles/` directory, create a subdirectory `____/` and add the `devfile.yaml` and `meta.yaml` files. + .File organization for a devfile @@ -47,10 +28,4 @@ tags, List of tags. Tags usually include the tools included in the stack. [source,yaml] ---- include::example${project-context}-devfile-meta.adoc[] ----- - -. Build the containers for the custom devfile registry: -+ ----- -include::example${project-context}-build-the-devfile-registry.adoc[] ----- +---- \ No newline at end of file diff --git a/modules/administration-guide/partials/proc_building-a-custom-plug-in-registry.adoc b/modules/contributor-guide/examples/snip_customizing-the-plug-in-registry.adoc similarity index 57% rename from modules/administration-guide/partials/proc_building-a-custom-plug-in-registry.adoc rename to modules/contributor-guide/examples/snip_customizing-the-plug-in-registry.adoc index d30793430b..1af9a53949 100644 --- a/modules/administration-guide/partials/proc_building-a-custom-plug-in-registry.adoc +++ b/modules/contributor-guide/examples/snip_customizing-the-plug-in-registry.adoc @@ -1,23 +1,4 @@ -// building-and-running-a-custom-registry-image - -[id="building-a-custom-plug-in-registry_{context}"] -= Building a custom plug-in registry - -This section describes how to build a custom plug-in registry. Following operations are covered: - -* Getting a copy of the source code necessary to build a custom plug-in registry. -* Adding a new plug-in. -* Building the custom plug-in registry. - -.Procedure - -. Clone the plug-in registry repository: -+ ----- -include::example${project-context}-clone-the-plug-in-registry-repository.adoc[] ----- - -. In the `./che-plugin-registry/v3/plugins/` directory, create new directories `____/____/____/` and a `meta.yaml` file in the last directory. + . In the `./che-plugin-registry/v3/plugins/` directory, create new directories `____/____/____/` and a `meta.yaml` file in the last directory. + .File organization for a plugin [subs="+quotes"] @@ -56,9 +37,3 @@ $ cat che-plugin-registry/v3/plugins/redhat/java/latest.txt ---- ==== -. Build the containers for the custom plug-in registry: -+ -[source,shell] ----- -$ ./build.sh ----- diff --git a/modules/administration-guide/images/customization/che-deploying-plugin-registry-in-kubernetes.png b/modules/contributor-guide/images/customization/che-deploying-plugin-registry-in-kubernetes.png similarity index 100% rename from modules/administration-guide/images/customization/che-deploying-plugin-registry-in-kubernetes.png rename to modules/contributor-guide/images/customization/che-deploying-plugin-registry-in-kubernetes.png diff --git a/modules/administration-guide/images/customization/deploying-devfile-registry-in-kubernetes.png b/modules/contributor-guide/images/customization/deploying-devfile-registry-in-kubernetes.png similarity index 100% rename from modules/administration-guide/images/customization/deploying-devfile-registry-in-kubernetes.png rename to modules/contributor-guide/images/customization/deploying-devfile-registry-in-kubernetes.png diff --git a/modules/contributor-guide/nav.adoc b/modules/contributor-guide/nav.adoc index 801eead1c9..b3e5f81051 100644 --- a/modules/contributor-guide/nav.adoc +++ b/modules/contributor-guide/nav.adoc @@ -1,5 +1,9 @@ .Contributor Guide - +* xref:customizing-the-devfile-and-plug-in-registries.adoc[] +** xref:building-a-custom-devfile-registry.adoc[] +** xref:building-a-custom-plug-in-registry.adoc[] +** xref:running-custom-registries.adoc[] +** xref:testing-a-visual-studio-code-extension-in-che.adoc[] * xref:branding-che-theia.adoc[] * xref:developing-che-theia-plug-ins.adoc[] * xref:testing-che-theia-plug-ins.adoc[] diff --git a/modules/contributor-guide/pages/building-a-custom-devfile-registry.adoc b/modules/contributor-guide/pages/building-a-custom-devfile-registry.adoc new file mode 100644 index 0000000000..9819f642a8 --- /dev/null +++ b/modules/contributor-guide/pages/building-a-custom-devfile-registry.adoc @@ -0,0 +1,13 @@ +[id="building-and-running-a-custom-devfile-registry-image"] +// = Customizing the devfile registry +:navtitle: Building custom devfile registry +:keywords: contributor-guide, customizing-the-devfile-and-plug-in-registries, building-and-running-a-custom-devfile-registry-image +:page-aliases: .:building-and-running-a-custom-devfile-registry-image + +:registry-mode: custom +:registry-mode-name: a custom +:registry-id: devfile +:registry-name: devfile + +include::installation-guide:example$proc_{project-context}-building-a-registry-image.adoc[] + diff --git a/modules/contributor-guide/pages/building-a-custom-plug-in-registry.adoc b/modules/contributor-guide/pages/building-a-custom-plug-in-registry.adoc new file mode 100644 index 0000000000..30affa1adf --- /dev/null +++ b/modules/contributor-guide/pages/building-a-custom-plug-in-registry.adoc @@ -0,0 +1,13 @@ +[id="customizing-the-plug-in-registry"] +// = Customizing the plug-in registry +:navtitle: Building custom plug-in registry +:keywords: contributor-guide, customizing-the-plug-in-registry, including-the-plug-in-binaries-in-the-registry-image, building-and-running-a-custom-in-registry-image +:page-aliases: .:building-and-running-a-custom-plug-in-registry-image, administration-guide:including-the-plug-in-binaries-in-the-registry-image + +:registry-mode: custom +:registry-mode-name: a custom +:registry-id: plugin +:registry-name: plug-in + +include::installation-guide:example$proc_{project-context}-building-a-registry-image.adoc[] + diff --git a/modules/contributor-guide/pages/customizing-the-devfile-and-plug-in-registries.adoc b/modules/contributor-guide/pages/customizing-the-devfile-and-plug-in-registries.adoc new file mode 100644 index 0000000000..c9604a9ab6 --- /dev/null +++ b/modules/contributor-guide/pages/customizing-the-devfile-and-plug-in-registries.adoc @@ -0,0 +1,7 @@ +[id="customizing-the-devfile-and-plug-in-registries"] +// = Customizing devfile and plug-in registries +:navtitle: Customizing the registries +:keywords: contributor-guide, customizing-the-devfile-and-plug-in-registries, including-the-plug-in-binaries-in-the-registry-image +:page-aliases: .:customizing-the-devfile-and-plug-in-registries, administration-guide:customizing-the-devfile-and-plug-in-registries, administration-guide:building-and-running-a-custom-registry-image + +include::partial$assembly_customizing-the-registries.adoc[] diff --git a/modules/contributor-guide/pages/running-custom-registries.adoc b/modules/contributor-guide/pages/running-custom-registries.adoc new file mode 100644 index 0000000000..9fb66aad20 --- /dev/null +++ b/modules/contributor-guide/pages/running-custom-registries.adoc @@ -0,0 +1,13 @@ +[id="running-custom-registries"] +// = Running custom registries +:navtitle: Running custom registries +:keywords: contributor-guide, running-custom-registries +:page-aliases: .:running-custom-registries, + +:registry-mode: custom +:registry-mode-name: a custom +:registry-id: plugin +:registry-name: plug-in + +include::partial$assembly_deploying-the-registries.adoc[] + diff --git a/modules/administration-guide/pages/testing-a-visual-studio-code-extension-in-che.adoc b/modules/contributor-guide/pages/testing-a-visual-studio-code-extension-in-che.adoc similarity index 51% rename from modules/administration-guide/pages/testing-a-visual-studio-code-extension-in-che.adoc rename to modules/contributor-guide/pages/testing-a-visual-studio-code-extension-in-che.adoc index 5d74f5969f..9c73da7fc4 100644 --- a/modules/administration-guide/pages/testing-a-visual-studio-code-extension-in-che.adoc +++ b/modules/contributor-guide/pages/testing-a-visual-studio-code-extension-in-che.adoc @@ -1,7 +1,7 @@ [id="testing-a-visual-studio-code-extension-in-che"] // = Testing a VS Code extension in Che :navtitle: Testing a VS Code extension in Che -:keywords: administration-guide, testing-a-visual-studio-code-extension-in-che -:page-aliases: .:testing-a-visual-studio-code-extension-in-che +:keywords: contributor-guide, testing-a-visual-studio-code-extension-in-che +:page-aliases: .:testing-a-visual-studio-code-extension-in-che, administration-guide:testing-a-visual-studio-code-extension-in-che include::partial$assembly_testing-a-visual-studio-code-extension-in-che.adoc[] diff --git a/modules/administration-guide/partials/assembly_building-and-running-a-custom-registry-image.adoc b/modules/contributor-guide/partials/assembly_building-and-running-a-custom-registry-image.adoc similarity index 62% rename from modules/administration-guide/partials/assembly_building-and-running-a-custom-registry-image.adoc rename to modules/contributor-guide/partials/assembly_building-and-running-a-custom-registry-image.adoc index 612637428e..6ab3302e79 100644 --- a/modules/administration-guide/partials/assembly_building-and-running-a-custom-registry-image.adoc +++ b/modules/contributor-guide/partials/assembly_building-and-running-a-custom-registry-image.adoc @@ -11,9 +11,18 @@ This section describes the building of registries and updating a running {prod-s // include::partial$assembly_modifying-the-registries.adoc[leveloffset=+1] -include::partial$proc_building-a-custom-devfile-registry.adoc[leveloffset=+1] +:registry-mode: custom +:registry-mode-name: a custom +:registry-id: devfile +:registry-name: devfile + +include::installation-guide:example${project-context}-proc_building-a-registry-image.adoc[leveloffset=+1] + +:registry-id: plugin +:registry-name: plug-in + +include::installation-guide:example${project-context}-proc_building-a-registry-image.adoc[leveloffset=+1] -include::partial$proc_building-a-custom-plug-in-registry.adoc[leveloffset=+1] include::partial$assembly_deploying-the-registries.adoc[leveloffset=+1] diff --git a/modules/contributor-guide/partials/assembly_customizing-the-registries.adoc b/modules/contributor-guide/partials/assembly_customizing-the-registries.adoc new file mode 100644 index 0000000000..194f6acc7e --- /dev/null +++ b/modules/contributor-guide/partials/assembly_customizing-the-registries.adoc @@ -0,0 +1,25 @@ +:parent-context-of-customizing-the-devfile-and-plug-in-registries: {context} + +[id="customizing-the-registries_{context}"] += Customizing the registries + +:context: customizing-the-registries + +This chapter describes how to build and run custom registries for {prod-short}. + + +include::installation-guide:example$ref_{project-context}-understanding-the-registries.adoc[leveloffset=+1] + +.Additional resources + +* Building and running the registries: + +** xref:building-a-custom-devfile-registry.adoc[] +** xref:building-a-custom-plug-in-registry.adoc[] +** xref:running-custom-registries.adoc[] + +* In depth examples: + +** xref:testing-a-visual-studio-code-extension-in-che.adoc[] + +:context: {parent-context-of-customizing-the-devfile-and-plug-in-registries} diff --git a/modules/administration-guide/partials/assembly_deploying-the-registries.adoc b/modules/contributor-guide/partials/assembly_deploying-the-registries.adoc similarity index 100% rename from modules/administration-guide/partials/assembly_deploying-the-registries.adoc rename to modules/contributor-guide/partials/assembly_deploying-the-registries.adoc diff --git a/modules/administration-guide/partials/assembly_testing-a-visual-studio-code-extension-in-che.adoc b/modules/contributor-guide/partials/assembly_testing-a-visual-studio-code-extension-in-che.adoc similarity index 100% rename from modules/administration-guide/partials/assembly_testing-a-visual-studio-code-extension-in-che.adoc rename to modules/contributor-guide/partials/assembly_testing-a-visual-studio-code-extension-in-che.adoc diff --git a/modules/administration-guide/partials/assembly_using-a-visual-studio-code-extension-in-che.adoc b/modules/contributor-guide/partials/assembly_using-a-visual-studio-code-extension-in-che.adoc similarity index 100% rename from modules/administration-guide/partials/assembly_using-a-visual-studio-code-extension-in-che.adoc rename to modules/contributor-guide/partials/assembly_using-a-visual-studio-code-extension-in-che.adoc diff --git a/modules/administration-guide/partials/proc_deploying-registries-in-kubernetes.adoc b/modules/contributor-guide/partials/proc_deploying-registries-in-kubernetes.adoc similarity index 100% rename from modules/administration-guide/partials/proc_deploying-registries-in-kubernetes.adoc rename to modules/contributor-guide/partials/proc_deploying-registries-in-kubernetes.adoc diff --git a/modules/administration-guide/partials/proc_deploying-registries-in-openshift.adoc b/modules/contributor-guide/partials/proc_deploying-registries-in-openshift.adoc similarity index 100% rename from modules/administration-guide/partials/proc_deploying-registries-in-openshift.adoc rename to modules/contributor-guide/partials/proc_deploying-registries-in-openshift.adoc diff --git a/modules/administration-guide/partials/proc_testing-the-vs-code-extension-using-gist.adoc b/modules/contributor-guide/partials/proc_testing-the-vs-code-extension-using-gist.adoc similarity index 97% rename from modules/administration-guide/partials/proc_testing-the-vs-code-extension-using-gist.adoc rename to modules/contributor-guide/partials/proc_testing-the-vs-code-extension-using-gist.adoc index 652898395b..a2eb2ab274 100644 --- a/modules/administration-guide/partials/proc_testing-the-vs-code-extension-using-gist.adoc +++ b/modules/contributor-guide/partials/proc_testing-the-vs-code-extension-using-gist.adoc @@ -16,7 +16,7 @@ components: type: chePlugin ---- -To add a plug-in that is not in the default plug-in registry, build a custom plug-in registry. See xref:building-and-running-a-custom-registry-image.adoc#building-a-custom-plug-in-registry_{context}[], or, alternatively, use GitHub and the gist service. +To add a plug-in that is not in the default plug-in registry, build a custom plug-in registry. See xref:customizing-the-devfile-and-plug-in-registries.adoc[], or, alternatively, use GitHub and the gist service. .Prerequisites diff --git a/modules/administration-guide/partials/proc_verifying-the-vs-code-extension-api-compatibility-level.adoc b/modules/contributor-guide/partials/proc_verifying-the-vs-code-extension-api-compatibility-level.adoc similarity index 100% rename from modules/administration-guide/partials/proc_verifying-the-vs-code-extension-api-compatibility-level.adoc rename to modules/contributor-guide/partials/proc_verifying-the-vs-code-extension-api-compatibility-level.adoc diff --git a/modules/end-user-guide/nav.adoc b/modules/end-user-guide/nav.adoc index a4ef69025e..5307772738 100644 --- a/modules/end-user-guide/nav.adoc +++ b/modules/end-user-guide/nav.adoc @@ -20,8 +20,11 @@ ** xref:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container.adoc[] * xref:customizing-developer-environments.adoc[] ** xref:what-is-a-che-theia-plug-in.adoc[] +** xref:adding-a-vs-code-extension-to-a-workspace.adoc[] +** xref:publishing-metadata-for-a-vs-code-extension.adoc[] ** xref:using-alternative-ides-in-che.adoc[] ** xref:adding-tools-to-che-after-creating-a-workspace.adoc[] +** xref:editing-a-devfile-and-plug-in-at-runtime.adoc[] * xref:configuring-oauth-authorization.adoc[] ** xref:configuring-github-oauth.adoc[] ** xref:configuring-openshift-oauth.adoc[] diff --git a/modules/end-user-guide/pages/adding-a-vs-code-extension-to-a-workspace.adoc b/modules/end-user-guide/pages/adding-a-vs-code-extension-to-a-workspace.adoc new file mode 100644 index 0000000000..0fe42497ee --- /dev/null +++ b/modules/end-user-guide/pages/adding-a-vs-code-extension-to-a-workspace.adoc @@ -0,0 +1,7 @@ +[id="adding-a-vscode-extension-to-a-workspace"] +// = Adding tools to Che after creating a workspace +:navtitle: Adding a VSCode extension +:keywords: end-user-guide, adding-a-vscode-extension-to-a-workspace +:page-aliases: .:adding-a-vscode-extension-to-a-workspace, administration-guide:using-a-visual-studio-code-extension-in-che + +include::partial$assembly_adding-a-vs-code-extension-to-a-workspace.adoc[] diff --git a/modules/administration-guide/pages/editing-a-devfile-and-plug-in-at-runtime.adoc b/modules/end-user-guide/pages/editing-a-devfile-and-plug-in-at-runtime.adoc similarity index 53% rename from modules/administration-guide/pages/editing-a-devfile-and-plug-in-at-runtime.adoc rename to modules/end-user-guide/pages/editing-a-devfile-and-plug-in-at-runtime.adoc index 429f42a4a5..5871e7c4c4 100644 --- a/modules/administration-guide/pages/editing-a-devfile-and-plug-in-at-runtime.adoc +++ b/modules/end-user-guide/pages/editing-a-devfile-and-plug-in-at-runtime.adoc @@ -1,7 +1,7 @@ [id="editing-a-devfile-and-plug-in-at-runtime"] // = Editing a devfile and plug-in at runtime :navtitle: Editing a devfile and plug-in at runtime -:keywords: administration-guide, editing-a-devfile-and-plug-in-at-runtime -:page-aliases: .:editing-a-devfile-and-plug-in-at-runtime +:keywords: end-user-guide, editing-a-devfile-and-plug-in-at-runtime +:page-aliases: .:editing-a-devfile-and-plug-in-at-runtime , administration-guide:editing-a-devfile-and-plug-in-at-runtime include::partial$assembly_editing-a-devfile-and-plug-in-at-runtime.adoc[] diff --git a/modules/end-user-guide/pages/publishing-metadata-for-a-vs-code-extension.adoc b/modules/end-user-guide/pages/publishing-metadata-for-a-vs-code-extension.adoc new file mode 100644 index 0000000000..bd622ff5ef --- /dev/null +++ b/modules/end-user-guide/pages/publishing-metadata-for-a-vs-code-extension.adoc @@ -0,0 +1,7 @@ +[id="publishing-metadata-for-a-vs-code-extension"] +// = Publishing a VS Code extension +:navtitle: Publishing a VS Code extension +:keywords: end-user-guide, publishing-metadata-for-a-vs-code-extension +:page-aliases: .:publishing-metadata-for-a-vs-code-extension + +include::partial$proc_publishing-metadata-for-a-vs-code-extension.adoc[] diff --git a/modules/administration-guide/partials/assembly_adding-che-plug-in-registry-vs-code-extension-to-a-workspace.adoc b/modules/end-user-guide/partials/assembly_adding-a-vs-code-extension-to-a-workspace.adoc similarity index 56% rename from modules/administration-guide/partials/assembly_adding-che-plug-in-registry-vs-code-extension-to-a-workspace.adoc rename to modules/end-user-guide/partials/assembly_adding-a-vs-code-extension-to-a-workspace.adoc index 906786d099..a5f1810b74 100644 --- a/modules/administration-guide/partials/assembly_adding-che-plug-in-registry-vs-code-extension-to-a-workspace.adoc +++ b/modules/end-user-guide/partials/assembly_adding-a-vs-code-extension-to-a-workspace.adoc @@ -4,12 +4,16 @@ :parent-context-of-adding-che-plug-in-registry-vs-code-extension-to-a-workspace: {context} -[id="adding-{prod-id-short}-plug-in-registry-vs-code-extension-to-a-workspace_{context}"] -= Adding a plug-in registry VS Code extension to a workspace +[id="adding-a-vs-code-extension-to-a-workspace_{context}"] += Adding a VS Code extension to a workspace :context: adding-{prod-id-short}-plug-in-registry-vs-code-extension-to-a-workspace -When the required VS Code extension is added into a {prod-short} plug-in registry, the user can add it into the workspace through the *{prod-short} Plugins* panel or through the workspace configuration. +This section describes how to add a VS Code extension to a workspace using the *{prod-short} Plugins* panel or the workspace configuration. + +.Prerequisites + +* The VS Code extension is available in the {prod-short} plug-in registry, or metadata for the VS Code extension are available. See xref:publishing-metadata-for-a-vs-code-extension.adoc[]. include::partial$proc_adding-the-vs-code-extension-using-the-che-plugins-panel.adoc[leveloffset=+1] diff --git a/modules/administration-guide/partials/assembly_editing-a-devfile-and-plug-in-at-runtime.adoc b/modules/end-user-guide/partials/assembly_editing-a-devfile-and-plug-in-at-runtime.adoc similarity index 100% rename from modules/administration-guide/partials/assembly_editing-a-devfile-and-plug-in-at-runtime.adoc rename to modules/end-user-guide/partials/assembly_editing-a-devfile-and-plug-in-at-runtime.adoc diff --git a/modules/administration-guide/partials/proc_adding-a-devfile-at-runtime.adoc b/modules/end-user-guide/partials/proc_adding-a-devfile-at-runtime.adoc similarity index 100% rename from modules/administration-guide/partials/proc_adding-a-devfile-at-runtime.adoc rename to modules/end-user-guide/partials/proc_adding-a-devfile-at-runtime.adoc diff --git a/modules/administration-guide/partials/proc_adding-a-plug-in-at-runtime.adoc b/modules/end-user-guide/partials/proc_adding-a-plug-in-at-runtime.adoc similarity index 100% rename from modules/administration-guide/partials/proc_adding-a-plug-in-at-runtime.adoc rename to modules/end-user-guide/partials/proc_adding-a-plug-in-at-runtime.adoc diff --git a/modules/administration-guide/partials/proc_adding-the-vs-code-extension-using-the-che-plugins-panel.adoc b/modules/end-user-guide/partials/proc_adding-the-vs-code-extension-using-the-che-plugins-panel.adoc similarity index 87% rename from modules/administration-guide/partials/proc_adding-the-vs-code-extension-using-the-che-plugins-panel.adoc rename to modules/end-user-guide/partials/proc_adding-the-vs-code-extension-using-the-che-plugins-panel.adoc index 49008883a7..f2bde60085 100644 --- a/modules/administration-guide/partials/proc_adding-the-vs-code-extension-using-the-che-plugins-panel.adoc +++ b/modules/end-user-guide/partials/proc_adding-the-vs-code-extension-using-the-che-plugins-panel.adoc @@ -8,6 +8,7 @@ .Prerequisites * A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. +* The VS Code extension is available in the {prod-short} plug-in registry, or metadata for the VS Code extension are available. See xref:publishing-metadata-for-a-vs-code-extension.adoc[]. .Procedure diff --git a/modules/administration-guide/partials/proc_adding-the-vs-code-extension-using-the-workspace-configuration.adoc b/modules/end-user-guide/partials/proc_adding-the-vs-code-extension-using-the-workspace-configuration.adoc similarity index 89% rename from modules/administration-guide/partials/proc_adding-the-vs-code-extension-using-the-workspace-configuration.adoc rename to modules/end-user-guide/partials/proc_adding-the-vs-code-extension-using-the-workspace-configuration.adoc index 1cc380598f..16b62ab626 100644 --- a/modules/administration-guide/partials/proc_adding-the-vs-code-extension-using-the-workspace-configuration.adoc +++ b/modules/end-user-guide/partials/proc_adding-the-vs-code-extension-using-the-workspace-configuration.adoc @@ -11,6 +11,8 @@ * An existing workspace defined on this instance of {prod} xref:end-user-guide:creating-and-configuring-a-new-workspace.adoc[]. +* The VS Code extension is available in the {prod-short} plug-in registry, or metadata for the VS Code extension are available. See xref:publishing-metadata-for-a-vs-code-extension.adoc[]. + .Procedure To add a VS Code extension using the workspace configuration: diff --git a/modules/administration-guide/partials/proc_writing-a-meta-yaml-file-and-adding-it-to-a-plug-in-registry.adoc b/modules/end-user-guide/partials/proc_publishing-metadata-for-a-vs-code-extension.adoc similarity index 81% rename from modules/administration-guide/partials/proc_writing-a-meta-yaml-file-and-adding-it-to-a-plug-in-registry.adoc rename to modules/end-user-guide/partials/proc_publishing-metadata-for-a-vs-code-extension.adoc index 6e2b91d7f9..f6bd88b635 100644 --- a/modules/administration-guide/partials/proc_writing-a-meta-yaml-file-and-adding-it-to-a-plug-in-registry.adoc +++ b/modules/end-user-guide/partials/proc_publishing-metadata-for-a-vs-code-extension.adoc @@ -2,18 +2,20 @@ // // publishing-a-vs-code-extension-into-the-{prod-id-short}-plug-in-registry -[id="proc_writing-a-meta-yaml-file-and-adding-it-to-a-plug-in-registry_{context}"] -= Writing a meta.yaml file and adding it to a plug-in registry +[id="proc_publishing-metadata-for-a-vs-code-extension_{context}"] += Publishing metadata for a VS Code extension -The plug-in meta information is required to publish a VS Code extension in an {prod} plug-in registry. This meta information is provided as a `meta.yaml` file. This section describes how to create a `meta.yaml` file for an extension. +To use a VS Code extension in a {prod-short} workspace, {prod-short} need to consume metadata describing the extension. The {prod-short} plugin registry is a static website publishing metadata for common VS Code extensions. This section describes how to publish metadata for an additional extension, not available in the {prod-short} plugin registry. This section describes how to create a `meta.yaml` file. + +.Prerequisite + +* If the VS Code extension requires it, the required associated container image is available. .Procedure -. Create a `meta.yaml` file in the following plug-in registry directory: `____/plugins/____/____/____/`. -+ -// NOTE: Support of two or more extensions is broken. See the link:https://github.com/eclipse/che/issues/13578[GitHub description for this issue] for further information. +. Create a `meta.yaml` file. -. Edit the `meta.yaml` file and provide the necessary information. The configuration file must have the following structure: +. Edit the `meta.yaml` file and provide the necessary information. The file must have the following structure: + [source,yaml] ---- @@ -57,3 +59,5 @@ spec: <16> The maximum CPU amount in cores or millicores (suffixed with "m") which is available for the sidecar container. Examples: "500m", "2". This value might be overridden by the user in the component configuration. <17> The CPU amount in cores or millicores (suffixed with "m") which is given for the sidecar container by default. Example: "125m". This value might be overridden by the user in the component configuration. <18> A list of VS Code extensions run in this sidecar container. + +. Publish the `meta.yaml` file as an HTTP resource. \ No newline at end of file diff --git a/modules/installation-guide/examples/che-assembly_installing-che-in-a-restricted-environment.adoc b/modules/installation-guide/examples/assembly_che-installing-che-in-a-restricted-environment.adoc similarity index 66% rename from modules/installation-guide/examples/che-assembly_installing-che-in-a-restricted-environment.adoc rename to modules/installation-guide/examples/assembly_che-installing-che-in-a-restricted-environment.adoc index eae57d7a63..819e57c50c 100644 --- a/modules/installation-guide/examples/che-assembly_installing-che-in-a-restricted-environment.adoc +++ b/modules/installation-guide/examples/assembly_che-installing-che-in-a-restricted-environment.adoc @@ -17,14 +17,31 @@ By default, {prod-short} workspaces reference various external resources, includ * Block-based storage volume or NFS share available outside of the cluster to serve dynamic storage provisioning or PVs. Block-based storage is recommended for optimal performance. -include::example${project-context}-con_understanding-network-connectivity-in-restricted-environments.adoc[leveloffset=+1] +include::example$con_{project-context}-understanding-network-connectivity-in-restricted-environments.adoc[leveloffset=+1] -include::example${project-context}-proc_building-an-offline-plug-in-registry-image.adoc[leveloffset=+1] -include::example${project-context}-proc_building-an-offline-devfile-registry-image.adoc[leveloffset=+1] +include::example$ref_{project-context}-understanding-the-registries.adoc[leveloffset=+1] -include::example${project-context}-proc_preparing-a-private-registry.adoc[leveloffset=+1] -include::example${project-context}-proc_configuring-che-to-run-in-a-restricted-environment.adoc[leveloffset=+1] +:registry-mode: offline +:registry-mode-name: an offline +:registry-id: devfile +:registry-name: devfile + +include::example$proc_{project-context}-building-a-registry-image.adoc[leveloffset=+1] + + +:registry-id: plugin +:registry-name: plug-in + +include::example$proc_{project-context}-building-a-registry-image.adoc[leveloffset=+1] + + +include::example$proc_{project-context}-preparing-a-private-registry.adoc[leveloffset=+1] + + +include::example$proc_{project-context}-configuring-che-to-run-in-a-restricted-environment.adoc[leveloffset=+1] + :context: {parent-context-of-installing-che-in-a-restricted-environment} + diff --git a/modules/installation-guide/examples/che-proc_building-an-offline-devfile-registry-image.adoc b/modules/installation-guide/examples/che-proc_building-an-offline-devfile-registry-image.adoc deleted file mode 100644 index e3a019740f..0000000000 --- a/modules/installation-guide/examples/che-proc_building-an-offline-devfile-registry-image.adoc +++ /dev/null @@ -1,39 +0,0 @@ -[id="building-an-offline-devfile-registry-image_{context}"] -= Building an offline devfile registry image - -This section describes how to build an _offline_ devfile registry image. Starting workspaces without relying on resources from the outside Internet requires building this image. The image contains all sample projects referenced in devfiles as `zip` files. - -.Procedure - -. Clone the devfile registry repository: -+ ----- -$ git clone https://github.com/eclipse/che-devfile-registry.git -$ cd che-devfile-registry ----- - -. Check out version of the registry to deploy: -+ -[subs="+attributes,+quotes"] ----- -$ git checkout {prod-ver}.x ----- - -. Build the devfile registry image: -+ -[subs="+quotes"] ----- -./build.sh --organization __ \ - --registry __ \ - --tag __ \ - --offline ----- -+ -[TIP] -==== -* To display full options for the `build.sh` script, use the `--help` parameter. -==== - -.Additional resources - -* xref:administration-guide:building-and-running-a-custom-registry-image.adoc[] diff --git a/modules/installation-guide/examples/che-proc_building-an-offline-plug-in-registry-image.adoc b/modules/installation-guide/examples/che-proc_building-an-offline-plug-in-registry-image.adoc deleted file mode 100644 index 9754297e4c..0000000000 --- a/modules/installation-guide/examples/che-proc_building-an-offline-plug-in-registry-image.adoc +++ /dev/null @@ -1,41 +0,0 @@ -[id="building-an-offline-plug-in-registry-image_{context}"] -= Building an offline plug-in registry image - -This section describes how to build an _offline_ plug-in registry image. Starting workspaces without relying on resources from the outside Internet requires building this image. The image contains plug-in metadata and all plug-in or extension artifacts. - -.Procedure - -. Clone the plug-in registry repository: -+ ----- -$ git clone https://github.com/eclipse/che-plugin-registry.git -$ cd che-plugin-registry ----- - -. Check out version of the registry to deploy: -+ -[subs="+attributes,+quotes"] ----- -$ git checkout {prod-ver}.x ----- - -. Build the plug-in registry image, including only the _latest_ version of each plug-in: -+ -[subs="+quotes"] ----- -./build.sh --organization __ \ - --registry __ \ - --tag __ \ - --offline \ - --latest-only ----- -+ -[TIP] -==== -* To display full options for the `build.sh` script, use the `--help` parameter. - -==== - -.Additional resources - -* xref:administration-guide:building-and-running-a-custom-registry-image.adoc[] diff --git a/modules/installation-guide/examples/che-con_understanding-network-connectivity-in-restricted-environments.adoc b/modules/installation-guide/examples/con_che-understanding-network-connectivity-in-restricted-environments.adoc similarity index 100% rename from modules/installation-guide/examples/che-con_understanding-network-connectivity-in-restricted-environments.adoc rename to modules/installation-guide/examples/con_che-understanding-network-connectivity-in-restricted-environments.adoc diff --git a/modules/installation-guide/examples/proc_che-building-a-registry-image.adoc b/modules/installation-guide/examples/proc_che-building-a-registry-image.adoc new file mode 100644 index 0000000000..24eab65163 --- /dev/null +++ b/modules/installation-guide/examples/proc_che-building-a-registry-image.adoc @@ -0,0 +1,55 @@ +[id="building-{registry-mode}-{registry-id}-registry-image_{context}"] += Building {registry-mode-name} {registry-name} registry image + +This section describes how to build {registry-mode-name} {registry-name} registry image. +ifeval::["{registry-mode}" == "offline"] +Starting workspaces without relying on resources from the outside Internet requires building this image. +ifeval::["{registry-id}" == "devfile"] +The image contains all sample projects referenced in devfiles as `zip` files. +endif::[] +ifeval::["{registry-id}" == "plugin"] +The image contains plug-in metadata and all plug-in or extension artifacts. +endif::[] +endif::[] +ifeval::["{registry-mode}" == "custom"] +The procedure explains how to add a new {registry-name}. +ifeval::["{registry-id}" == "devfile"] +The image contains all sample projects referenced in devfiles. +endif::[] +ifeval::["{registry-id}" == "plugin"] +The image contains plug-ins or extensions metadata. +endif::[] +endif::[] + + +.Procedure + +. Clone the {registry-name} registry repository and check out the version to deploy: ++ +[subs="+attributes,+quotes"] +---- +include::snip_{project-context}-clone-the-registry-repository.adoc[] +---- + +ifeval::["{registry-mode}" == "custom"] +include::contributor-guide:example$snip_customizing-the-{registry-name}-registry.adoc[] +endif::[] + +. Build {registry-mode-name} {registry-name} registry image: ++ +[subs="+quotes"] +---- +include::snip_{project-context}-build-a-registry.adoc[] +---- ++ +[TIP] +==== +To display full options for the `build.sh` script, use the `--help` parameter. +ifeval::["{registry-mode}" == "custom"] +ifeval::["{registry-id}" == "plugin"] + +To include the plug-in binaries in the registry image, add the `--offline` parameter. +endif::[] +endif::[] +==== + diff --git a/modules/installation-guide/examples/che-proc_configuring-che-to-run-in-a-restricted-environment.adoc b/modules/installation-guide/examples/proc_che-configuring-che-to-run-in-a-restricted-environment.adoc similarity index 100% rename from modules/installation-guide/examples/che-proc_configuring-che-to-run-in-a-restricted-environment.adoc rename to modules/installation-guide/examples/proc_che-configuring-che-to-run-in-a-restricted-environment.adoc diff --git a/modules/installation-guide/examples/che-proc_preparing-a-private-registry.adoc b/modules/installation-guide/examples/proc_che-preparing-a-private-registry.adoc similarity index 100% rename from modules/installation-guide/examples/che-proc_preparing-a-private-registry.adoc rename to modules/installation-guide/examples/proc_che-preparing-a-private-registry.adoc diff --git a/modules/installation-guide/examples/che-ref_supported-platforms-and-installation-methods.adoc b/modules/installation-guide/examples/ref_che-supported-platforms-and-installation-methods.adoc similarity index 100% rename from modules/installation-guide/examples/che-ref_supported-platforms-and-installation-methods.adoc rename to modules/installation-guide/examples/ref_che-supported-platforms-and-installation-methods.adoc diff --git a/modules/installation-guide/examples/ref_che-understanding-the-registries.adoc b/modules/installation-guide/examples/ref_che-understanding-the-registries.adoc new file mode 100644 index 0000000000..3ac4a75841 --- /dev/null +++ b/modules/installation-guide/examples/ref_che-understanding-the-registries.adoc @@ -0,0 +1,12 @@ +[id="understanding-the-{prod-id-short}-registries_{context}"] += Understanding the {prod-short} registries + +{prod-short} uses two registries: the plug-ins registry and the devfile registry. They are static websites publishing the metadata of {prod-short} 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 {prod-short} installation. + +.The devfile and plug-in registries +The devfile registry:: The devfile registry holds the definitions of the {prod-short} stacks. Stacks are available on the {prod-short} user dashboard when selecting *Create Workspace*. It contains the list of {prod-short} 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 {prod-short}. When built in offline mode it also contains all plug-in or extension artifacts. + diff --git a/modules/installation-guide/examples/snip_che-build-a-registry.adoc b/modules/installation-guide/examples/snip_che-build-a-registry.adoc new file mode 100644 index 0000000000..c09b2f77bd --- /dev/null +++ b/modules/installation-guide/examples/snip_che-build-a-registry.adoc @@ -0,0 +1,7 @@ +./build.sh --organization __ \ + --registry __ \ + --tag __ \ +ifeval::["{registry-mode}" == "offline"] + --offline \ +endif::[] + --latest-only \ No newline at end of file diff --git a/modules/installation-guide/examples/snip_che-clone-the-registry-repository.adoc b/modules/installation-guide/examples/snip_che-clone-the-registry-repository.adoc new file mode 100644 index 0000000000..a73cf18054 --- /dev/null +++ b/modules/installation-guide/examples/snip_che-clone-the-registry-repository.adoc @@ -0,0 +1,3 @@ +$ git clone git@github.com:eclipse/che-{registry-id}-registry.git +$ cd che-{registry-id}-registry +$ git checkout {prod-ver}.x \ No newline at end of file diff --git a/modules/installation-guide/pages/installing-che-in-a-restricted-environment.adoc b/modules/installation-guide/pages/installing-che-in-a-restricted-environment.adoc index 2d2a47bbc1..d719144dc7 100644 --- a/modules/installation-guide/pages/installing-che-in-a-restricted-environment.adoc +++ b/modules/installation-guide/pages/installing-che-in-a-restricted-environment.adoc @@ -4,4 +4,4 @@ :keywords: installation-guide, installing-che-in-a-restricted-environment, installing-che-in-restricted-environment :page-aliases: .:installing-che-in-restricted-environment, .:installing-che-in-a-restricted-environment, installing-che-in-restricted-environment -include::example${project-context}-assembly_installing-che-in-a-restricted-environment.adoc[] +include::example$assembly_{project-context}-installing-che-in-a-restricted-environment.adoc[] diff --git a/modules/installation-guide/partials/assembly_upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc b/modules/installation-guide/partials/assembly_upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc index 8272148b9c..ffd4111e9f 100644 --- a/modules/installation-guide/partials/assembly_upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc +++ b/modules/installation-guide/partials/assembly_upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc @@ -15,13 +15,23 @@ This section describes how to upgrade {prod} using the CLI management tool in re * The `{prod-cli}` {prod-ver} management tool is available. See xref:overview:using-the-chectl-management-tool.adoc[]. -include::example${project-context}-con_understanding-network-connectivity-in-restricted-environments.adoc[leveloffset=+1] +include::example$con_{project-context}-understanding-network-connectivity-in-restricted-environments.adoc[leveloffset=+1] -include::example${project-context}-proc_building-an-offline-plug-in-registry-image.adoc[leveloffset=+1] +:registry-mode: offline +:registry-mode-name: an offline +:registry-id: devfile +:registry-name: devfile -include::example${project-context}-proc_building-an-offline-devfile-registry-image.adoc[leveloffset=+1] +include::example$proc_{project-context}-building-a-registry-image.adoc[leveloffset=+1] -include::example${project-context}-proc_preparing-a-private-registry.adoc[leveloffset=+1] + +:registry-id: plugin +:registry-name: plug-in + +include::example$proc_{project-context}-building-a-registry-image.adoc[leveloffset=+1] + + +include::example$proc_{project-context}-preparing-a-private-registry.adoc[leveloffset=+1] include::partial$proc_upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc[leveloffset=+1] diff --git a/modules/installation-guide/partials/con_supported-platforms.adoc b/modules/installation-guide/partials/con_supported-platforms.adoc index 99b6e04c9f..b31ad0a1d4 100644 --- a/modules/installation-guide/partials/con_supported-platforms.adoc +++ b/modules/installation-guide/partials/con_supported-platforms.adoc @@ -1,5 +1,5 @@ [id="supported-platforms_{context}"] = Supported platforms -include::example${project-context}-ref_supported-platforms-and-installation-methods.adoc[leveloffset=+1] +include::example$ref_{project-context}-supported-platforms-and-installation-methods.adoc[leveloffset=+1]