Further documentation cleanup

README.md

@@ -17,7 +17,8 @@ Run [VS Code](https://github.com/Microsoft/vscode) on any machine anywhere and a
 
 For a full setup and walkthrough, please see [./doc/guide.md](./doc/guide.md).
 
-[We have a script](./install.sh) to install code-server for Linux or macOS.
+[We have a script](./install.sh) to install code-server for Linux and macOS.
+
 It tries to use the system package manager if possible.
 
 First run to print out the install process:

doc/FAQ.md

@@ -8,10 +8,10 @@
 - [How is this different from VS Code Codespaces?](#how-is-this-different-from-vs-code-codespaces)
 - [How should I expose code-server to the internet?](#how-should-i-expose-code-server-to-the-internet)
 - [How do I securely access web services?](#how-do-i-securely-access-web-services)
-  - [Sub-domains](#sub-domains)
   - [Sub-paths](#sub-paths)
+  - [Sub-domains](#sub-domains)
 - [Multi-tenancy](#multi-tenancy)
-- [Docker in code-server docker container?](#docker-in-code-server-docker-container)
+- [Docker in code-server container?](#docker-in-code-server-container)
 - [Collaboration](#collaboration)
 - [How can I disable telemetry?](#how-can-i-disable-telemetry)
 - [How does code-server decide what workspace or folder to open?](#how-does-code-server-decide-what-workspace-or-folder-to-open)
@@ -19,7 +19,7 @@
 - [Heartbeat File](#heartbeat-file)
 - [How does the config file work?](#how-does-the-config-file-work)
 - [Blank screen on iPad?](#blank-screen-on-ipad)
-- [Isn't an install script insecure?](#isnt-an-install-script-insecure)
+- [Isn't an install script piped into sh insecure?](#isnt-an-install-script-piped-into-sh-insecure)
 - [Enterprise](#enterprise)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -40,23 +40,23 @@ See https://cdn.vsassets.io/v/M146_20190123.39/_content/Microsoft-Visual-Studio-
 > Marketplace Offerings are intended for use only with Visual Studio Products and Services
 > and you may only install and use Marketplace Offerings with Visual Studio Products and Services.
 
-As a result, Coder has created its own marketplace for open source extensions. It works by scraping
-GitHub for VS Code extensions and building them. It's not perfect but getting better by the day with
-more and more extensions.
+As a result, [Coder](https://coder.com) has created its own marketplace for open source extensions.
+It works by scraping GitHub for VS Code extensions and building them. It's not perfect but getting
+better by the day with more and more extensions.
 
 Issue [#1299](https://github.com/cdr/code-server/issues/1299) is a big one in making the experience here
 better by allowing the community to submit extensions and repos to avoid waiting until the scraper finds
 an extension.
 
+To request an extension for the code-server marketplace, please open a new issue
+and select the `Extension request` template.
+
 If an extension is not available or does not work, you can grab its VSIX from its Github releases or
 build it yourself. Then run the `Extensions: Install from VSIX` command in the Command Palette and
 point to the .vsix file.
 
 See below for installing an extension from the cli.
 
-To request an extension for the code-server marketplace, please open a new issue
-and select the `Extension request` template.
-
 If you have your own custom marketplace, it is possible to point code-server to it by setting
 `$SERVICE_URL` and `$ITEM_URL` to point to it.
 
@@ -97,17 +97,17 @@ code-server only supports password authentication natively.
 **note**: code-server will rate limit password authentication attempts at 2 a minute and 12 an hour.
 
 If you want to use external authentication (i.e sign in with Google) you should handle this
-with a reverse proxy using something like [oauth2_proxy](https://github.com/pusher/oauth2_proxy).
+with a reverse proxy using something like [oauth2_proxy](https://github.com/pusher/oauth2_proxy)
+or [Cloudflare Access](https://teams.cloudflare.com/access).
 
 For HTTPS, you can use a self signed certificate by passing in just `--cert` or
 pass in an existing certificate by providing the path to `--cert` and the path to
-its key with `--cert-key`.
+the key with `--cert-key`.
 
 If `code-server` has been passed a certificate it will also respond to HTTPS
-requests and will redirect all HTTP requests to HTTPS. Otherwise it will respond
-only to HTTP requests.
+requests and will redirect all HTTP requests to HTTPS.
 
-You can use [Let's Encrypt](https://letsencrypt.org/) to get an SSL certificate
+You can use [Let's Encrypt](https://letsencrypt.org/) to get a TLS certificate
 for free.
 
 Again, please follow [./guide.md](./guide.md) for our recommendations on setting up and using code-server.
@@ -118,6 +118,10 @@ code-server is capable of proxying to any port using either a subdomain or a
 subpath which means you can securely access these services using code-server's
 built-in authentication.
 
+### Sub-paths
+
+Just browse to `/proxy/<port>/`.
+
 ### Sub-domains
 
 You will need a DNS entry that points to your server for each port you want to
@@ -137,24 +141,19 @@ code-server --proxy-domain <domain>
 Now you can browse to `<port>.<domain>`. Note that this uses the host header so
 ensure your reverse proxy forwards that information if you are using one.
 
-### Sub-paths
-
-Just browse to `/proxy/<port>/`.
-
 ## Multi-tenancy
 
 If you want to run multiple code-servers on shared infrastructure, we recommend using virtual
 machines with a VM per user. This will easily allow users to run a docker daemon. If you want
 to use kubernetes, you'll definitely want to use [kubevirt](https://kubevirt.io) to give each
-user a virtual machine instead of just a container. Docker in docker while supported requires
-privileged containers which are a security risk in a multi tenant infrastructure.
+user a virtual machine instead of just a container.
 
-## Docker in code-server docker container?
+## Docker in code-server container?
 
-If you'd like to access docker inside of code-server, we'd recommend running a docker:dind container
-and mounting in a directory to share between dind and the code-server container at /var/run. After, install
-the docker CLI in the code-server container and you should be able to access the daemon as the socket
-will be shared at /var/run/docker.sock.
+If you'd like to access docker inside of code-server, we'd recommend running a `docker:dind` container
+and mounting in a directory to share between `dind` and the `code-server` container at `/var/run`.
+After, install the docker CLI in the code-server container and you should be able to access the
+daemon as the socket will be shared at `/var/run/docker.sock`.
 
 In order to make volume mounts work, mount the home directory in the code-server container and the
 dind container at the same path. i.e you'd volume mount a directory from the host to `/home/coder`
@@ -165,7 +164,7 @@ to make volume mounts in any other directory work.
 
 We understand the high demand but the team is swamped right now.
 
-You can follow progress at [#33](https://github.com/cdr/code-server/issues/33).
+You can subscribe to [#33](https://github.com/cdr/code-server/issues/33) for updates.
 
 ## How can I disable telemetry?
 
@@ -208,7 +207,7 @@ as there is an active browser connection.
 
 If you want to shutdown `code-server` if there hasn't been an active connection in X minutes
 you can do so by continuously checking the last modified time on the heartbeat file and if it is
-older than X minutes, you should kill `code-server`.
+older than X minutes, kill `code-server`.
 
 [#1636](https://github.com/cdr/code-server/issues/1636) will make the experience here better.
 
@@ -243,7 +242,7 @@ certificate using the CA and then import the CA onto your iPad.
 
 See [#1566](https://github.com/cdr/code-server/issues/1566#issuecomment-623159434).
 
-## Isn't an install script insecure?
+## Isn't an install script piped into sh insecure?
 
 Please give
 [this wonderful blogpost](https://sandstorm.io/news/2015-09-24-is-curl-bash-insecure-pgp-verified-install) by

doc/guide.md

@@ -24,8 +24,8 @@ Further docs are at:
 - [FAQ.md](./FAQ.md) for common questions.
 - [CONTRIBUTING.md](../doc/CONTRIBUTING.md) for development docs
 
-We'll walk you through acquiring a remote machine to run code-server on and then exposing `code-server` so you can
-securely access it.
+We'll walk you through acquiring a remote machine to run code-server on
+and then exposing `code-server` so you can securely access it.
 
 ## 1. Acquire a remote machine
 
@@ -60,7 +60,7 @@ Once you've signed up and created a GCP project, create a new Compute Engine VM
    - Change the type to custom and set at least 2 cores and 2 GB of ram.
    - Add more vCPUs and memory as you prefer, you can edit after creating the instance as well.
    - https://cloud.google.com/compute/docs/machine-types#general_purpose
-7. We highly recommend switching the persistent disk to a SSD of at least 32 GB.
+7. We highly recommend switching the persistent disk to an SSD of at least 32 GB.
    - Click `Change` under `Boot Disk` and change the type to `SSD Persistent Disk` and the size
      to `32`.
    - You can always grow your disk later.
@@ -68,16 +68,18 @@ Once you've signed up and created a GCP project, create a new Compute Engine VM
 8. Navigate to `Networking -> Network interfaces` and edit the existing interface
    to use a static external IP.
    - Click done to save network interface changes.
-9. If you do not have a [project wide SSH key](https://cloud.google.com/compute/docs/instances/adding-removing-ssh-keys#project-wide), navigate to `Security - > SSH Keys` and add your public key there.
+9. If you do not have a [project wide SSH key](https://cloud.google.com/compute/docs/instances/adding-removing-ssh-keys#project-wide), navigate to `Security -> SSH Keys` and add your public key there.
 10. Click create!
 
 Remember, you can shutdown your server when not in use to lower costs.
+
 We highly recommend learning to use the [`gcloud`](https://cloud.google.com/sdk/gcloud) cli
 to avoid the slow dashboard.
 
 ## 2. Install code-server
 
-[We have a script](./install.sh) to install code-server for Linux or macOS.
+[We have a script](./install.sh) to install code-server for Linux and macOS.
+
 It tries to use the system package manager if possible.
 
 First run to print out the install process:
@@ -158,8 +160,8 @@ ServerAliveInterval 5
 ExitOnForwardFailure yes
 ```
 
-You can also forward your SSH key and GPG agent to the instance to securely access GitHub
-and sign commits without copying your keys onto the instance.
+You can also forward your SSH and GPG agent to the instance to securely access GitHub
+and sign commits without copying your keys.
 
 1. https://developer.github.com/v3/guides/using-ssh-agent-forwarding/
 2. https://wiki.gnupg.org/AgentForwarding
@@ -244,8 +246,8 @@ fields.
 
 ### Change the password?
 
-Edit the code-server config file at `~/.config/code-server/config.yaml` and then restart
-code-server with:
+Edit the `password` field in the code-server config file at `~/.config/code-server/config.yaml`
+and then restart code-server with:
 
 ```bash
 systemctl --user restart code-server

doc/install.md

@@ -3,6 +3,8 @@
 # Install
 
 - [install.sh](#installsh)
+  - [Flags](#flags)
+  - [Installation reference](#installation-reference)
 - [Debian, Ubuntu](#debian-ubuntu)
 - [Fedora, CentOS, RHEL, SUSE](#fedora-centos-rhel-suse)
 - [Arch Linux](#arch-linux)
@@ -18,7 +20,8 @@ various distros and operating systems.
 
 ## install.sh
 
-[We have a script](./install.sh) to install code-server for Linux or macOS.
+[We have a script](./install.sh) to install code-server for Linux and macOS.
+
 It tries to use the system package manager if possible.
 
 First run to print out the install process:
@@ -35,39 +38,39 @@ curl -fsSL https://code-server.dev/install.sh | sh
 
 The script will print out how to run and start using code-server.
 
+If you believe an install script used with `curl | sh` is insecure, please give
+[this wonderful blogpost](https://sandstorm.io/news/2015-09-24-is-curl-bash-insecure-pgp-verified-install) by
+[sandstorm.io](https://sandstorm.io) a read.
+
+If you'd still prefer manual installation despite the below [reference](#reference) and `--dry-run`
+then continue on for docs on manual installation. The [`install.sh`](./install.sh) script runs the _exact_ same
+commands presented in the rest of this document.
+
+### Flags
+
+- `--dry-run` to echo the commands for the install process without running them.
+- `--static` to install a static release into `~/.local`.
+- `--static=/usr/local` to install a static release system wide.
+- `--version=X.X.X` to install version `X.X.X` instead of latest.
+- `--help` to see full usage docs.
+
+### Reference
+
 - For Debian, Ubuntu and Raspbian it will install the latest deb package.
 - For Fedora, CentOS, RHEL and openSUSE it will install the latest rpm package.
 - For Arch Linux it will install the AUR package.
-- For any unrecognized Linux operating system it will install the latest static release into `~/.local`
+- For any unrecognized Linux operating system it will install the latest static release into `~/.local`.
 
   - Add `~/.local/bin` to your `$PATH` to run code-server.
 
 - For macOS it will install the Homebrew package.
 
-  - If Homebrew is not installed it will install the latest static release into `~/.local`
+  - If Homebrew is not installed it will install the latest static release into `~/.local`.
   - Add ~/.local/bin to your \$PATH to run code-server.
 
 - If ran on an architecture with no binary releases, it will install the npm package with `yarn` or `npm`.
   - We only have binary releases for amd64 and arm64 presently.
 
-Pass `--dry-run` to echo the commands for the install process without running them.
-
-Pass `--static` to install a static release into `~/.local`.
-
-Pass `--static=/usr/local` to install a static release system wide.
-
-Pass `--version=X.X.X` to install version `X.X.X` instead of latest.
-
-Pass `--help` to see full usage docs.
-
-If you believe an install script used via curl is insecure, please give
-[this wonderful blogpost](https://sandstorm.io/news/2015-09-24-is-curl-bash-insecure-pgp-verified-install) by
-[sandstorm.io](https://sandstorm.io) a read.
-
-If you'd still prefer manual installation despite the above explanations and `--dry-run`
-then continue for docs on manual installation. The [`install.sh`](./install.sh) script runs the *exact* same
-commands depicted in the rest of this document.
-
 ## Debian, Ubuntu
 
 ```bash
@@ -106,10 +109,10 @@ systemctl --user enable --now code-server
 
 ## yarn, npm
 
-We recommend installing with `yarn` or `npm` if:
+We recommend installing with `yarn` or `npm` when:
 
-1. You aren't using `amd64` or `arm64`.
-2. glibc < v2.17
+1. You aren't on `amd64` or `arm64`.
+2. If you're on Linux with glibc < v2.17
 
 **note:** Installing via `yarn` or `npm` builds native modules on install and so requires C dependencies.
 See [./doc/npm.md](./doc/npm.md) for installing these dependencies.

install.sh

@@ -6,25 +6,30 @@ usage() {
   if [ "$0" = sh ]; then
     cli="curl -fsSL https://code-server.dev/install.sh | sh -s --"
   else
-    curl_usage="$(
-      cat << EOF
-
-To use latest:
-
-  curl -fsSL https://code-server.dev/install.sh | sh -s -- <args>
-EOF
-    )""
-"
+    curl_usage="The latest script is available at https://code-server.dev/install.sh"
   fi
   cat << EOF
 Installs code-server for Linux or macOS.
 It tries to use the system package manager if possible.
 After successful installation it explains how to start using code-server.
+${curl_usage-}
 
 Usage:
 
   $cli [--dry-run] [--version X.X.X] [--static <install-prefix>=~/.local]
-${curl_usage-}
+
+    --dry-run Echo the commands for the install process without running them.
+
+    --version Install a specific version instead of the latest release.
+
+    --static  Install a static release into ~/.local
+
+              The release will be unarchived into ~/.local/lib/code-server.X.X.X
+              and the binary symlinked into ~/.local/bin/code-server.
+              Add ~/.local/bin to your \$PATH to use it.
+
+              To install system wide pass ---static=/usr/local
+
 - For Debian, Ubuntu and Raspbian it will install the latest deb package.
 - For Fedora, CentOS, RHEL and openSUSE it will install the latest rpm package.
 - For Arch Linux it will install the AUR package.
@@ -41,20 +46,7 @@ ${curl_usage-}
   npm package with yarn or npm.
   - We only have binary releases for amd64 and arm64 presently.
 
-    --dry-run Echo the commands for the install process without running them.
-
-    --version Install a specific version instead of the latest release.
-
-    --static  Install a static release into ~/.local
-
-              code-server will be unarchived into ~/.local/lib/code-server.X.X.X
-              and the binary will be symlinked into ~/.local/bin/code-server.
-              You will need to add ~/.local/bin to your \$PATH to use it without
-              the full path.
-
-              To install system wide set the prefix to /usr/local.
-
-https://github.com/cdr/code-server/blob/master/doc/install.md
+More installation docs are at https://github.com/cdr/code-server/blob/master/doc/install.md
 EOF
 }
 
@@ -123,7 +115,7 @@ main() {
     --version=*)
       VERSION="$(parse_arg "$@")"
       ;;
-    -h | --h | --help)
+    -h | --help)
       usage
       exit 0
       ;;
@@ -152,11 +144,11 @@ main() {
   if [ ! "$ARCH" ]; then
     if [ "${STATIC-}" ]; then
       echoerr "No static releases available for the architecture $(uname -m)."
-      echoerr "Please rerun without the -s flag to install from npm."
+      echoerr "Please rerun without the --static flag to install from npm."
       exit 1
     fi
     install_npm
-    exit 0
+    return
   fi
 
   CACHE_DIR="$(echo_cache_dir)"