From a0a77e379ecd7b929850d28ec445cd5778f8d228 Mon Sep 17 00:00:00 2001 From: Anmol Sethi Date: Thu, 14 May 2020 03:17:17 -0400 Subject: [PATCH] Add doc/guide.md --- README.md | 3 + ci/README.md | 18 +-- ci/dev/fmt.sh | 3 + doc/FAQ.md | 116 ++++++++++------- doc/guide.md | 236 ++++++++++++++++++++++++++++++++++ package.json | 3 +- src/browser/pages/vscode.html | 2 +- src/browser/register.ts | 2 +- src/node/util.ts | 11 +- src/node/wrapper.ts | 2 +- yarn.lock | 215 +++++++++++++++++++++++++++++-- 11 files changed, 537 insertions(+), 74 deletions(-) create mode 100644 doc/guide.md diff --git a/README.md b/README.md index d1e670a1..02866778 100644 --- a/README.md +++ b/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. diff --git a/ci/README.md b/ci/README.md index 892a2bf1..c21adceb 100644 --- a/ci/README.md +++ b/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 diff --git a/ci/dev/fmt.sh b/ci/dev/fmt.sh index f7c48c41..8e248823 100755 --- a/ci/dev/fmt.sh +++ b/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' diff --git a/doc/FAQ.md b/doc/FAQ.md index a4357560..087c7141 100644 --- a/doc/FAQ.md +++ b/doc/FAQ.md @@ -1,9 +1,31 @@ + + # 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) + + + ## 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`. + +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: + +```bash +# From the Coder extension marketplace +code-server --install-extension ms-python.python + +# 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. + +However, code-server is free, open source and can be ran on any machine without any limitations. + +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 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. +Please follow [./guide.md]](./guide.md) for our recommendations on setting up and using code-server. -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. - -1. https://developer.github.com/v3/guides/using-ssh-agent-forwarding/ -1. https://wiki.gnupg.org/AgentForwarding - -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. - -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. +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//`. -## 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. -1. Unix: `~/.local/share/code-server` -1. Windows: `%APPDATA%\Local\code-server\Data` +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`. + +[#1636](https://github.com/cdr/code-server/issues/1636) will make the experience here better. ## Enterprise diff --git a/doc/guide.md b/doc/guide.md new file mode 100644 index 00000000..2cc03630 --- /dev/null +++ b/doc/guide.md @@ -0,0 +1,236 @@ + + +# Setup Guide + +- [1. Acquire a remote machine](#1-acquire-a-remote-machine) + - [Requirements](#requirements) + - [Google Cloud Platform](#google-cloud-platform) +- [2. Install code-server](#2-install-code-server) +- [3. Expose code-server](#3-expose-code-server) + - [SSH forwarding](#ssh-forwarding) + - [Let's Encrypt](#lets-encrypt) + - [Self Signed Certificate](#self-signed-certificate) + - [Change the password?](#change-the-password) + - [How do I securely access development web services?](#how-do-i-securely-access-development-web-services) + + + +This guide demonstrates how to setup and use code-server. +To reiterate, code-server lets you run VS Code on a remote server and then access it via a browser. + +See the [README](../README.md) for a general overview and the [FAQ](./FAQ.md) for further user docs. + +We'll walk you through acquiring a remote machine to run code-server on and then exposing `code-server` so you can +easily access it. + +## 1. Acquire a remote machine + +First, you need a machine to run code-server on. You can use a physical +machine you have lying around or use a VM on GCP/AWS. + +### Requirements + +For a good experience, we recommend at least: + +- 1 GB of RAM +- 2 cores + +You can use whatever linux distribution floats your boat but in this guide we assume Debian. + +### Google Cloud Platform + +For demonstration purposes, this guide assumes you're using a VM on GCP but you should be +able to easily use any machine or VM provider. + +You can sign up at https://console.cloud.google.com/getting-started. You'll get a 12 month \$300 +free trial. + +Once you've signed up and created a GCP project, create a new Compute Engine VM Instance. + +1. Navigate to `Compute Engine -> VM Instances` on the sidebar +2. Now click `Create Instance` to create a new instance +3. Choose the region closest to you based on [gcping.com](http://www.gcping.com) +4. Name it whatever you want +5. Any zone is fine +6. We'd recommend a `e2-standard-2` instance from the E2 series and General-purpose family + - 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 +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 +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 + +SSH into your instance and run the appropriate commands documented in [README.md](../README.md). + +Assuming Debian: + +```bash +curl -sSOL https://github.com/cdr/code-server/releases/download/3.3.0/code-server_3.3.0_amd64.deb +sudo dpkg -i code-server_3.3.0_amd64.deb +systemctl --user enable --now code-server +# Now code-server is running at http://127.0.0.1:8080 +# Your password is in ~/.config/code-server/config.yaml +``` + +## 3. Expose code-server + +There are several approaches to operating and exposing code-server. + +Since you can gain access to a terminal from within code-server, **never**, **ever** +expose it directly to the internet without some form of authentication and encryption! + +By default, code-server will enable password authentication which will +require you to copy the password from the code-server config file to login. You +can also set a custom password with `$PASSWORD`. + +**tip**: You can list the full set of code-server options with `code-server --help` + +### SSH forwarding + +We highly recommend this approach for not requiring any additional setup, you just need an +SSH server on your remote machine. The downside is you won't be able to access `code-server` +without an SSH client like an iPad. If that's important to you, skip to [Let's Encrypt](#lets-encrypt). + +Recommended reading: https://help.ubuntu.com/community/SSH/OpenSSH/PortForwarding + +```bash +# -N disables executing a remote shell +ssh -N -L 8080:127.0.0.1:8080 +``` + +As long as this command hasn't exited, that means any request on local port 8080 goes to your +instance at `127.0.0.1:8080` which is where code-server is running. + +Next ssh into your instance and edit your code-server config file to disable password authentication. + +```bash +# Replaces "auth: password" with "auth: none" in the code-server config. +sed -i.bak 's/auth: password/auth: none/' ~/.config/code-server/config.yaml +``` + +Restart code-server with (assuming you followed the guide): + +```bash +systemctl --user restart code-server +``` + +Now if you access http://127.0.0.1:8080 locally, you should see code-server! + +If you want to make the SSH port forwarding persistent we recommend using +[mutagen](https://mutagen.io/documentation/introduction/installation). + +``` +# Same as the above SSH command but runs in the background continously. +# Add `mutagen daemon start` to your ~/.bashrc to start the mutagen daemon when you open a shell. +mutagen forward create --help -n=code-server tcp:127.0.0.1:8080 :tcp:127.0.0.1:8080 +``` + +We also recommend adding the following lines to your `~/.ssh/config` to quickly detect bricked SSH connections: + +```bash +Host * +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. + +1. https://developer.github.com/v3/guides/using-ssh-agent-forwarding/ +2. https://wiki.gnupg.org/AgentForwarding + +### Let's Encrypt + +Let's Encrypt is a great option if you want to access code-server on an iPad or just want password +based authentication. This does require that the remote machine is exposed to the internet. + +Assuming you have been following the guide, edit your instance and checkmark the allow HTTP/HTTPS traffic options. + +1. You'll need to buy a domain name. We recommend [Google Domains](https://domains.google.com) +2. Add an A record to your domain with your instance's IP +3. Install caddy https://caddyserver.com/docs/download#debian-ubuntu-raspbian + +```bash +echo "deb [trusted=yes] https://apt.fury.io/caddy/ /" \ + | sudo tee -a /etc/apt/sources.list.d/caddy-fury.list +sudo apt update +sudo apt install caddy +``` + +4. Replace `/etc/caddy/Caddyfile` with sudo to look like this: + +``` +mydomain.com + +reverse_proxy 127.0.0.1:8080 +``` + +5. Reload caddy with: + +```bash +sudo systemctl reload caddy +``` + +Visit `https://` to access code-server. Congratulations! + +In a future release we plan to integrate Let's Encrypt directly with code-server to avoid +the dependency on caddy. + +### Self Signed Certificate + +**note:** Self signed certificates do not work with iPad and will cause a blank page. You'll +have to use [Let's Encrypt](#lets-encrypt) instead. + +Recommended reading: https://security.stackexchange.com/a/8112 + +We recommend this as a last resort as self signed certificates do not work with iPads and can +cause other bizarre issues. Not to mention all the warnings when you access code-server. +Only use this if you do not want to buy a domain or cannot expose the remote machine to the internet. + +ssh into your instance and edit your code-server config file to use a randomly generated self signed certificate: + +```bash +# Replaces "cert: false" with "cert: true" in the code-server config. +sed -i.bak 's/cert: false/cert: true/' ~/.config/code-server/config.yaml +# Replaces "bind-addr: 127.0.0.1:8080" with "bind-addr: 0.0.0.0:443" in the code-server config. +sed -i.bak 's/bind-addr: 127.0.0.1:8080/bind-addr: 0.0.0.0:443/' ~/.config/code-server/config.yaml +# Allows code-server to listen on port 443. +sudo setcap cap_net_bind_service=+ep /usr/lib/code-server/lib/node +``` + +Assuming you have been following the guide, restart code-server with: + +```bash +systemctl --user restart code-server +``` + +Edit your instance and checkmark the allow HTTPS traffic option. + +Visit `https://` to access code-server. +You'll get a warning when accessing but if you click through you should be good. + +You can also use [mkcert](https://mkcert.dev) to create a self signed certificate trusted by your +OS to avoid the warnings. + +### Change the password? + +Edit the code-server config file at `~/.config/code-server/config.yaml` and then restart +code-server with: + +```bash +systemctl --user restart code-server +``` + +### How do I securely access development web services? + +If you're working on a web service and want to access it locally, code-server can proxy it for you. + +See the [FAQ](https://github.com/cdr/code-server/blob/master/doc/FAQ.md#how-do-i-securely-access-web-services). diff --git a/package.json b/package.json index aed1e9d6..713f6be8 100644 --- a/package.json +++ b/package.json @@ -45,6 +45,7 @@ "@types/ws": "^6.0.4", "@typescript-eslint/eslint-plugin": "^2.0.0", "@typescript-eslint/parser": "^2.0.0", + "doctoc": "^1.4.0", "eslint": "^6.2.0", "eslint-config-prettier": "^6.0.0", "eslint-plugin-import": "^2.18.2", @@ -52,7 +53,7 @@ "leaked-handles": "^5.2.0", "mocha": "^6.2.0", "parcel-bundler": "^1.12.4", - "prettier": "^1.18.2", + "prettier": "^2.0.5", "stylelint": "^13.0.0", "stylelint-config-recommended": "^3.0.0", "ts-node": "^8.4.1", diff --git a/src/browser/pages/vscode.html b/src/browser/pages/vscode.html index abfb102c..72c39824 100644 --- a/src/browser/pages/vscode.html +++ b/src/browser/pages/vscode.html @@ -98,7 +98,7 @@ END_PROD_ONLY -->