Repository files navigation

The Code Extension Marketplace is an open-source alternative to the VS CodeMarketplace for use in editors likecode-server orVSCodium.

It is maintained byCoder and is used by our enterprisecustomers in regulated and security-conscious industries like banking, assetmanagement, military, and intelligence where they deploy Coder in an air-gappednetwork and accessing an internet-hosted marketplace is not allowed.

This marketplace reads extensions from file storage and provides an API foreditors to consume. It does not have a frontend or any mechanisms for extensionauthors to add or update extensions in the marketplace.

The marketplace is a single binary. Deployment involves running the binary,pointing it to a directory of extensions, and exposing the binary's boundaddress in some way.

If deploying with Kubernetes see theHelm directory otherwise read on.

The binary can be downloaded from GitHub releases. For example here is a way todownload the latest release usingwget. Replace$os and$arch with youroperating system and architecture.

wget https://github.com/coder/code-marketplace/releases/latest/download/code-marketplace-$os-$arch -O ./code-marketplacechmod +x ./code-marketplace

The marketplace server can be ran using theserver sub-command.

./code-marketplace server [flags]

Run./code-marketplace --help for a full list of options.

To use a local directory for extension storage use the--extensions-dir flag.

./code-marketplace [command] --extensions-dir ./extensions

It is possible use Artifactory as a file store instead of local storage. Forthis to work theARTIFACTORY_TOKEN environment variable must be set.

export ARTIFACTORY_TOKEN="my-token"./code-marketplace [command] --artifactory http://artifactory.server/artifactory --repo extensions

The token will be used in theAuthorization header with the valueBearer <TOKEN>.

The marketplace must be put behind TLS otherwise code-server will rejectconnecting to the API. This could mean using a TLS-terminating reverse proxylike NGINX or Caddy with your own domain and certificates or using a servicelike Cloudflare.

When hosting the marketplace behind a reverse proxy set either theForwardedheader or both theX-Forwarded-Host andX-Forwarded-Proto headers. Theseheaders are used to generate absolute URLs to extension assets in API responses.One way to test this is to make a query and check one of the URLs in theresponse:

curl 'https://example.com/api/extensionquery' -H 'Accept: application/json;api-version=3.0-preview.1' --compressed -H 'Content-Type: application/json' --data-raw '{"filters":[{"criteria":[{"filterType":8,"value":"Microsoft.VisualStudio.Code"}],"pageSize":1}],"flags":439}' | jq .results[0].extensions[0].versions[0].assetUri"https://example.com/assets/vscodevim/vim/1.24.1"

The marketplace does not support being hosted behind a base path; it must beproxied at the root of your domain.

The/healthz endpoint can be used to determine if the marketplace is ready toreceive requests.

Extensions can be added to the marketplace by file, directory, or web URL.

./code-marketplace add extension.vsix [flags]./code-marketplace add extension-vsixs/ [flags]./code-marketplace add https://domain.tld/extension.vsix [flags]

If the extension has dependencies or is in an extension pack those details willbe printed. Extensions listed as dependencies must also be added but extensionsin a pack are optional.

If an extension is open source you can get it from one of three locations:

1. GitHub releases (if the extension publishes releases to GitHub).
2. Open VSX (if the extension is published to Open VSX).
3. Building from source.

For example to add the Python extension from Open VSX:

./code-marketplace add https://open-vsx.org/api/ms-python/python/2022.14.0/file/ms-python.python-2022.14.0.vsix [flags]

Or the Vim extension from GitHub:

./code-marketplace add https://github.com/VSCodeVim/Vim/releases/download/v1.24.1/vim-1.24.1.vsix [flags]

Extensions can be removed from the marketplace by ID and version or--all toremove all versions.

./code-marketplace remove ms-python.python@2022.14.0 [flags]./code-marketplace remove ms-python.python --all [flags]

The marketplace does not utilize a database. When an extension query is made,the marketplace scans the local file system or queries Artifactory on demand tofind all the available extensions.

However, for Artifactory in particular this can be slow, so this full list ofextensions is cached in memory for a default of one minute and reused for anysubsequent requests that fall within that duration. This duration can beconfigured or disabled with--list-cache-duration and applies to both storagebackends.

This means that when you add or remove an extension, depending on when the lastrequest was made, it can take a duration between zero and--list-cache-duration for the query response to reflect that change.

Artifactory storage also uses a second in-memory cache for extension manifests,which are referenced in extension queries (for things like categories). Thiscache is initially populated with all available extension manifests on startup.Extensions added after the server is running are added to the cache on-demandthe next time extensions are scanned.

The manifest cache has no expiration and never evicts manifests because it wasexpected that extensions are typically only ever added and individual extensionversion manifests never change; however we would like to implement evictingmanifests of extensions that have been removed.

With local storage, manifests are read directly from the file system ondemand. Requests for other extension assets (such as icons) for both storagebackends have no cache and are read/proxied directly from the file system orArtifactory since they are not in the extension query hot path.

You can point code-server to your marketplace by setting theEXTENSIONS_GALLERY environment variable.

The value of this variable is a JSON blob that specifies the service URL, itemURL, and resource URL template.

• serviceURL: specifies the location of the API (https://<domain>/api).
• itemURL: the frontend for extensions which is currently just a mostly blankpage that says "not supported" (https://<domain>/item)
• resourceURLTemplate: used to download web extensions like Vim; code-serveritself will replace the{publisher},{name},{version}, and{path}template variables so use them verbatim(https://<domain>/files/{publisher}/{name}/{version}/{path}).

For example (replace<domain> with your marketplace's domain):

export EXTENSIONS_GALLERY='{"serviceUrl":"https://<domain>/api", "itemUrl":"https://<domain>/item", "resourceUrlTemplate": "https://<domain>/files/{publisher}/{name}/{version}/{path}"}'code-server

If code-server reports content security policy errors ensure that themarketplace is running behind an https URL.

If you are using a custom certificate authority or a self-signed certificate andget errors like "unable to verify the first certificate", you may need to settheNODE_EXTRA_CA_CERTSenvironment variable for code-server to find your certificates bundle.

Make sure your bundle contains the full certificate chain. This can be necessarybecause Node does not read system certificates by default and while VS Code hascode for reading them, it appears not to work or be enabled for the web version.

Some so-called "web" extensions (likevscodevim.vim) are installed in thebrowser, and extension searches are also performed from the browser, so yourcertificate bundle may also need to be installed on the client machine inaddition to the remote machine.

Although not officially supported, you can follow the examples below to startusing code-marketplace with VS Code and VSCodium:

• VS Code

  Extension signing may have to be disabled in VS Code.

• VSCodium

  export VSCODE_GALLERY_SERVICE_URL="https://<domain>/apiexport VSCODE_GALLERY_ITEM_URL="https://<domain>/item"# Or set a product.json file in `~/.config/VSCodium/product.json`codium

• Recommended extensions.
• Featured extensions.
• Download counts.
• Ratings.
• Searching by popularity.
• Published, released, and updated dates for extensions (for example this willcause bogus release dates to show for versions).
• Frontend for browsing available extensions.
• Extension validation (only the marketplace owner can add extensions anyway).
• Adding and updating extensions by extension authors.

• Bulk add from one Artifactory repository to another (or to itself).
• Optional database to speed up queries.
• Progress indicators when adding/removing extensions.