procedures: Add docs about Open VSX on-premises

modules/administration-guide/examples/snip_che-deploy-open-vsx-using-oc.adoc

@@ -0,0 +1,153 @@
+* Installed `oc` and git tools.
+* Installed Podman.
+* Log in to the OpenShift cluster where a {prod-short} is deployed as an administrator.
++
+[TIP]
+====
+
+`$ oc login pass:c,a,q[{prod-url}] --username=__<my_user>__`
+
+====
+
+.Procedure
+
+. Create a new OpenShift project for Open VSX.
++
+[subs="+attributes,+quotes"]
+----
+oc new-project openvsx
+----
+. Clone Open VSX sources.
++
+Get Open VSX sources and navigate to the OpenShift deploy directory:
++
+[bash,subs="verbatim",options="nowrap"]
+----
+git clone https://github.com/eclipse/openvsx.git &&
+cd openvsx/deploy/openshift
+----
+
+. Prepare Open VSX server image.
++
+The next step is to build and publish the Open VSX server image. To do this, run the following commands:
++
+[bash,subs="verbatim",options="nowrap"]
+----
+export REGISTRY=quay.io &&
+export NAMESPACE=myuser &&
+export OPENVSX_SERVER_IMAGE_NAME=openvsx-server &&
+export OPENVSX_VERSION=v0.27.0 &&
+export OPENVSX_SERVER_IMAGE=${REGISTRY}/${NAMESPACE}/${OPENVSX_SERVER_IMAGE_NAME}:${OPENVSX_VERSION} &&
+podman build -t "${OPENVSX_SERVER_IMAGE}" --build-arg "OPENVSX_VERSION=${OPENVSX_VERSION}" -f openvsx.Dockerfile . &&
+podman login "${REGISTRY}" &&
+podman push "${OPENVSX_SERVER_IMAGE}"
+----
++
+[IMPORTANT]
+====
+
+Make sure to configure the correct container registry and namespace for your image. Additionally, ensure that the image is publicly accessible and can be pulled without authentication.
+
+====
+
+. Prepare Open VSX CLI image.
++
+Build and publish the Open VSX CLI image. To do this, run the following commands:
++
+[bash,subs="verbatim",options="nowrap"]
+----
+export OPENVSX_CLI_IMAGE_NAME=openvsx-cli &&
+export OPENVSX_CLI_VERSION=0.10.5 &&
+export OPENVSX_CLI_IMAGE=${REGISTRY}/${NAMESPACE}/${OPENVSX_CLI_IMAGE_NAME}:${OPENVSX_CLI_VERSION} &&
+podman build -t "${OPENVSX_CLI_IMAGE}" --build-arg "OVSX_VERSION=${OPENVSX_CLI_VERSION}" -f cli.Dockerfile . &&
+podman push "${OPENVSX_CLI_IMAGE}"
+----
++
+[IMPORTANT]
+====
+
+Ensure that the image is publicly accessible and can be pulled without authentication.
+
+====
+
+. Deploy Open VSX.
++
+[bash,subs="verbatim",options="nowrap"]
+----
+oc process -f openvsx-deployment.yml \
+-p OPENVSX_SERVER_IMAGE="${OPENVSX_SERVER_IMAGE}" \
+-p OPENVSX_CLI_IMAGE="${OPENVSX_CLI_IMAGE}" \
+| oc apply -f -
+----
+
+. Verify that all pods in the `openvsx` namespace are running and ready. It might take a few minutes for all pods to become ready. Run the following command:
++
+[bash,subs="verbatim",options="nowrap"]
+----
+oc get pods -n openvsx \
+  -o jsonpath='{range .items[*]}{@.metadata.name}{"\t"}{@.status.phase}{"\t"}{.status.containerStatuses[*].ready}{"\n"}{end}'
+----
+
+. Add Open VSX user with PAT to the database.
++
+Find PostgreSQL pod:
++
+[bash,subs="verbatim",options="nowrap"]
+----
+export POSTGRESQL_POD_NAME=$(oc get pods -n openvsx \
+   -o jsonpath="{.items[*].metadata.name}" | tr ' ' '\n' | grep '^postgresql' | head -n 1)
+----
++
+Insert username into OpenVSX database:
++
+[bash,subs="verbatim",options="nowrap"]
+----
+oc exec -n openvsx "$POSTGRESQL_POD_NAME" -- bash -c \
+   "psql -d openvsx -c \"INSERT INTO user_data (id, login_name, role) VALUES (1001, 'eclipse-che', 'privileged');\""
+----
++
+Insert user PAT into OpenVSX database:
++
+[bash,subs="verbatim",options="nowrap"]
+----
+oc exec -n openvsx "$POSTGRESQL_POD_NAME" -- bash -c \
+   "psql -d openvsx -c \"INSERT INTO personal_access_token (id, user_data, value, active, created_timestamp, accessed_timestamp, description) VALUES (1001, 1001, 'eclipse_che_token', true, current_timestamp, current_timestamp, 'extensions publisher');\""
+----
+
+. Configure {prod-short} to use the internal Open VSX.
++
+[bash,subs="verbatim",options="nowrap"]
+----
+export CHECLUSTER_NAME="$(oc get checluster --all-namespaces -o json | jq -r '.items[0].metadata.name')" &&
+export CHECLUSTER_NAMESPACE="$(oc get checluster --all-namespaces -o json | jq -r '.items[0].metadata.namespace')" &&
+export OPENVSX_ROUTE_URL="$(oc get route internal -n openvsx -o jsonpath='{.spec.host}')" &&
+export PATCH='{"spec":{"components":{"pluginRegistry":{"openVSXURL":"https://'"$OPENVSX_ROUTE_URL"'"}}}}' &&
+oc patch checluster "${CHECLUSTER_NAME}" --type=merge --patch "${PATCH}" -n "${CHECLUSTER_NAMESPACE}"
+----
++
+[TIP]
+====
+
+Refer to the xref:configuring-the-open-vsx-registry-url.adoc[] for detailed instructions on configuring the Open VSX registry URL in {prod-short}.
+
+====
+
+. Publish Visual Studio Code extensions with the `ovsx` command.
++
+[NOTE]
+====
+
+At the beginning, the Open VSX registry does not provide any extension.
+
+====
++
+With everything configured, the next step is to publish a Visual Studio Code extension from inside the ovsx-cli container.
+To do this, you need two pieces of information: the extension `namespace` name (used for publishing), the download URL of the .vsix extension package.
+Once you have this information, run the following commands to publish the extension: 
++
+.. Retrieve the name of the pod running the Open VSX server:
++ 
+[bash,subs="verbatim",options="nowrap"]
+----
+export OVSX_POD_NAME=$(oc get pods -n openvsx -o jsonpath="{.items[*].metadata.name}" | tr ' ' '\n' | grep ^ovsx-cli)
+----

modules/administration-guide/examples/snip_che-deploy-open-vsx.adoc

@@ -0,0 +1,30 @@
+. Build and Publish Open VSX image.
++
+To build and deploy the Open VSX server container image to the OpenShift internal image registry, run the `2.2. Build and Publish Open VSX Image` task in the workspace: (`Terminal → Run Task… → devfile → 2.2. Build and Publish OpenVSX Image`). During execution, you will be prompted to enter the Open VSX server version. If left blank, the task will default to using v0.27.0.
++
+[TIP]
+====
+Open VSX server versions could be found on the OpenVSX GitHub release page: https://github.com/eclipse/openvsx/releases 
+====
+
+. Build and Publish Open VSX CLI (`ovsx`) Image.
++
+Run `2.3. Build and Publish OpenVSX CLI Image` task in the workspace (`Terminal → Run Task… → devfile → 2.3. Build and Publish OpenVSX CLI Image`) to build the Open VSX CLI image and push it to OpenShift internal registry.
+
+. Deploy Open VSX.
++
+Run `2.4. Deploy OpenVSX` task in the workspace (`Terminal → Run Task… → devfile → 2.4. Deploy OpenVSX`). This command deploys the Open VSX components to an OpenShift project by processing a template file (openvsx-deployment.yml). It creates all required resources defined in the template, which includes:
++
+.. Deployments (PostgreSQL, Elasticsearch, Open VSX server, Open VSX CLI).
++
+.. Services and Routes for accessing components.
++
+.. Secrets for GitHub OAuth credentials and Open VSX personal access token.
+
++
+[TIP]
+====
+
+All deployment information is described in the `deploy/openshift/openvsx-deployment.yml` file with some default values such as `OVSX_PAT_BASE64`. 
+
+====

modules/administration-guide/nav.adoc

@@ -107,6 +107,7 @@
 *** xref:enabling-fuse-for-all-workspaces.adoc[]
 * xref:managing-ide-extensions.adoc[]
 ** xref:extensions-for-microsoft-visual-studio-code-open-source.adoc[]
+** xref:running-the-open-vsx-on-premises.adoc[]
 ** xref:configuring-the-open-vsx-registry-url.adoc[]
 * xref:configuring-visual-studio-code.adoc[]
 ** xref:configuring-single-and-multiroot-workspaces.adoc[]

modules/administration-guide/pages/managing-ide-extensions.adoc

@@ -10,5 +10,6 @@
 IDEs use extensions or plugins to extend their functionality, and the mechanism for managing extensions differs between IDEs.
 
 * xref:extensions-for-microsoft-visual-studio-code-open-source.adoc[]
+* xref:running-the-open-vsx-on-premises.adoc[]
 * xref:configuring-the-open-vsx-registry-url.adoc[]
 

modules/administration-guide/pages/running-the-open-vsx-on-premises.adoc

@@ -0,0 +1,152 @@
+:_content-type: PROCEDURE
+:description: Running Open VSX On-Premises
+:keywords: administration guide, configuring, openvsx, registry
+:navtitle: Running Open VSX On-Premises
+:page-aliases:
+
+[id="running-the-open-vsx-on-premises"]
+= Running the Open VSX On-Premises
+
+Follow the instructions below to deploy and configure an on-premises Eclipse Open VSX extension registry, fully integrated with {prod-short} and OpenShift environments. Choose one of the two setup paths: using a {prod-short} workspace or the OpenShift CLI (`oc`), to help you set up a secure, internal Open VSX instance. This includes creating necessary OpenShift project, deploying Open VSX components, publishing extensions and integrating the registry with {prod-short}.
+
+== Using {prod-short} instance
+
+.Prerequisites
+
+* Be logged in to a {prod-short} as an administrator.
+
+.Procedure
+
+. Start a workspace using the Open VSX repository.
++
+Create a workspace by using the following link:https://github.com/eclipse/openvsx[Eclipse Open VSX repository].
++
+[TIP]
+====
+The environment, including all necessary commands, is defined in the `.devfile.yaml` file.
+====
+
+. Create a new OpenShift project for Open VSX.
++
+Run `2.1. Create Namespace for OpenVSX` task in the workspace (`Terminal → Run Task… → devfile → 2.1. Create Namespace for OpenVSX`). A new project with the name `openvsx` should be created on the cluster.
+
+include::example$snip_{project-context}-deploy-open-vsx.adoc[]
+
+. Add Open VSX user with PAT to the database.
++
+Run the `2.5. Add OpenVSX user with PAT to the DB` task in the workspace (`Terminal → Run Task… → devfile → 2.5. Add OpenVSX user with PAT to the DB`). The command will ask for the Open VSX username and user PAT. You can just click enter to use the default values. 
++
+[IMPORTANT]
+====
+
+The user PAT must match the decoded value of `OVSX_PAT_BASE64` specified in the deployment file. If `OVSX_PAT_BASE64` has been updated, use the new token's decoded value as the user PAT.
+
+====
+
+. Configure {prod-short} to use the internal Open VSX.
++
+Run the `2.6. Configure Che to use the internal Open VSX registry` task in the workspace (`Terminal → Run Task… → devfile → 2.6. Configure Che to use the internal OpenVSX registry`). It applies the patch to the `CheCluster` custom resource, updating its configuration to use the specified Open VSX URL for the extension registry.
+
+.  Publish an extension from a `.vsix` file.
++
+At the beginning, the Open VSX registry does not provide any extension. Once the `openvsx-server` pod is running and in the Ready state, extensions can be published to the registry. The `2.8. Publish a Visual Studio Code Extension from a VSIX file` command publishes an extension to the local Open VSX registry directly from a `.vsix` file. It prompts you to provide the extension's `namespace` name and the path to the `.vsix` file. 
+
+.  Publish list of extensions.
++
+The `2.9. Publish list of Visual Studio Code Extensions` command automates the process of publishing a predefined list of Microsoft Visual Studio Code extensions based on download URLs to the internal Open VSX registry. 
++
+[TIP]
+====
+The command reads from the `deploy/openshift/extensions.txt` file, which lists the URLs of `.vsix` files for each extension to be published.
+To publish your extensions to Open VSX, update the `extensions.txt` file as needed, then run the 2.9. Publish list of Visual Studio Code Extensions task from the workspace:
+`Terminal → Run Task… → devfile → 2.9. Publish list of Visual Studio Code Extensions`.
+====
+
+. Verify that {prod-short} uses internal Open VSX.
++
+Start any workspace and check the available extensions in the Extensions view of the workspace IDE or by opening the `internal` route in the OpenVSX OpenShift project.
+
+== Using OpenShift CLI (`oc`) tool
+
+.Prerequisites
+
+include::example$snip_{project-context}-deploy-open-vsx-using-oc.adoc[]
++
+.. Download the .vsix extension:
++ 
+[bash,subs="verbatim",options="nowrap"]
+----
+oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "wget -O /tmp/extension.vsix EXTENSION_DOWNLOAD_URL "
+----
++
+.. Create an extension namespace:
++
+[bash,subs="verbatim",options="nowrap"]
+---- 
+oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "ovsx create-namespace EXTENSION_NAMESPACE_NAME" || true
+----
++
+.. Publish the extension:
++
+[bash,subs="verbatim",options="nowrap"]
+----
+oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "ovsx publish /tmp/extension.vsix"
+----
++
+.. Delete the downloaded extension file:
++ 
+[bash,subs="verbatim",options="nowrap"]
+----
+oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "rm /tmp/extension.vsix"
+----
++
+[TIP]
+====
+
+Example: Publish the `redhat.vscode-yaml` extension version 1.18.0:
+[bash,subs="verbatim",options="nowrap"]
+----
+oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "wget -O /tmp/extension.vsix https://open-vsx.org/api/redhat/vscode-yaml/1.18.0/file/redhat.vscode-yaml-1.18.0.vsix " &&
+oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "ovsx create-namespace redhat" || true &&
+oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "ovsx publish /tmp/extension.vsix" &&
+oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "rm /tmp/extension.vsix"
+----
+
+====
++
+. Verify Open VSX extension registry.
++
+Check the list of published extensions by navigating to the URL defined in the OPENVSX_ROUTE_URL environment variable.
+
+== Setting Up Internal Access to the Open VSX Service
+
+In addition to using a public route to reference the Open VSX registry, you can also configure {prod-short} to set internal cluster service routing. This method provides enhanced security by keeping traffic confined within the cluster, avoiding public exposure.
+
+.Procedure
+
+Steps for Internal Service Routing:
+
+. Remove the Public Route.
++
+Delete the public route associated with the Open VSX registry to restrict external access:
++ 
+[bash,subs="verbatim",options="nowrap"]
+----
+oc delete route internal -n openvsx
+----
+
+. Set the Internal Open VSX Service URL.
++
+Update the CheCluster custom resource to use the internal cluster service DNS:
++ 
+[bash,subs="verbatim",options="nowrap"]
+----
+export CHECLUSTER_NAME="$(oc get checluster --all-namespaces -o json | jq -r '.items[0].metadata.name')" &&
+export CHECLUSTER_NAMESPACE="$(oc get checluster --all-namespaces -o json | jq -r '.items[0].metadata.namespace')" &&
+export PATCH='{"spec":{"components":{"pluginRegistry":{"openVSXURL":"http://openvsx-server.openvsx.svc:8080"}}}}' &&
+oc patch checluster "${CHECLUSTER_NAME}" --type=merge --patch "${PATCH}" -n "${CHECLUSTER_NAMESPACE}"
+----
+
+.Additional resources
+* link:https://github.com/eclipse/openvsx/[Eclipse Open VSX sources]
+* link:https://github.com/eclipse/openvsx/wiki/[Eclipse Open VSX documentation]

modules/administration-guide/partials/proc_adding-or-removing-extensions-in-the-embedded-open-vsx-registry-instance.adoc

@@ -3,6 +3,11 @@
 [id="adding-or-removing-extensions-in-the-embedded-open-vsx-registry-instance"]
 = Adding or removing extensions in the embedded Open VSX registry instance
 
+[IMPORTANT]
+====
+You can manage Visual Studio Code extensions by setting up and using an internal, on-premises Open VSX registry. This approach provides full control over the extension lifecycle, enables offline use, and improves compliance. The embedded plugin registry will be deprecated in future releases, with the Open VSX registry serving as its successor. Refer to the xref:running-the-open-vsx-on-premises.adoc[] for detailed setup instructions.
+====
+
 You can add or remove extensions in the embedded Open VSX registry instance. This results in a custom build of the Open VSX registry that can be used in your organization’s workspaces. 
 
 pass:[<!-- vale RedHat.TermsErrors = NO -->]