From 42b5152888d63d8426d881389f8035bcbd4dbf79 Mon Sep 17 00:00:00 2001 From: Anmol Sethi Date: Thu, 21 May 2020 23:53:02 -0400 Subject: [PATCH] Further documentation cleanup --- README.md | 3 ++- doc/FAQ.md | 55 +++++++++++++++++++++++++------------------------- doc/guide.md | 20 +++++++++--------- doc/install.md | 51 ++++++++++++++++++++++++---------------------- install.sh | 46 +++++++++++++++++------------------------ 5 files changed, 86 insertions(+), 89 deletions(-) diff --git a/README.md b/README.md index e396fa61d..b1a485320 100644 --- a/README.md +++ b/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: diff --git a/doc/FAQ.md b/doc/FAQ.md index 8fc013e09..ebecf919b 100644 --- a/doc/FAQ.md +++ b/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) @@ -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//`. + ### 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 Now you can browse to `.`. 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//`. - ## 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 diff --git a/doc/guide.md b/doc/guide.md index 0e2523a57..6db6a4929 100644 --- a/doc/guide.md +++ b/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 diff --git a/doc/install.md b/doc/install.md index 12802531e..7ae35c74b 100644 --- a/doc/install.md +++ b/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. diff --git a/install.sh b/install.sh index 202bd12e3..35dbaa547 100755 --- a/install.sh +++ b/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 -- -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 =~/.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)"