cubetiq/code-server
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Rewrite and update documentation

Browse Source
This commit is contained in:
Dean Sheather
2019-08-17 05:46:37 +10:00
parent 8c39e085f4
commit 7caef7f49c
12 changed files with 703 additions and 246 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
doc/self-hosted/cros-install.md
View File

@@ -1,20 +1,31 @@
# Installng code-server in your ChromiumOS/ChromeOS/CloudReady machine
# Installng code-server on a ChromeOS/CloudReady machine
This guide will show you how to install code-server into your CrOS machine.
This guide will show you how to install code-server on your CrOS machine.
## Using Crostini
One of the easier ways to run code-server is via [Crostini](https://www.aboutchromebooks.com/tag/project-crostini/), the Linux apps support feature in CrOS. Make sure you have enough RAM, HDD space and your CPU has VT-x/ AMD-V support. If your chromebook has this, then you are qualified to use Crostini.
One of the easier ways to run code-server is via [Crostini](crostini), the Linux
apps support feature in CrOS. Make sure you have enough RAM, HDD space and your
CPU has VT-x/AMD-V support. If your Chromebook has this, then you are qualified
to use Crostini.
If you are running R69, you might want to enable this on [Chrome Flags](chrome://flags/#enable-experimental-crostini-ui). If you run R72, however, this is already enabled for you.
If you are running R69, you might want to enable this on
[Chrome Flags](r69-flag). If you run R72, however, this is already enabled for
you.
After checking your prerequisites, follow the steps in [the self-host install guide](index.md) on installing code-server. Once done, make sure code-server works by running it. After running it, simply go to `penguin.linux.test:8443` to access code-server. Now you should be greeted with this screen. If you did, congratulations, you have installed code-server in your Chromebook!
After checking your prerequisites, follow the steps in [the self-host install
guide](self-hosted-guide) on installing code-server. Once done, make sure
code-server works by running it, then simply go to `penguin.linux.test:8443` to
access code-server. You should be greeted with the following screen. If it
works, congratulations, you have installed code-server in your Chromebook!
![code-server on Chromebook](../assets/cros.png)
Alternatively, if you ran code-server in another container and you need the IP for that specific container, simply go to Termina's shell via `crosh` and type `vsh termina`.
Alternatively, if you ran code-server in another container and you need the IP
for that specific container, simply go to Termina's shell via `crosh` and type
`vsh termina`.
```bash
```
Loading extra module: /usr/share/crosh/dev.d/50-crosh.sh
Welcome to crosh, the Chrome OS developer shell.
@@ -28,9 +39,11 @@ Load it by using the Ctrl+Shift+P keyboard shortcut.
crosh> vsh termina
(termina) chronos@localhost ~ $
```
While in termina, run `lxc list`. It should output the list of running containers.
```bash
While in termina, run `lxc list`. It should output the list of running
containers.
```
(termina) chronos@localhost ~ $ lxc list
+---------+---------+-----------------------+------+------------+-----------+
| NAME | STATE | IPV4 | IPV6 | TYPE | SNAPSHOTS |
@@ -40,14 +53,29 @@ While in termina, run `lxc list`. It should output the list of running container
(termina) chronos@localhost ~ $
```
For this example, we show the default `penguin` container, which is exposed on `eth0` at 100.115.92.199. Simply enter the IP of the container where the code-server runs to Chrome.
For this example, we show the default `penguin` container, which is exposed on
`eth0` at 100.115.92.199. Simply enter the IP of the container where code-server
is running into Chrome to access code-server.
[crostini]: https://www.aboutchromebooks.com/tag/project-crostini/
[r69-flag]: chrome://flags/#enable-experimental-crostini-ui
[self-hosted-guide]: ./index.md
## Using Crouton
[Crouton](https://github.com/dnschneid/crouton) is one of the old ways to get a running full Linux via `chroot` on a Chromebook. To use crouton, enable developer mode and go to `crosh`. This time, run `shell`, which should drop you to `bash`.
[Crouton](crouton) is one of the old ways to get a running full Linux via
`chroot` on a Chromebook. To use crouton, enable developer mode and go to
`crosh`. This time, run `shell`, which should drop you to `bash`.
Make sure you downloaded `crouton`, if so, go ahead and run it under `~/Downloads`. After installing your chroot container via crouton, go ahead and enter `enter-chroot` to enter your container.
Make sure you downloaded `crouton`, if so, go ahead and run it under
`~/Downloads`. After installing your chroot container via crouton, go ahead and
enter `enter-chroot` to enter your container.
Follow the instructions set in [the self-host install guide](index.md) to install code-server. After that is done, run `code-server` and verify it works by going to `localhost:8443`.
Follow the instructions set in [the self-host install guide](self-hosted-guide)
to install code-server. After that is done, run `code-server` and verify it
works by going to `localhost:8443`.
> At this point in writing, `localhost` seems to work in this method. However, the author is not sure if it applies still to newer Chromebooks.
> At this point in writing, `localhost` seems to work in this method. However,
> it might not apply to newer Chromebooks.
[crouton]: https://github.com/dnschneid/crouton

317
doc/self-hosted/index.md
View File

@@ -1,38 +1,65 @@
# Getting Started
[code-server](https://coder.com) is used by developers at Azure, Google, Reddit, and more to give them access to VS Code in the browser.
This document pertains to Coder-specific implementation of VS Code: code-server.
For documentation on how to use VS Code itself, please refer to the official
[VS Code documentation](vscode-documentation).
If you get stuck or need help at anytime, [file an issue](create-issue),
[tweet (@coderhq)](twitter-coderhq) or [email](email-coder).
[vscode-documentation]: https://code.visualstudio.com/docs
[create-issue]: https://github.com/cdr/code-server/issues/new?title=Improve+self-hosted+quickstart+guide
[twitter-coderhq]: https://twitter.com/coderhq
[email-coder]: mailto:support@coder.com?subject=Self-hosted%20quickstart%20guide
## Quickstart Guide
> NOTE: If you get stuck or need help, [file an issue](https://github.com/cdr/code-server/issues/new?&title=Improve+self-hosted+quickstart+guide), [tweet (@coderhq)](https://twitter.com/coderhq) or [email](mailto:support@coder.com?subject=Self-hosted%20quickstart%20guide).
It takes just a few minutes to get your own self-hosted server running. If
you've got a machine running macOS or Linux, you're ready to start the
binary which listens on port `8443` by default.
This document pertains to Coder specific implementations of VS Code. For documentation on how to use VS Code itself, please refer to the official [documentation for VS Code](https://code.visualstudio.com/docs)
<!-- DO NOT CHANGE THIS TO A CODEBLOCK. We want line breaks for readability, but
backslashes to escape them do not work cross-platform. This uses line
breaks that are rendered but not copy-pasted to the clipboard. -->
It takes just a few minutes to get your own self-hosted server running. If you've got a machine running macOS, Windows, or Linux, you're ready to start the binary which listens on port `8443` by default.
1. Visit the [releases](code-server-releases) page and download the latest
release for your operating system.
2. Extract the archive and double click the executable to run in the current
directory.
3. Copy the password that appears in the output.
<img src="../assets/cli.png">
4. In your browser navigate to https://localhost:8443. You will be greeted with
an SSL warning as code-server uses a self-signed certificate (more on that
below). Skip the warning.
5. Login using the password from earlier.
<!--
DO NOT CHANGE THIS TO A CODEBLOCK.
We want line breaks for readability, but backslashes to escape them do not work cross-platform.
This uses line breaks that are rendered but not copy-pasted to the clipboard.
-->
Be careful about who you share your password with, as it will grant them full
access to your server.
[code-server-releases]: https://github.com/cdr/code-server/releases
1. Visit [the releases](https://github.com/cdr/code-server/releases) page and download the latest cli for your operating system
2. Double click the executable to run in the current directory
3. Copy the password that appears in the cli<img src="../assets/cli.png">
4. In your browser navigate to `localhost:8443`
5. Paste the password from the cli into the login window<img src="../assets/server-password-modal.png">
> NOTE: Be careful with your password as sharing it will grant those users access to your server's file system
### Security Warnings
### Things To Know
- When you visit the IP for your code-server instance, you will be greeted with a page similar to the following screenshot. Code-server is using a self-signed SSL certificate for easy setup. In Chrome/Chromium, click **"Advanced"** then click **"proceed anyway"**. In Firefox, click **Advanced**, then **Add Exception**, then finally **Confirm Security Exception**.<img src ="../assets/chrome_warning.png">
When you visit your code-server instance, you will be greeted with a warning
page similar to the following screenshot. code-server is using a self-signed SSL
certificate for easy setup. In Chrome/Chromium, click **Advanced** then click
**proceed anyway**. In Firefox, click **Advanced**, then **Add Exception**,
then finally **Confirm Security Exception**.
<img src="../assets/chrome_warning.png">
## Usage
<pre class="pre-wrap"><code>code-server<span class="virtual-br"></span> --help</code></pre>
code-server can be ran with a number of arguments to customize your working directory, host, port, and SSL certificate.
## code-server Usage
You can bring up code-server usage by using `code-server --help`. Arguments let
you customize your working directory, host, port, SSL certificates, and more.
Flags can be supplied to code-server like `--flag-name value` or
`--flag-name=value`. To supply values with whitespace, use double quotes.
```
$ code-server --help
Usage: code-server [options]
Run VS Code on a remote server.
@@ -44,7 +71,7 @@ Options:
-e, --extensions-dir <dir> Override the main default path for user extensions.
--extra-extensions-dir [dir] Path to an extra user extension directory (repeatable). (default: [])
--extra-builtin-extensions-dir [dir] Path to an extra built-in extension directory (repeatable). (default: [])
-d, --user-data-dir <dir> Specifies the directory that user data is kept in, useful when running as root.
-d --user-data-dir <dir> Specifies the directory that user data is kept in, useful when running as root.
-h, --host <value> Customize the hostname. (default: "0.0.0.0")
-o, --open Open in the browser on startup.
-p, --port <number> Port to bind on. (default: 8443)
@@ -52,74 +79,228 @@ Options:
-H, --allow-http Allow http connections.
--disable-telemetry Disables ALL telemetry.
--socket <value> Listen on a UNIX socket. Host and port will be ignored when set.
--trust-proxy Trust the X-Forwarded-For header, useful when using a reverse proxy.
--install-extension <value> Install an extension by its ID.
-h, --help output usage information
```
### Data Directory
Use `code-server -d (path/to/directory)` or `code-server --user-data-dir=(path/to/directory)`, excluding the parentheses to specify the root folder that VS Code will start in.
By default, code-server listens on `0.0.0.0:8443`. If you'd like to customize
this, use the `--host` and `--port` flags:
`code-server --host 127.0.0.1 --port 1234`.
### Host
By default, code-server will use `0.0.0.0` as its address. This can be changed by using `code-server -h` or `code-server --host=` followed by the address you want to use.
> Example: `code-server -h 127.0.0.1`
You can instruct code-server to automatically open itself in your default
browser by using the `-o` or `--open` flag.
### Open
You can have the server automatically open the VS Code in your browser on startup by using the `code-server -o` or `code-server --open` flags
Use `code-server -d path/to/directory` to specify where code-server stores it's
configuration data. You can specify where extensions are installed using the
`-e`, `--extra-extensions-dir` and `--extra-builtin-extensions-dir` flags.
### Port
By default, code-server will use `8443` as its port. This can be changed by using `code-server -p` or `code-server --port=` followed by the port you want to use.
> Example: `code-server -p 9000`
### Telemetry
Disable all telemetry with `code-server --disable-telemetry`.
### SSL Certificates
### Cert and Cert Key
To encrypt the traffic between the browser and server use `code-server --cert=` followed by the path to your `.cer` file. Additionally, you can use certificate keys with `code-server --cert-key` followed by the path to your `.key` file.
> Example (certificate and key): `code-server --cert /etc/letsencrypt/live/example.com/fullchain.cer --cert-key /etc/letsencrypt/live/example.com/fullchain.key`
> Example (if you are using Letsencrypt or similar): `code-server --cert /etc/letsencrypt/live/example.com/fullchain.pem --cert-key /etc/letsencrypt/live/example.com/privkey.key`
To change the certificate code-server uses for HTTPS connections, specify a
certificate with `--cert` and a private key with `--cert-key`.
> To ensure the connection between you and your server is encrypted view our guide on [securing your setup](../security/ssl.md)
If you're using Let's Encrypt, you should be using the `fullchain.pem` file as
the certificate and `privkey.pem` as the private key.
### Nginx Reverse Proxy
Below is a virtual host example that works with code-server. Please also pass `--allow-http` and `--trust-proxy` to code-server to allow the proxy to connect. You can also use Let's Encrypt to get a SSL certificates for free.
```
server {
listen 80;
listen [::]:80;
server_name code.example.com code.example.org;
location / {
proxy_pass http://localhost:8443/;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection upgrade;
proxy_set_header Accept-Encoding gzip;
}
```
code-server \
--cert /etc/letsencrypt/live/example.com/fullchain.pem \
--cert-key /etc/letsencrypt/live/example.com/privkey.pem
```
For more information on security and SSL configuration, please visit the
[security documentation](../security).
#### Telemetry
Telemetry can be disabled by using the `--disable-telemetry` flag or by setting
the `DISABLE_TELEMETRY` environment variable to `true`. If telemetry is enabled,
code-server will send the following data along with VS Code's telemetry data:
- Unique machine ID
- CPU core count and model
- Memory information
- Shell information (which shell you use)
- OS release and architecture
### Nginx Reverse Proxy
The following site configuration file works with code-server. When starting
code-server, be sure to provide the `--allow-http` and `--trust-proxy` flags so
Nginx can connect to code-server properly.
Some of these directives require a version of Nginx greater than or equal to
`1.13.0`, which might not be available in your distro's repositories. Check out
[Nginx's documentation](nginx-install) for more information on how to install
the latest version of Nginx from the official repository.
```
# HTTP configuration
server {
listen 80;
listen [::]:80;
server_name code.example.com code.example.org;
# If you're using CloudFlare, uncomment the following line.
# real_ip_header CF-Connecting-IP;
# Other security options.
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
location / {
proxy_pass http://localhost:8443/;
proxy_set_header Accept-Encoding gzip;
proxy_set_header Connection upgrade;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
```
}
### Apache Reverse Proxy
Example of a HTTPS virtualhost configuration for Apache as a reverse proxy. Please also pass `--allow-http` and `--trust-proxy` to code-server to allow the proxy to connect. You can also use Let's Encrypt to get a SSL certificates for free.
```
<VirtualHost *:80>
# HTTPS configuration. Scores an A on SSL Labs' SSL Server Test.
server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name code.example.com code.example.org;
# If you're using CloudFlare, uncomment the following line.
# real_ip_header CF-Connecting-IP;
# SSL certificate and key.
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/cert-key.pem;
# Strong TLS configuration. Originally taken from https://cipherli.st/.
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
# ssl_dhparam /etc/nginx/dhparam.pem; # openssl dhparam -out /etc/nginx/dhparam.pem 4096
ssl_ciphers EECDH+AESGCM:EDH+AESGCM;
ssl_ecdh_curve secp384r1;
ssl_session_timeout 10m;
ssl_session_cache shared:SSL:10m;
ssl_session_tickets off;
ssl_stapling on;
ssl_stapling_verify on;
resolver 8.8.8.8 8.8.4.4 valid=300s;
resolver_timeout 5s;
# Other security options.
# add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload";
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
location / {
proxy_pass http://localhost:8443/;
proxy_set_header Accept-Encoding gzip;
proxy_set_header Connection upgrade;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
```
Make sure to set the `proxy_pass` directive to the actual address of your
code-server instance and the `server_name` directive to the hostname/s of your
website. If you're using an SSL certificate, make sure to change the
`ssl_certificate` and `ssl_certificate_key` directives. If not, remove the HTTPS
`server` block entirely.
[nginx-install]: https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/#installing-a-prebuilt-package
### Apache Reverse Proxy
The following virtual host configuration file works with code-server. When
starting code-server, be sure to provide the `--allow-http` and `--trust-proxy`
flags so Apache can connect to code-server properly.
Some of these directives require a version of Apache greater than or equal to
`2.4.0`, which might not be available in your distro's repositories. You will
also need to enable the following modules: `rewrite`, `proxy`, `proxy_http`,
`proxy_wstunnel`, `ssl`, and `socache_shmcb`.
```
# HTTP configuration.
<VirtualHost *:80>
ServerName code.example.com
# If you're using CloudFlare, uncomment the following line.
# RemoteIPHeader CF-Connecting-IP;
# Other security options.
Header always set X-Frame-Options DENY
Header always set X-Content-Type-Options nosniff
RewriteEngine On
RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteCond %{HTTP:Connection} upgrade [NC]
RewriteRule .* "ws://localhost:8443%{REQUEST_URI}" [P]
RequestHeader set X-Forwarded-Proto https
RequestHeader set X-Forwarded-Port 443
ProxyRequests off
ProxyPass / http://localhost:8443/ nocanon
ProxyPassReverse / http://localhost:8443/
</VirtualHost>
# HTTPS configuration. Scores an A on SSL Labs' SSL Server Test.
<IfModule mod_ssl.c>
SSLStaplingCache shmcb:/tmp/stapling_cache(150000)
<VirtualHost *:443>
ServerName code.example.com
RewriteEngine On
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule /(.*) ws://localhost:8443/$1 [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket [NC]
RewriteRule /(.*) http://localhost:8443/$1 [P,L]
# If you're using CloudFlare, uncomment the following line.
# RemoteIPHeader CF-Connecting-IP;
ProxyRequests off
# SSL certificate and key.
SSLEngine On
SSLCertificateFile /path/to/cert.pem
SSLCertifcateKeyFile /path/to/cert-key.pem
SSLCertificateChainFile /path/to/chain.pem
# Strong TLS configuration. Originally taken from https://cipherli.st/.
SSLCipherSuite EECDH+AESGCM:EDH+AESGCM
SSLProtocol -all +TLSv1.2
SSLHonorCipherOrder On
SSLCompression off
SSLUseStapling on
SSLStaplingCache "shmcb:logs/stapling-cache(150000)"
SSLSessionTickets Off
# Other security options.
# Header always set Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"
Header always set X-Frame-Options DENY
Header always set X-Content-Type-Options nosniff
RewriteEngine On
RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteCond %{HTTP:Connection} upgrade [NC]
RewriteRule .* "ws://localhost:8443%{REQUEST_URI}" [P]
RequestHeader set X-Forwarded-Proto https
RequestHeader set X-Forwarded-Port 443
ProxyRequests off
ProxyPass / http://localhost:8443/ nocanon
ProxyPassReverse / http://localhost:8443/
</VirtualHost>
```
*Important:* For more details about Apache reverse proxy configuration checkout the [documentation](https://httpd.apache.org/docs/current/mod/mod_proxy.html) - especially the [Securing your Server](https://httpd.apache.org/docs/current/mod/mod_proxy.html#access) section
</IfModule>
```
### Help
Use `code-server --help` to view the usage for the CLI. This is also shown at the beginning of this section.
Make sure to set the `ProxyPass`, `ProxyPassReverse` and `RewriteRule`
directives to the actual address of your code-server instance and the
`ServerName` directive to the hostname of your website. If you're using SSL,
make sure to change the `SSLCertificateFile`, `SSLCertificateKeyFile`, and
`SSLCertificateChainFile` directives. If not, remove the HTTPS `IfModule` block
entirely.
For more details about Apache reverse proxy configuration, check out the
[mod_proxy documentation](apache-mod_proxy).
[apache-mod_proxy]: https://httpd.apache.org/docs/current/mod/mod_proxy.html