bughz
/
code-server
mirror of https://github.com/coder/code-server.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Further documentation cleanup

This commit is contained in:
Anmol Sethi 2020-05-21 23:53:02 -04:00
parent 7dcfde7329
commit 42b5152888
No known key found for this signature in database
GPG Key ID: 8CEF1878FF10ADEB
5 changed files with 86 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
README.md
View File

@ -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). 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. It tries to use the system package manager if possible.
First run to print out the install process: First run to print out the install process:

55
doc/FAQ.md
View File

@ -8,10 +8,10 @@
- [How is this different from VS Code Codespaces?](#how-is-this-different-from-vs-code-codespaces) - [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 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) - [How do I securely access web services?](#how-do-i-securely-access-web-services)
- [Sub-domains](#sub-domains)
- [Sub-paths](#sub-paths) - [Sub-paths](#sub-paths)
- [Sub-domains](#sub-domains)
- [Multi-tenancy](#multi-tenancy) - [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) - [Collaboration](#collaboration)
- [How can I disable telemetry?](#how-can-i-disable-telemetry) - [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 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) - [Heartbeat File](#heartbeat-file)
- [How does the config file work?](#how-does-the-config-file-work) - [How does the config file work?](#how-does-the-config-file-work)
- [Blank screen on iPad?](#blank-screen-on-ipad) - [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) - [Enterprise](#enterprise)
<!-- END doctoc generated TOC please keep comment here to allow auto update --> <!-- 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 > 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. > 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 As a result, [Coder](https://coder.com) has created its own marketplace for open source extensions.
GitHub for VS Code extensions and building them. It's not perfect but getting better by the day with It works by scraping GitHub for VS Code extensions and building them. It's not perfect but getting
more and more extensions. 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 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 better by allowing the community to submit extensions and repos to avoid waiting until the scraper finds
an extension. 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 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 build it yourself. Then run the `Extensions: Install from VSIX` command in the Command Palette and
point to the .vsix file. point to the .vsix file.
See below for installing an extension from the cli. 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 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. `$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. **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 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 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 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 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 requests and will redirect all HTTP requests to HTTPS.
only to HTTP requests.
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. for free.
Again, please follow [./guide.md](./guide.md) for our recommendations on setting up and using code-server. 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 subpath which means you can securely access these services using code-server's
built-in authentication. built-in authentication.
### Sub-paths
Just browse to `/proxy/<port>/`.
### Sub-domains ### Sub-domains
You will need a DNS entry that points to your server for each port you want to 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 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. ensure your reverse proxy forwards that information if you are using one.
### Sub-paths
Just browse to `/proxy/<port>/`.
## Multi-tenancy ## Multi-tenancy
If you want to run multiple code-servers on shared infrastructure, we recommend using virtual 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 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 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 user a virtual machine instead of just a container.
privileged containers which are a security risk in a multi tenant infrastructure.
## 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 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 and mounting in a directory to share between `dind` and the `code-server` container at `/var/run`.
the docker CLI in the code-server container and you should be able to access the daemon as the socket After, install the docker CLI in the code-server container and you should be able to access the
will be shared at /var/run/docker.sock. 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 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` 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. 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? ## 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 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 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. [#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). 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 Please give
[this wonderful blogpost](https://sandstorm.io/news/2015-09-24-is-curl-bash-insecure-pgp-verified-install) by [this wonderful blogpost](https://sandstorm.io/news/2015-09-24-is-curl-bash-insecure-pgp-verified-install) by

20
doc/guide.md
View File

@ -24,8 +24,8 @@ Further docs are at:
- [FAQ.md](./FAQ.md) for common questions. - [FAQ.md](./FAQ.md) for common questions.
- [CONTRIBUTING.md](../doc/CONTRIBUTING.md) for development docs - [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 We'll walk you through acquiring a remote machine to run code-server on
securely access it. and then exposing `code-server` so you can securely access it.
## 1. Acquire a remote machine ## 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. - 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. - 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 - 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 - Click `Change` under `Boot Disk` and change the type to `SSD Persistent Disk` and the size
to `32`. to `32`.
- You can always grow your disk later. - 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 8. Navigate to `Networking -> Network interfaces` and edit the existing interface
to use a static external IP. to use a static external IP.
- Click done to save network interface changes. - 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! 10. Click create!
Remember, you can shutdown your server when not in use to lower costs. 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 We highly recommend learning to use the [`gcloud`](https://cloud.google.com/sdk/gcloud) cli
to avoid the slow dashboard. to avoid the slow dashboard.
## 2. Install code-server ## 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. It tries to use the system package manager if possible.
First run to print out the install process: First run to print out the install process:
@ -158,8 +160,8 @@ ServerAliveInterval 5
ExitOnForwardFailure yes ExitOnForwardFailure yes
``` ```
You can also forward your SSH key and GPG agent to the instance to securely access GitHub You can also forward your SSH and GPG agent to the instance to securely access GitHub
and sign commits without copying your keys onto the instance. and sign commits without copying your keys.
1. https://developer.github.com/v3/guides/using-ssh-agent-forwarding/ 1. https://developer.github.com/v3/guides/using-ssh-agent-forwarding/
2. https://wiki.gnupg.org/AgentForwarding 2. https://wiki.gnupg.org/AgentForwarding
@ -244,8 +246,8 @@ fields.
### Change the password? ### Change the password?
Edit the code-server config file at `~/.config/code-server/config.yaml` and then restart Edit the `password` field in the code-server config file at `~/.config/code-server/config.yaml`
code-server with: and then restart code-server with:
```bash ```bash
systemctl --user restart code-server systemctl --user restart code-server

51
doc/install.md
View File

@ -3,6 +3,8 @@
# Install # Install
- [install.sh](#installsh) - [install.sh](#installsh)
- [Flags](#flags)
- [Installation reference](#installation-reference)
- [Debian, Ubuntu](#debian-ubuntu) - [Debian, Ubuntu](#debian-ubuntu)
- [Fedora, CentOS, RHEL, SUSE](#fedora-centos-rhel-suse) - [Fedora, CentOS, RHEL, SUSE](#fedora-centos-rhel-suse)
- [Arch Linux](#arch-linux) - [Arch Linux](#arch-linux)
@ -18,7 +20,8 @@ various distros and operating systems.
## install.sh ## 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. It tries to use the system package manager if possible.
First run to print out the install process: 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. 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 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 Fedora, CentOS, RHEL and openSUSE it will install the latest rpm package.
- For Arch Linux it will install the AUR 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. - Add `~/.local/bin` to your `$PATH` to run code-server.
- For macOS it will install the Homebrew package. - 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. - 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`. - 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. - 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 ## Debian, Ubuntu
```bash ```bash
@ -106,10 +109,10 @@ systemctl --user enable --now code-server
## yarn, npm ## 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`. 1. You aren't on `amd64` or `arm64`.
2. glibc < v2.17 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. **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. See [./doc/npm.md](./doc/npm.md) for installing these dependencies.

46
install.sh
View File

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