Rework the readme deployment section

Author: code-asher

README.md

@@ -2,51 +2,60 @@
 
 The Code Extension Marketplace is an open-source alternative to the VS Code
 Marketplace for use in editors like
-[code-server](https://github.com/cdr/code-server).
+[code-server](https://github.com/coder/code-server).
 
 This marketplace reads extensions from file storage and provides an API for
 editors to consume. It does not have a frontend or any mechanisms for extension
 authors to add or update extensions in the marketplace.
 
 ## Deployment
 
-Replace `$os` and `$arch` with your operating system and architecture.
+The marketplace is a single binary. Deployment involves running the binary,
+pointing it to a directory of extensions, and exposing the binary's bound
+address in some way.
+
+### Getting the binary
+
+The binary can be downloaded from GitHub releases. For example here is a way to
+download the latest release using `wget`. Replace `$os` and `$arch` with your
+operating system and architecture.
 
 ```
 wget https://github.com/coder/code-marketplace/releases/latest/download/code-marketplace-$os-$arch -O ./code-marketplace
 chmod +x ./code-marketplace
-./code-marketplace server --extensions-dir /my/extensions
 ```
 
-Run `./code-marketplace --help` for a full list of options.
-
-It is recommended to put the marketplace behind TLS otherwise code-server will
-reject connecting to the API.
-
-The `/healthz` endpoint can be used to determine if the marketplace is ready to
-receive requests.
+### Running the binary
 
-## Usage in code-server
+The marketplace server can be ran using the `server` sub-command.
 
 ```
-export EXTENSIONS_GALLERY='{"serviceUrl":"https://<domain>/api", "itemUrl":"https://<domain>/item", "resourceUrlTemplate": "https://<domain>/files/{publisher}/{name}/{version}/{path}"}'
-code-server
+./code-marketplace server --extensions-dir ./extensions
 ```
 
-If code-server reports content security policy errors ensure that the
-marketplace is running behind an https URL.
+Run `./code-marketplace --help` for a full list of options.
+
+### Exposing the marketplace
 
-## Reverse proxy
+The marketplace must be put behind TLS otherwise code-server will reject
+connecting to the API. This could mean using a reverse proxy like NGINX or Caddy
+with your own domain and certificates or using a service like Cloudflare.
 
-To host the marketplace behind a reverse proxy set either the `Forwarded` header
-or both the `X-Forwarded-Host` and `X-Forwarded-Proto` headers.
+When hosting the marketplace behind a reverse proxy set either the `Forwarded`
+header or both the `X-Forwarded-Host` and `X-Forwarded-Proto` headers. These are
+used to generate absolute URLs to extension assets in API responses.
 
 The marketplace does not support being hosted behind a base path; it must be
 proxied at the root of your domain.
 
+### Health checks
+
+The `/healthz` endpoint can be used to determine if the marketplace is ready to
+receive requests.
+
 ## Adding extensions
 
-Extensions can be added to the marketplace by file or URL.  The extensions
+Extensions can be added to the marketplace by file or URL. The extensions
 directory does not need to be created beforehand.
 
 ```
@@ -77,6 +86,16 @@ Or the Vim extension from GitHub:
 ./code-marketplace add https://github.com/VSCodeVim/Vim/releases/download/v1.24.1/vim-1.24.1.vsix --extensions-dir ./extensions
 ```
 
+## Usage in code-server
+
+```
+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 the
+marketplace is running behind an https URL.
+
 ## Development
 
 ```