Add doc/guide.md

Author: nhooyr

README.md

@@ -35,6 +35,9 @@ systemctl --user enable --now code-server
 
 ### npm
 
+We recommend installing from `npm` if we don't have a precompiled release for your machine's
+platform or architecture.
+
 **note:** Installing via `npm` requires certain dependencies for the native module builds.
 See [./doc/npm.md](./doc/npm.md) for installing these dependencies.
 

ci/README.md

@@ -10,19 +10,19 @@ Any file and directory added into this tree should be documented here.
 
 Make sure you have `$GITHUB_TOKEN` set and [hub](https://github.com/github/hub) installed.
 
-1. Update the version of code-server in `package.json` and README.md install examples and push a commit
-1. GitHub actions will generate the `npm-package` and `release-packages` artifacts
-1. Run `yarn release:github-draft` to create a GitHub draft release from the template with
+1. Update the version of code-server in `package.json` and README.md/guide.md install examples and push a commit
+2. GitHub actions will generate the `npm-package` and `release-packages` artifacts
+3. Run `yarn release:github-draft` to create a GitHub draft release from the template with
    the updated version.
    1. Summarize the major changes in the release notes and link to the relevant issues.
-1. Wait for the artifacts in step 2 to build
-1. Run `yarn release:github-assets` to download the artifacts and then upload them to the draft release
-1. Run some basic sanity tests on one of the released packages
-1. Publish the release
+4. Wait for the artifacts in step 2 to build
+5. Run `yarn release:github-assets` to download the artifacts and then upload them to the draft release
+6. Run some basic sanity tests on one of the released packages
+7. Publish the release
    1. CI will automatically grab the artifacts and then
       1. Publish the NPM package
-      1. Publish the AMD64 docker image
-      1. Publish the ARM64 docker image
+      2. Publish the AMD64 docker image
+      3. Publish the ARM64 docker image
 
 ## dev
 

ci/dev/fmt.sh

@@ -21,6 +21,9 @@ main() {
   )
   prettier --write --loglevel=warn $(git ls-files "${prettierExts[@]}")
 
+  doctoc --title '# FAQ' doc/FAQ.md > /dev/null
+  doctoc --title '# Setup Guide' doc/guide.md > /dev/null
+
   if [[ ${CI-} && $(git ls-files --other --modified --exclude-standard) ]]; then
     echo "Files need generation or are formatted incorrectly:"
     git -c color.ui=always status | grep --color=no '\[31m'

doc/FAQ.md

@@ -1,9 +1,31 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 # FAQ
 
+- [Questions?](#questions)
+- [What's the deal with extensions?](#whats-the-deal-with-extensions)
+- [Where are extensions stored?](#where-are-extensions-stored)
+- [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)
+- [Multi Tenancy](#multi-tenancy)
+- [Docker in code-server docker container?](#docker-in-code-server-docker-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)
+- [How do I debug issues with code-server?](#how-do-i-debug-issues-with-code-server)
+- [Heartbeat file](#heartbeat-file)
+- [Enterprise](#enterprise)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Questions?
 
-Please file all questions and support requests at https://www.reddit.com/r/codeserver/
-The issue tracker is only for bugs.
+Please file all questions and support requests at https://www.reddit.com/r/codeserver/.
+
+The issue tracker is **only** for bugs.
 
 ## What's the deal with extensions?
 
@@ -23,42 +45,53 @@ Issue [#1299](https://github.com/cdr/code-server/issues/1299) is a big one in ma
 better by allowing the community to submit extensions and repos to avoid waiting until the scraper finds
 an extension.
 
-If an extension does not work, try to grab its VSIX from its Github releases or build it yourself and
-copy it to the extensions folder.
+If an extension is not available or does not work, you can grab its VSIX from its Github releases or
+build it yourself and [Install from VSIX](https://code.visualstudio.com/docs/editor/extension-gallery#_install-from-a-vsix).
 
-## How is this different from VS Code Online?
+Feel free to file an issue to add a missing extension to the marketplace.
 
-VS Code Online is a closed source managed service by Microsoft and only runs on Azure.
+## Where are extensions stored?
 
-code-server is open source and can be freely run on any machine.
+Defaults to `~/.local/share/code-server/extensions`.
 
-## How should I expose code-server to the internet?
+If the `XDG_DATA_HOME` environment variable is set the data directory will be
+`$XDG_DATA_HOME/code-server/extensions`.
+
+You can install an extension on the CLI with:
 
-By far the most secure method of using code-server is via
-[sshcode](https://github.com/codercom/sshcode) as it runs code-server and then forwards
-its port over SSH and requires no setup on your part other than having a working SSH server.
+```bash
+# From the Coder extension marketplace
+code-server --install-extension ms-python.python
 
-You can also forward your SSH key and GPG agent to the remote machine to securely access GitHub
-and securely sign commits without duplicating your keys onto the the remote machine.
+# From a downloaded VSIX on the file system
+code-server --install-extension downloaded-ms-python.python.vsix
+```
+
+## How is this different from VS Code Codespaces?
+
+VS Code Codespaces is a closed source and paid service by Microsoft. It also allows you to access
+VS Code via the browser.
 
-1. https://developer.github.com/v3/guides/using-ssh-agent-forwarding/
-1. https://wiki.gnupg.org/AgentForwarding
+However, code-server is free, open source and can be ran on any machine without any limitations.
 
-If you cannot use sshcode, then you will need to ensure there is some sort of authorization in
-front of code-server and that you are using HTTPS to secure all connections.
+While you can self host environments with VS Code Codespaces, you still need to an Azure billing
+account and you access VS Code via the Codespaces web dashboard instead of directly connecting to
+your instance.
+
+## How should I expose code-server to the internet?
 
-By default when listening externally, code-server enables password authentication using a
-randomly generated password so you can use that. You can set the `PASSWORD` environment variable
-to use your own instead. If you want to handle authentication yourself, use `--auth none`
-to disable password authentication.
+Please follow [./guide.md]](./guide.md) for our recommendations on setting up and using code-server.
+
+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 you should handle this with a reverse
-proxy using something like [oauth2_proxy](https://github.com/pusher/oauth2_proxy).
+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).
 
-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`.
+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`.
 
 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
@@ -67,6 +100,8 @@ only to HTTP requests.
 You can use [Let's Encrypt](https://letsencrypt.org/) to get an SSL certificate
 for free.
 
+Again, Please follow [./guide.md]](./guide.md) for our recommendations on setting up and using code-server.
+
 ## How do I securely access web services?
 
 code-server is capable of proxying to any port using either a subdomain or a
@@ -96,15 +131,6 @@ ensure your reverse proxy forwards that information if you are using one.
 
 Just browse to `/proxy/<port>/`.
 
-## x86 releases?
-
-node has dropped support for x86 and so we decided to as well. See
-[nodejs/build/issues/885](https://github.com/nodejs/build/issues/885).
-
-## Alpine builds?
-
-Just install `libc-dev` and code-server should work.
-
 ## Multi Tenancy
 
 If you want to run multiple code-server's on shared infrastructure, we recommend using virtual
@@ -127,8 +153,9 @@ to make volume mounts in any other directory work.
 
 ## Collaboration
 
-At the moment we have no plans for multi user collaboration on code-server but we understand there is strong
-demand and will work on it when the time is right.
+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).
 
 ## How can I disable telemetry?
 
@@ -165,13 +192,16 @@ information from the following places:
 Additionally, collecting core dumps (you may need to enable them first) if
 code-server crashes can be helpful.
 
-### Where is the data directory?
+## Heartbeat file
 
-If the `XDG_DATA_HOME` environment variable is set the data directory will be
-`$XDG_DATA_HOME/code-server`. Otherwise:
+`code-server` touches `~/.local/share/code-server/heartbeat` once a minute as long
+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 continously checking the last modified time on the heartbeat file and if it is
+older than X minutes, you should kill `code-server`.
 
-1. Unix: `~/.local/share/code-server`
-1. Windows: `%APPDATA%\Local\code-server\Data`
+[#1636](https://github.com/cdr/code-server/issues/1636) will make the experience here better.
 
 ## Enterprise