docs(marketplace): insights how to self-host vscode marketplace

[ghuntley]

Fixes #1319 and #1318

[GitMensch]

From this docs it is totally unclear to me how to use this self-hosted local-only "marketplace"; I've even followed the linked docs which says something about "Coder" and that binary - but nothing about how to configure vscodium (or vscode or anything else) to use this. Did I miss something?
Should the docs possibly mention that you can self-host an OpenVSX instance that can be configured to be used in the local IDE?

[daiyam]

{
  "extensionsGallery": {
    "serviceUrl": "<<API URL>>",
    "cacheUrl": "",
    "itemUrl": "<<item URL>>",
    "controlUrl": "",
    "recommendationsUrl": ""
  }
}

I think the UI need to be more explicit or even give a template of resulting JSON.
@ghuntley What do you think?

[ghuntley]

I think the UI need to be more explicit or even give a template of resulting JSON.

ah if I understand @GitMensch correctly here's after how to configure VSCodium itself whereas the screenshot is about configuration of v1 of Coder which is a totally different thing to https://github.com/coder/code-marketplace

[ghuntley]

From this docs it is totally unclear to me how to use this self-hosted local-only "marketplace"

The configuration instructions for VSCodium are the same as https://github.com/VSCodium/vscodium/blob/master/DOCS.md#how-to-use-the-vs-code-marketplace @GitMensch

Replace marketplace.visualstudio.com but with your-self-hosted-marketplace-address.example.com

[GitMensch]

What would be the cache URL?

[GitMensch]

Background: I've rewriting the readme, current draft of that area:

---

Extensions + Marketplace

Being a vscode based editor, VSCodium gets additional features by installing VS Code extensions.
Unfortunately, as Microsoft prohibits usages of the Microsoft marketplace by any other products or redistribution of .vsix files from it, in order to use VS Code extensions in non-Microsoft products those need to be installed differently.

By default, the product.json file is set up to use open-vsx.org as extension gallery, which has an adapter to the Marketplace API used by VS Code. Since that is a rather new project, you will likely miss some extensions you know from the VS Code Marketplace. You have the following options to obtain such missing extensions:

• Ask the extension maintainers to publish to open-vsx.org in addition to the VS Code Marketplace. The publishing process is documented in the Open VSX Wiki.
• Create a pull request to this repository to have the @open-vsx service account publish the extensions for you.
• Download and install the vsix files, for example from the release page in their source repository.

How to use the Open VSX Registry

As noted above, the Open VSX Registry is the pre-set extension gallery in VSCodium. Using the extension view in VSCodium will therefore by default use it.
See this article for more information on the motivation behind Open VSX.

How to use a different extension gallery

You can switch from the pre-set Open VSX Registry by configuring the endpoints using the following solutions.
These examples use the URLs for Microsoft's VS Code Marketplace, see below for more information on that.

With the following environment variables:

• VSCODE_GALLERY_SERVICE_URL='https://marketplace.visualstudio.com/_apis/public/gallery'
• VSCODE_GALLERY_ITEM_URL='https://marketplace.visualstudio.com/items'
• VSCODE_GALLERY_CACHE_URL='https://vscode.blob.core.windows.net/gallery/index'
• VSCODE_GALLERY_CONTROL_URL=''
• VSCODE_GALLERY_RECOMMENDATIONS_URL=''

Or by creating a custom product.json at the following location (replace VSCodium by VSCodium - Insiders if you use that):

• Windows: %APPDATA%\VSCodium or %USERPROFILE%\AppData\Roaming\VSCodium
• macOS: ~/Library/Application Support/VSCodium
• Linux: $XDG_CONFIG_HOME/VSCodium or ~/.config/VSCodium

with the content:

{
  "extensionsGallery": {
    "serviceUrl": "https://marketplace.visualstudio.com/_apis/public/gallery",
    "itemUrl": "https://marketplace.visualstudio.com/items",
    "cacheUrl": "https://vscode.blob.core.windows.net/gallery/index", // set to empty string for every other extension gallery
    "controlUrl": "",
    "recommendationsUrl": ""
  }
}

How to self-host your own VS Code Marketplace

Individual developers and enterprise companies in regulated or security-conscious industries can self-host their own extension gallery. In all of these cases you'd enter its endpoint URLs as noted above, replacing marketplace.visualstudio.com with your-self-hosted-marketplace-address.example.com (or IP address), setting cacheUrl / VSCODE_GALLERY_CACHE_URL to an empty string.

There are likely other options, but the following were reported to work:

• Open VSX eclipse open-source project
  While the public instance which is run by the Eclipse Foundation is the pre-set endpoint in VSCodium, you can host your own instance.

  Open VSX is a vendor-neutral open-source alternative to the Visual Studio Marketplace. It provides a server application that manages VS Code extensions in a database, a web application similar to the VS Code Marketplace, and a command-line tool for publishing extensions similar to vsce.

• code-marketplace open-source project

  code-marketplace is a self-contained go binary that does not have a frontend or any mechanisms for extension authors to add or update extensions in the marketplace. It simply reads extensions from file storage and provides an API for VSCode compatible editors to consume.

How to use the VS Code Marketplace

As with any online service, ensure you've understood its terms of use.
Also note that this extension gallery hosts multiple extensions that are non-free and have license-agreements that explicit forbid to use them in non-Microsoft products, along with using telemetry.

The endpoint URLs are given in the example above.

---

@daiyam @stripedpajamas: Thoughts? Also:

• Please note that apart from Update README.md vscodium-insiders#4 there should be a short paragraph on VSCodium Insiders in the VSCodium readme.
• As noted in Handle Download URL for insider jeanp413/open-remote-ssh#37 I highly suggest to rename the insider repo, dropping the "s".
• Is the part "replace VSCodium by VSCodiumInsider if you use that" correct?

[daiyam]

• cacheUrl should be empty when not using Microsoft's VS Code Marketplace

• there should be a short paragraph on VSCodium Insiders in the VSCodium readme

  yes

• I will comment on the issue

• replace VSCodium by VSCodiumInsider if you use that

  No, it should be replace `VSCodium` with `VSCodium - Insiders`