64cc2895f3
As reported in GH-962, this breaks VSCode's extension details view. Might need further triage if its also a v2 internal issue.
307 lines
11 KiB
Markdown
307 lines
11 KiB
Markdown
# Getting Started
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
<!-- 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. -->
|
|
|
|
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.
|
|
|
|
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
|
|
|
|
|
|
### Security Warnings
|
|
|
|
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">
|
|
|
|
|
|
## 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.
|
|
|
|
Options:
|
|
-V, --version output the version number
|
|
--cert <value>
|
|
--cert-key <value>
|
|
-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.
|
|
-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)
|
|
-N, --no-auth Start without requiring authentication.
|
|
-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.
|
|
--install-extension <value> Install an extension by its ID.
|
|
-h, --help output usage information
|
|
```
|
|
|
|
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`.
|
|
|
|
You can instruct code-server to automatically open itself in your default
|
|
browser by using the `-o` or `--open` flag.
|
|
|
|
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.
|
|
|
|
|
|
### SSL Certificates
|
|
|
|
To change the certificate code-server uses for HTTPS connections, specify a
|
|
certificate with `--cert` and a private key with `--cert-key`.
|
|
|
|
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.
|
|
|
|
```
|
|
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 SAMEORIGIN;
|
|
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;
|
|
}
|
|
}
|
|
|
|
# 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
|
|
|
|
# If you're using CloudFlare, uncomment the following line.
|
|
# RemoteIPHeader CF-Connecting-IP;
|
|
|
|
# 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>
|
|
</IfModule>
|
|
```
|
|
|
|
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
|