docs: restructure Open VSX on-premises documentation (#3078)

* docs: add procedure to deploy Open VSX with a pre-built image

Replaces the workspace-based deployment section of the monolithic
running-the-open-vsx-on-premises.adoc page. Shows actual commands
instead of opaque devfile task references. Fixes CRW-10789 by
removing the notified column from the personal_access_token INSERT.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add procedure to deploy Open VSX from source

Replaces the CLI-based deployment section and build steps from the
monolithic running-the-open-vsx-on-premises.adoc page. Fixes CRW-10789
SQL bug, updates stale eclipse/openvsx URLs, fixes AsciiDoc source
block syntax.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add procedure to configure internal Open VSX access

Extracts the 'Setting Up Internal Access' section from the monolithic
running-the-open-vsx-on-premises.adoc into a standalone, JTBD-aligned
procedure for security hardening.

* docs: rewrite Open VSX registry URL configuration procedure

Adds proper abstract, prerequisites, definition lists, verification,
rate limiting note, air-gap warning, and Additional resources.
Adapted from downstream CQA 2.1-compliant content.

* docs: promote delete-via-API procedure to standalone page

Moves from partials/ to pages/ for independent discoverability.
Fixes CRW-10789 SQL bug (removes notified column), replaces
hardcoded oc with {orch-cli}, converts to definition lists.

* docs: promote delete-from-DB procedure to standalone page

Moves from partials/ to pages/ for independent discoverability.
Replaces hardcoded oc with {orch-cli}, adds Antora metadata,
adds Additional resources with xref to admin API method.

* docs: rewrite IDE extensions concept page with JTBD framing

Replaces thin wrapper (one sentence + xref list) with proper concept
explaining WHY extension management matters and the three registry
options. All links in Additional resources per DITA ConceptLink rule.

* docs: update nav.adoc for restructured Open VSX section

Replaces 3 monolithic entries with 7 focused pages following
JTBD user journey: understand → configure → deploy → secure → maintain.

* docs: remove replaced monolithic pages, snippets, and partials

Removes files superseded by the new modular structure:
- running-the-open-vsx-on-premises.adoc (replaced by 3 focused procedures)
- deleting-extension-from-the-open-vsx-on-premises.adoc (thin wrapper)
- snip_che-deploy-open-vsx.adoc (content inlined)
- snip_che-deploy-open-vsx-using-oc.adoc (content inlined)
- partials/proc_deleting-* (promoted to standalone pages)

Updates xrefs in out-of-scope partials that referenced the deleted page.

* docs: fix broken xrefs to partial files in registry URL procedure

Replace xrefs to non-page partials (adding-or-removing-extensions-*)
with xref to their parent page (extensions-for-microsoft-visual-studio-
code-open-source.adoc) for valid Antora resolution.

* docs: add Next steps, fix SQL, add workspace deploy procedure

Address SME review feedback:
- Restore notified column in SQL INSERT statements (mandatory for
  OpenVSX v0.33.0+) in all 3 procedure files
- Add image compatibility note to pre-built deploy procedure
- Add new procedure: deploy Open VSX from a Che workspace using
  devfile tasks (preserves devfile-based workflow for existing users)
- Update nav.adoc and concept page with workspace procedure xref
- Add Next steps to deploy procedures
- Fix broken xrefs to partial files in registry URL procedure
- Fix Vale errors (namespace wording)

* docs: remove pre-built image procedure (upstream-only deploy is from source)

The openvsx-deployment-no-es.yml template requires custom-built images,
which only exist downstream. Remove the misleading pre-built image
procedure from upstream and redirect all xrefs to the from-source
procedure.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: gtrivedi88

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

@@ -113,9 +113,12 @@
 *** xref:devworkspace-backup-regular-oci-registry.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:deleting-extension-from-the-open-vsx-on-premises.adoc[]
 ** xref:configuring-the-open-vsx-registry-url.adoc[]
+** xref:proc_deploy-open-vsx-from-source.adoc[]
+** xref:proc_deploy-open-vsx-from-workspace.adoc[]
+** xref:proc_configure-internal-open-vsx-access.adoc[]
+** xref:proc_deleting-extension-using-openvsx-admin-api.adoc[]
+** xref:proc_deleting-extension-from-postgresql-database.adoc[]
 * xref:configuring-visual-studio-code.adoc[]
 ** xref:configuring-single-and-multiroot-workspaces.adoc[]
 ** xref:trusted-extensions-for-microsoft-visual-studio-code.adoc[]

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

@@ -1,33 +1,72 @@
 :_content-type: PROCEDURE
-:description: Configuring the Open VSX registry URL for all {prod} workspaces
-:keywords: administration guide, configuring, openvsx, registry
-:navtitle: Open VSX registry URL
+:description: Configure the Open VSX registry URL for {prod} workspaces
+:keywords: administration guide, configuring, openvsx, registry, extensions
+:navtitle: Configure the Open VSX registry URL
 :page-aliases:
 
 [id="configuring-the-open-vsx-registry-url"]
-= Configuring the Open VSX registry URL
+= Configure the Open VSX registry URL
 
-To search and install extensions, the Microsoft Visual Studio Code - Open Source editor uses an embedded Open VSX registry instance.
-You can also configure {prod-short} to use another Open VSX registry instance rather than the embedded one.
+[role="_abstract"]
+Configure {prod-short} to use an alternative Open VSX registry instance instead of the default embedded registry. Switch to the public open-vsx.org registry for internet-connected environments, or to a standalone on-premises instance for full control over available extensions.
+
+The default is the embedded instance of the Open VSX registry.
+
+If the default Open VSX registry instance does not meet your requirements, you can select one of the following instances:
+
+* The Open VSX registry instance at `pass:c,a,q[https://open-vsx.org]` that requires access to the internet.
+
+* A standalone Open VSX registry instance that is deployed on a network accessible from {prod-short} workspace pods.
+
+.Prerequisites
+
+* You have administrator access to the cluster where {prod-short} is deployed.
+* You have an active `{orch-cli}` session with administrative permissions. See {orch-cli-link}.
 
 .Procedure
-* Set the URL of your Open VSX registry instance in the CheCluster Custom Resource `spec.components.pluginRegistry.openVSXURL` field.
+
+. Edit the `CheCluster` custom resource to update the `openVSXURL` value:
 +
-[source,yaml,subs="+attributes,+quotes"]
+[source,yaml,subs="+quotes"]
 ----
 spec:
-   components:
-# [...]
-     pluginRegistry:
-       openVSXURL: __<your_open_vsx_registy>__
-# [...]
+  components:
+    pluginRegistry:
+      openVSXURL: "__<url_of_an_open_vsx_registry_instance>__"
 ----
 +
+where:
++
+`__<url_of_an_open_vsx_registry_instance>__`:: The URL of the Open VSX registry instance. For example: `openVSXURL: "pass:c,a,q[https://open-vsx.org]"`.
++
+--
+* To select the embedded Open VSX registry instance in the `plugin-registry` pod, use `openVSXURL: ''`. You can customize the list of included extensions. See xref:extensions-for-microsoft-visual-studio-code-open-source.adoc[].
+
+* You can also point `openVSXURL` at the URL of a standalone Open VSX registry instance. The URL must be accessible from within your organization's cluster and not blocked by a proxy.
+--
++
+[NOTE]
+====
+To ensure the stability and performance of the community-supported Open VSX Registry, API usage is organized into defined tiers. The Eclipse Foundation implements these limits to protect infrastructure from high-frequency automated traffic and to provide consistent service quality for all users. For more information, see link:https://github.com/EclipseFdn/open-vsx.org/wiki/rate-limiting[Rate Limits and Usage Tiers] and the link:https://github.com/EclipseFdn/open-vsx.org/wiki[open-vsx.org wiki].
+====
++
+[IMPORTANT]
+====
+Using link:https://open-vsx.org[https://open-vsx.org] is not recommended in an air-gapped environment, isolated from the internet. To reduce the risk of malware infections and unauthorized access to your code, use the embedded or self-hosted Open VSX registry with a curated set of extensions.
+====
++
 [WARNING]
 ====
 Due to the dedicated Microsoft link:https://cdn.vsassets.io/v/M190_20210811.1/_content/Microsoft-Visual-Studio-Marketplace-Terms-of-Use.pdf[Terms of Use], link:https://marketplace.visualstudio.com/vscode[Visual Studio Code Marketplace] is not supported by {prod}.
 ====
 
+.Verification
+
+* Confirm that the `plugin-registry` pod has restarted and is running.
+* Open a workspace and verify that extensions are available from the selected registry instance in the *Extensions* view.
+
+[role="_additional-resources"]
 .Additional resources
+
 * xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]
 * link:https://open-vsx.org/[Open VSX registry]

modules/administration-guide/nav.adoc

@@ -1,16 +1,32 @@
 :_content-type: CONCEPT
-:description: Managing IDE extensions
-:keywords: extensions, plugins, plug-ins, registry
+:description: Options for managing IDE extensions in {prod} workspaces
+:keywords: extensions, plugins, openvsx, registry, ide
 :navtitle: Managing IDE extensions
-//:page-aliases:
+:page-aliases:
 
 [id="managing-ide-extensions"]
 = Managing IDE extensions
 
-IDEs use extensions or plugins to extend their functionality, and the mechanism for managing extensions differs between IDEs.
+[role="_abstract"]
+Manage IDE extensions in {prod-short} workspaces to control which extensions are available, trusted, and pre-installed for users across different IDE types. Extension management is essential for air-gapped environments, security-conscious organizations, and teams that need consistent developer tooling.
+
+IDEs in {prod-short} use extensions to provide language support, debugging, linting, and other development tools. The Microsoft Visual Studio Code - Open Source editor manages extensions through the Open VSX registry.
+
+{prod-short} supports three registry configurations:
+
+Embedded Open VSX registry:: Runs in the `plugin-registry` pod and supports air-gapped, offline, and proxy-restricted environments. Contains a default subset of extensions that you can customize.
+
+Public Open VSX registry:: The community-hosted registry at `open-vsx.org`, accessed over the internet. Provides the full catalog of openly published extensions.
+
+Standalone Open VSX registry:: A self-hosted instance deployed on a network accessible from {prod-short} workspace pods. Provides full control over available extensions for organizations that need a curated, private registry.
+
+[role="_additional-resources"]
+.Additional resources
 
 * xref:extensions-for-microsoft-visual-studio-code-open-source.adoc[]
-* xref:running-the-open-vsx-on-premises.adoc[]
-* xref:deleting-extension-from-the-open-vsx-on-premises.adoc[]
 * xref:configuring-the-open-vsx-registry-url.adoc[]
-
+* xref:proc_deploy-open-vsx-from-source.adoc[]
+* xref:proc_deploy-open-vsx-from-workspace.adoc[]
+* xref:proc_configure-internal-open-vsx-access.adoc[]
+* xref:proc_deleting-extension-using-openvsx-admin-api.adoc[]
+* xref:proc_deleting-extension-from-postgresql-database.adoc[]

modules/administration-guide/pages/configuring-the-open-vsx-registry-url.adoc

@@ -0,0 +1,49 @@
+:_content-type: PROCEDURE
+:description: Restrict the Open VSX registry to internal cluster access
+:keywords: administration guide, openvsx, security, internal, routing
+:navtitle: Configure internal Open VSX access
+:page-aliases:
+
+[id="proc_configure-internal-open-vsx-access"]
+= Configure internal access to the Open VSX registry
+
+[role="_abstract"]
+Restrict your Open VSX registry to internal cluster traffic by removing the public route and configuring {prod-short} to use the internal service URL. Internal routing keeps extension registry traffic within the cluster and avoids public exposure.
+
+.Prerequisites
+
+* You have Open VSX deployed in the `openvsx` namespace.
+* You have the `{orch-cli}` tool installed.
+* You are logged in to the cluster as a cluster administrator.
+* You have `jq` installed.
+
+.Procedure
+
+. Delete the public route for the Open VSX registry:
++
+[source,bash,subs="+attributes,+quotes",options="nowrap"]
+----
+{orch-cli} delete route internal -n openvsx
+----
+
+. Update the CheCluster custom resource to use the internal service DNS URL:
++
+[source,bash,subs="+attributes,+quotes",options="nowrap"]
+----
+export CHECLUSTER_NAME="$({orch-cli} get checluster --all-namespaces -o json | jq -r '.items[0].metadata.name')" &&
+export CHECLUSTER_NAMESPACE="$({orch-cli} get checluster --all-namespaces -o json | jq -r '.items[0].metadata.namespace')" &&
+export PATCH='{"spec":{"components":{"pluginRegistry":{"openVSXURL":"http://openvsx-server.openvsx.svc:8080"}}}}' &&
+{orch-cli} patch checluster "${CHECLUSTER_NAME}" --type=merge --patch "${PATCH}" -n "${CHECLUSTER_NAMESPACE}"
+----
+
+. Restart any running workspaces to apply the new registry URL.
+
+.Verification
+
+* Start a workspace and verify that extensions are available in the Extensions view using the internal registry.
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:proc_deploy-open-vsx-from-source.adoc[]
+* xref:configuring-the-open-vsx-registry-url.adoc[]