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.

Runmake build to generate the updated binary. Commit and get the new image tag and make changes to the appropriate deployment.

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]

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.

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

• VS Code
• VSCodium

    export VSCODE_GALLERY_SERVICE_URL="https://<domain>/api  export 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.