diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..6034d421 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @coderasher @kylecarbs \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..25f343ef --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,18 @@ +--- +name: Bug Report +about: Report problems and unexpected behavior. +title: '' +labels: '' +assignees: '' +--- + + + + +- `vscode-remote` version: +- OS Version: + +#### Steps to Reproduce + +1. +2. diff --git a/.github/ISSUE_TEMPLATE/extension_bug.md b/.github/ISSUE_TEMPLATE/extension_bug.md new file mode 100644 index 00000000..420cc645 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/extension_bug.md @@ -0,0 +1,18 @@ +--- +name: Extension Bug +about: Report problems and unexpected behavior with extensions. +title: '' +labels: 'extension-specific' +assignees: '' +--- + + + +- `vscode-remote` version: +- OS Version: +- Extension: + +#### Steps to Reproduce + +1. +2. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 00000000..47b7dbd3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,11 @@ +--- +name: Feature Request +about: Suggest an idea for this project. +title: '' +labels: '' +assignees: '' +--- + + + + \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md new file mode 100644 index 00000000..119c6b69 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.md @@ -0,0 +1,17 @@ +--- +name: Question +about: Ask a question. +title: '' +labels: '' +assignees: '' +--- + + + +#### Description + + + +#### Related Issues + + \ No newline at end of file diff --git a/.gitignore b/.gitignore index 444ef229..647d88c5 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ lib node_modules dist -out \ No newline at end of file +out +.DS_Store diff --git a/README.md b/README.md index ad1d42e1..cf5ae5d2 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,53 @@ -# vscode-remote +# code-server -Run VS Code remotely. +[!["Open Issues"](https://img.shields.io/github/issues-raw/codercom/code-server.svg)](https://github.com/codercom/code-server/issues) +[!["Latest Release"](https://img.shields.io/github/release/codercom/code-server.svg)](https://github.com/codercom/code-server/releases/latest) +[![MIT license](https://img.shields.io/badge/license-MIT-green.svg)](#) + +`code-server` is VS Code running on a remote server, accessible through the browser. + +![Screenshot](/doc/assets/ide.png) + +## Getting Started + +[Try `code-server` now](https://coder.com/signup) for free at coder.com. + +1. [Download a binary](https://github.com/codercom/code-server/releases) (Linux and OSX supported. Windows coming soon) +2. Start the binary with the project directory as the first argument + + ``` + code-server + ``` + > You will be prompted to enter the password shown in the CLI + `code-server` should now be running at https://:8443. + > code-server uses a self-signed SSL certificate that may prompt your browser to ask you some additional questions before you proceed. Please [read here](doc/self-hosted/index.md) for more information. + +For detailed instructions and troubleshooting, see the [self-hosted quick start guide](doc/self-hosted/index.md). + +Quickstart guides for [Google Cloud](doc/admin/install/google_cloud.md), [AWS](doc/admin/install/aws.md), and [Digital Ocean](doc/admin/install/digitalocean.md). + +How to [secure your setup](/doc/security/ssl.md). + +## Development + +### Known Issues + +- Debugging extensions doesn’t work. + +### Future + +- Windows support. +- Electron and ChromeOS applications to bridge the gap between local<->remote. +- Run VS Code unit tests against our builds to ensure features work as expected. ## Contributing -### Getting the source +Guides on setup for development will be coming soon. :) -``` -git clone https://github.com/codercom/vscode-remote -``` +## License -### Installing dependencies +[MIT](LICENSE) -``` -cd vscode-remote -yarn -``` +## Enterprise -### Run - -``` -yarn start -``` +Visit [our enterprise page](https://coder.com/enterprise) for more information on our enterprise offering. diff --git a/doc/admin/install/aws.md b/doc/admin/install/aws.md new file mode 100644 index 00000000..6be6cd26 --- /dev/null +++ b/doc/admin/install/aws.md @@ -0,0 +1,57 @@ +# Deploy on AWS + +This tutorial shows you how to deploy `code-server` on an EC2 AWS instance. + +If you're just starting out, we recommend [installing code-server locally](../../self-hosted/index.md). It takes only a few minutes and lets you try out all of the features. You can also try out the IDE on a container hosted [by Coder](http://coder.com/signup) + +--- + +## Deploy to EC2 + +### Use the AWS wizard + +- Click **Launch Instance** from your [EC2 dashboard](https://console.aws.amazon.com/ec2/v2/home). +- Select the Ubuntu Server 16.04 LTS (HVM), SSD Volume Type (`ami-0f9cf087c1f27d9b1)` at this time of writing) +- Select an appropriate instance size (we recommend t2.medium/large, depending on team size and number of repositories/languages enabled), then **Next: Configure Instance Details** +- Select **Next: ...** until you get to the **Configure Security Group** page, then add the default **HTTP** rule (port range "80", source "0.0.0.0/0, ::/0") + > Rules with source of 0.0.0.0/0 allow all IP addresses to access your instance. We recommend setting [security group rules](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html?icmpid=docs_ec2_console) to allow access from known IP addresses only. +- Click **Launch** +- You will be prompted to create a key pair + > A key pair consists of a public key that AWS stores, and a private key file that you store. Together, they allow you to connect to your instance securely. For Windows AMIs, the private key file is required to obtain the password used to log into your instance. For Linux AMIs, the private key file allows you to securely SSH into your instance. +- From the dropdown choose "create a new pair", give the key pair a name +- Click **Download Key Pair** + > This is necessary before you proceed. A `.pem` file will be downloaded. make sure you store is in a safe location because it can't be retrieved once we move on. +- Finally, click **Launch Instances** +--- +### SSH Into EC2 Instance +- First head to your [EC2 dashboard](https://console.aws.amazon.com/ec2/v2/home) and choose instances from the left panel +- In the description of your EC2 instance copy the public DNS (iPv4) address using the copy to clipboard button +- Open a terminal on your computer and use the following command to SSH into your EC2 instance + ``` + ssh i "path/to/your/keypair.pem" ubuntu@(paste the public DNS here) + ``` + >example: `ssh -i "/Users/John/Downloads/TestInstance.pem" ubuntu@ec2-3-45-678-910.compute-1.amazonaws.co` +- You should see a prompt for your EC2 instance like so +- At this point it is time to download the `code-server` binary. We will of course want the linux version. Make sure you copy the link for the latest linux version on our [releases page](https://github.com/codercom/code-server/releases) +- With the URL in the clipboard, run: + ``` + wget https://github.com/codercom/code-server/releases/download/0.1.4/code-server-linux + ``` +- If you run into any permission errors, make the binary executable by running: + ``` + chmod +x code-server-linux + ``` + > To ensure the connection between you and your server is encrypted view our guide on [securing your setup](../security/ssl.md) +- Finally, run + ``` + sudo ./code-server-linux -p 80 + ``` +- When you visit the public IP for your AWS instance, you will be greeted with this page. Code-server is using a self-signed SSL certificate for easy setup. To proceed to the IDE, click **"Advanced"** +- Then click **"proceed anyway"** + + > For instructions on how to keep the server running after you end your SSH session please checkout [how to use systemd](https://www.linode.com/docs/quick-answers/linux/start-service-at-boot/) to start linux based services if they are killed + + > The `-p 80` flag is necessary in order to make the IDE accessible from the public IP of your instance (also available from the description in the instances page. + + --- +> NOTE: If you get stuck or need help, [file an issue](https://github.com/codercom/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). \ No newline at end of file diff --git a/doc/admin/install/digitalocean.md b/doc/admin/install/digitalocean.md new file mode 100644 index 00000000..e702f50a --- /dev/null +++ b/doc/admin/install/digitalocean.md @@ -0,0 +1,37 @@ +# Deploy on DigitalOcean + +This tutorial shows you how to deploy `code-server` to a single node running on DigitalOcean. + +If you're just starting out, we recommend [installing code-server locally](../../self-hosted/index.md). It takes only a few minutes and lets you try out all of the features. You can also try out the IDE on a container hosted [by Coder](http://coder.com/signup) + +--- + +## Use the "Create Droplets" wizard + +[Open your DigitalOcean dashboard](https://cloud.digitalocean.com/droplets/new) to create a new droplet + +- **Choose an image -** Select the **Distributions** tab and then choose Ubuntu +- **Choose a size -** We recommend at least 4GB RAM and 2 CPU, more depending on team size and number of repositories/languages enabled. +- Launch your instance +- Open a terminal on your computer and SSH into your instance + > example: ssh root@203.0.113.0 +- Once in the SSH session, visit code-server [releases page](https://github.com/codercom/code-server/releases/) and copy the link to the download for the latest linux release +- In the shell run the below command with the URL from your clipboard + ``` + wget https://github.com/codercom/code-server/releases/download/0.1.4/code-server-linux + ``` +- If you run into any permission errors when attempting to run the binary: + ``` + chmod +x code-server-linux + ``` + > To ensure the connection between you and your server is encrypted view our guide on [securing your setup](../security/ssl.md) +- Finally start the code-server + ``` + sudo ./code-server-linux -p80 + ``` + > For instructions on how to keep the server running after you end your SSH session please checkout [how to use systemd](https://www.linode.com/docs/quick-answers/linux/start-service-at-boot/) to start linux based services if they are killed +- When you visit the public IP for your Digital Ocean instance, you will be greeted with this page. Code-server is using a self-signed SSL certificate for easy setup. To proceed to the IDE, click **"Advanced"** +- Then click **"proceed anyway"** + +--- +> NOTE: If you get stuck or need help, [file an issue](https://github.com/codercom/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). \ No newline at end of file diff --git a/doc/admin/install/google_cloud.md b/doc/admin/install/google_cloud.md new file mode 100644 index 00000000..9c5e4f6b --- /dev/null +++ b/doc/admin/install/google_cloud.md @@ -0,0 +1,46 @@ +# Deploy on Google Cloud + +This tutorial shows you how to deploy `code-server` to a single node running on Google Cloud. + +If you're just starting out, we recommend [installing code-server locally](../../self-hosted/index.md). It takes only a few minutes and lets you try out all of the features. You can also try out the IDE on a container hosted [by Coder](http://coder.com/signup) + +--- + +## Deploy to Google Cloud VM +> Pre-requisite: Please [set up Google Cloud SDK](https://cloud.google.com/sdk/docs/) on your local machine + +- [Open your Google Cloud console](https://console.cloud.google.com/compute/instances) to create a new VM instance and click **Create Instance** +- Choose an appropriate machine type (we recommend 2 vCPU and 7.5 GB RAM, more depending on team size and number of repositories/languages enabled) +- Choose Ubuntu 16.04 LTS as your boot disk +- Check the boxes for **Allow HTTP traffic** and **Allow HTTPS traffic** in the **Firewall** section +- Create your VM, and **take note** of it's public IP address. +- Copy the link to download the latest Linux binary from our [releases page](https://github.com/codercom/code-server/releases) + +--- + +## Final Steps + +1. SSH into your Google Cloud VM +``` +gcloud compute ssh --zone [region] [instance name] +``` +2. Download the binary using the link we copied to clipboard +``` +wget https://github.com/codercom/code-server/releases/download/0.1.4/code-server-linux +``` +3. Make the binary executable if you run into any errors regarding permission: + ``` + chmod +x code-server-linux + ``` +> To ensure the connection between you and your server is encrypted view our guide on [securing your setup](../security/ssl.md) +4. Start the code-server +``` +sudo ./code-server-linux -p 80 +``` +> For instructions on how to keep the server running after you end your SSH session please checkout [how to use systemd](https://www.linode.com/docs/quick-answers/linux/start-service-at-boot/) to start linux based services if they are killed +5. Access code-server from the public IP of your Google Cloud instance we noted earlier in your browser. +> example: 32.32.32.234 +6. You will be greeted with this page. Code-server is using a self-signed SSL certificate for easy setup. To proceed to the IDE, click **"Advanced"** +7. Then click **"proceed anyway"** +--- +> NOTE: If you get stuck or need help, [file an issue](https://github.com/codercom/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). \ No newline at end of file diff --git a/doc/assets/aws_ubuntu.png b/doc/assets/aws_ubuntu.png new file mode 100644 index 00000000..b3b0fad1 Binary files /dev/null and b/doc/assets/aws_ubuntu.png differ diff --git a/doc/assets/chrome_confirm.png b/doc/assets/chrome_confirm.png new file mode 100644 index 00000000..8c0659d0 Binary files /dev/null and b/doc/assets/chrome_confirm.png differ diff --git a/doc/assets/chrome_warning.png b/doc/assets/chrome_warning.png new file mode 100644 index 00000000..8fe2e2a4 Binary files /dev/null and b/doc/assets/chrome_warning.png differ diff --git a/doc/assets/cli.png b/doc/assets/cli.png new file mode 100644 index 00000000..18c4714e Binary files /dev/null and b/doc/assets/cli.png differ diff --git a/doc/assets/ide.png b/doc/assets/ide.png new file mode 100644 index 00000000..e70569d4 Binary files /dev/null and b/doc/assets/ide.png differ diff --git a/doc/assets/logo-horizontal.png b/doc/assets/logo-horizontal.png new file mode 100644 index 00000000..4348b58a Binary files /dev/null and b/doc/assets/logo-horizontal.png differ diff --git a/doc/assets/server-password-modal.png b/doc/assets/server-password-modal.png new file mode 100644 index 00000000..c79beb4c Binary files /dev/null and b/doc/assets/server-password-modal.png differ diff --git a/doc/security/ssl.md b/doc/security/ssl.md new file mode 100644 index 00000000..da0e4bd9 --- /dev/null +++ b/doc/security/ssl.md @@ -0,0 +1,53 @@ +# Generate a self-signed certificate 🔒 + +code-server has the ability to secure your connection between client and server using SSL/TSL certificates. By default, the server will start with an unencrypted connection. We recommend Self-signed TLS/SSL certificates for personal of code-server or within an organization. + +This guide will show you how to create a self-signed certificate and start code-server using your certificate/key. + +## TLS / HTTPS + +You can specify any location that you want to save the certificate and key. In this example, we will navigate to the root directory, create a folder called `certs` and cd into it. + +```shell +mkdir ~/certs && cd ~/certs +``` + +If you don't already have a TLS certificate and key, you can generate them with the command below. They will be placed in `~/certs` + +```shell +openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ~/certs/MyKey.key -out ~/certs/MyCertificate.crt +``` + +You will be prompted to add some identifying information about your organization +```shell +You are about to be asked to enter information that will be incorporated +into your certificate request. +What you are about to enter is what is called a Distinguished Name or a DN. +There are quite a few fields but you can leave some blank +For some fields there will be a default value, +If you enter '.', the field will be left blank. +----- +Country Name (2 letter code) [AU]:US +State or Province Name (full name) [Some-State]:TX +Locality Name (eg, city) []:Austin +Organization Name (eg, company) [Coder Technologies]:Coder +Organizational Unit Name (eg, section) []:Docs +Common Name (e.g. server FQDN or YOUR name) []:hostname.example.com +Email Address []:admin@example.com +``` +>If you already have a TLS certificate and key, you can simply reference them in the `--cert` and `--cert-key` flags when launching code-server + + +## Starting code-server with certificate and key + +1. At the end of the path to your binary, add the following flags followed by the path to your certificate and key like so. Then press enter to run code-server. + ```shell + ./code-server --cert=~/certs/MyCertificate.crt --cert-key=~/certs/MyKey.key + ``` +2. After that you will be running a secure code-server. + +> You will know your connection is secure if the lines `WARN No certificate specified. This could be insecure. WARN Documentation on securing your setup: https://coder.com/docs` no longer appear. + +## Other options + +For larger organizations you may wish to rely on a Certificate Authority as opposed to a self-signed certificate. For more information on generating free and open certificates for your site, please check out EFF's [certbot](https://certbot.eff.org/). Certbot is a cli to generate certificates using [LetsEncrypt](https://letsencrypt.org/). diff --git a/doc/self-hosted/index.md b/doc/self-hosted/index.md new file mode 100644 index 00000000..e3f71e53 --- /dev/null +++ b/doc/self-hosted/index.md @@ -0,0 +1,75 @@ +# 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. + +## Quickstart guide + +> NOTE: If you get stuck or need help, [file an issue](https://github.com/codercom/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). + +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) + +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 `8080` by default. + + + + +1. Visit [the releases](https://github.com/codercom/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 +4. In your browser navigate to `localhost:8080` +5. Paste the password from the cli into the login window +> NOTE: Be careful with your password as sharing it will grant those users access to your server's file system + +### Things to know +- When you visit the IP for your code-server, you will be greeted with this page. Code-server is using a self-signed SSL certificate for easy setup. To proceed to the IDE, click **"Advanced"** +- Then click **"proceed anyway"** + +## Usage +
code-server --help
+ +code-server can be ran with a number of arguments to customize your working directory, host, port, and SSL certificate. + +``` +USAGE + $ code-server [WORKDIR] + +ARGUMENTS + WORKDIR [default: (directory to binary)] Specify working dir + +OPTIONS + -d, --data-dir=data-dir + -h, --host=host [default: 0.0.0.0] + -o, --open Open in browser on startup + -p, --port=port [default: 8080] Port to bind on + -v, --version show CLI version + --cert=cert + --cert-key=cert-key + --help show CLI help + ``` + + ### Data directory + Use `code-server -d (path/to/directory)` or `code-server --data-dir=(path/to/directory)`, excluding the parentheses to specify the root folder that VS Code will start in + + ### Host + By default, code-server will use `0.0.0.0` as it's 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` + + ### 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 + + ### Port + By default, code-server will use `8080` as it's 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` + + ### 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` + +> To ensure the connection between you and your server is encrypted view our guide on [securing your setup](../security/ssl.md) + + ### Help + Use `code-server -h` or `code-server --help` to view the usage for the cli. This is also shown at the beginning of this section. \ No newline at end of file