Skip to content

Commit 33717b2

Browse files
kylecarbscode-asher
kylecarbs
authored and
code-asher
committed
Add documentation (#42)
* Add docs * Add guides for hosting * Inital commit. Add quick start guide for self hosted * Add info for flags * Detail usage flags and provide examples * Correct file types for certificate * Add self-signed certificate guide, update .gitignore * Add additional information.: * Checkout to master * Add transition document, add some links to readme * Comment out some stuff * Revise transition document * Fix typo * Add Google Cloud setup guide * fix link * Add guide links to readme * Add AWS deployment guide * Fixup based on PR suggestions * Fixup ssl guide and readme * Fix typo * Add step to make binary executable * Add digitalocean guide, update readme, add chmod steps just in case * add information about securing the connection to each deploy guide * Update doc/security/ssl.md Co-Authored-By: nol166 <[email protected]> * Fixup from PR suggestions * Add guide for systemd for when ssh closes * Fix typos * VS Code Remote -> code-server * Fix minor stylistics * Update readme (#43) * Update readme * Add details about chrome warning * Add back extension ID settings * Add back SSL guide to readme * State that chmod is likely not necessary * Fix type * Update readme * Remove transition guide * Revise readme based on suggestions. (#45) * Update references to vscode-remote * No Windows support yet
1 parent 90d3a0f commit 33717b2

19 files changed

+380
-17
lines changed

‎.github/CODEOWNERS

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
* @coderasher @kylecarbs

‎.github/ISSUE_TEMPLATE/bug_report.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
name: Bug Report
3+
about: Report problems and unexpected behavior.
4+
title: ''
5+
labels: ''
6+
assignees: ''
7+
---
8+
9+
<!-- Please search existing issues to avoid creating duplicates. -->
10+
<!-- All extension-specific issues should be created with the `Extension Bug` template. -->
11+
12+
- `vscode-remote` version: <!-- The version of vscode-remote -->
13+
- OS Version: <!-- OS version, cloud provider, -->
14+
15+
#### Steps to Reproduce
16+
17+
1.
18+
2.

‎.github/ISSUE_TEMPLATE/extension_bug.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
name: Extension Bug
3+
about: Report problems and unexpected behavior with extensions.
4+
title: ''
5+
labels: 'extension-specific'
6+
assignees: ''
7+
---
8+
9+
<!-- Please search existing issues to avoid creating duplicates. -->
10+
11+
- `vscode-remote` version: <!-- The version of vscode-remote -->
12+
- OS Version: <!-- OS version, cloud provider, -->
13+
- Extension: <!-- Link to extension -->
14+
15+
#### Steps to Reproduce
16+
17+
1.
18+
2.

‎.github/ISSUE_TEMPLATE/feature_request.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
name: Feature Request
3+
about: Suggest an idea for this project.
4+
title: ''
5+
labels: ''
6+
assignees: ''
7+
---
8+
9+
<!-- Please search existing issues to avoid creating duplicates. -->
10+
11+
<!-- Describe the feature you'd like. -->

‎.github/ISSUE_TEMPLATE/question.md

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
name: Question
3+
about: Ask a question.
4+
title: ''
5+
labels: ''
6+
assignees: ''
7+
---
8+
9+
<!-- Please search existing issues to avoid creating duplicates. -->
10+
11+
#### Description
12+
13+
<!-- A description of the the question. -->
14+
15+
#### Related Issues
16+
17+
<!-- Any issues related to your question. -->

‎.gitignore

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
lib
22
node_modules
33
dist
4-
out
4+
out
5+
.DS_Store

‎README.md

+45-16
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,53 @@
1-
# vscode-remote
1+
# code-server
22

3-
Run VS Code remotely.
3+
[!["Open Issues"](https://img.shields.io/github/issues-raw/codercom/code-server.svg)](https://github.com/codercom/code-server/issues)
4+
[!["Latest Release"](https://img.shields.io/github/release/codercom/code-server.svg)](https://github.com/codercom/code-server/releases/latest)
5+
[![MIT license](https://img.shields.io/badge/license-MIT-green.svg)](#)
46

5-
## Contributing
7+
`code-server` is VS Code running on a remote server, accessible through the browser.
8+
9+
![Screenshot](/doc/assets/ide.png)
10+
11+
## Getting Started
12+
13+
[Try `code-server` now](https://coder.com/signup) for free at coder.com.
14+
15+
1. [Download a binary](https://github.com/codercom/code-server/releases) (Linux and OSX supported. Windows coming soon)
16+
2. Start the binary with the project directory as the first argument
17+
18+
```
19+
code-server <inital directory to open>
20+
```
21+
> You will be prompted to enter the password shown in the CLI
22+
`code-server` should now be running at https://<IP>:8443.
23+
> 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.
24+
25+
For detailed instructions and troubleshooting, see the [self-hosted quick start guide](doc/self-hosted/index.md).
26+
27+
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).
628
7-
### Getting the source
29+
How to [secure your setup](/doc/security/ssl.md).
30+
31+
## Development
32+
33+
### Known Issues
34+
35+
- Debugging extensions doesn’t work.
36+
37+
### Future
38+
39+
- Windows support.
40+
- Electron and ChromeOS applications to bridge the gap between local<->remote.
41+
- Run VS Code unit tests against our builds to ensure features work as expected.
42+
43+
## Contributing
844
9-
```
10-
git clone https://github.com/codercom/vscode-remote
11-
```
45+
Guides on setup for development will be coming soon. :)
1246
13-
### Installing dependencies
47+
## License
1448
15-
```
16-
cd vscode-remote
17-
yarn
18-
```
49+
[MIT](LICENSE)
1950
20-
### Run
51+
## Enterprise
2152
22-
```
23-
yarn start
24-
```
53+
Visit [our enterprise page](https://coder.com/enterprise) for more information on our enterprise offering.

‎doc/admin/install/aws.md

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Deploy on AWS
2+
3+
This tutorial shows you how to deploy `code-server` on an EC2 AWS instance.
4+
5+
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)
6+
7+
---
8+
9+
## Deploy to EC2
10+
11+
### Use the AWS wizard
12+
13+
- Click **Launch Instance** from your [EC2 dashboard](https://console.aws.amazon.com/ec2/v2/home).
14+
- Select the Ubuntu Server 16.04 LTS (HVM), SSD Volume Type (`ami-0f9cf087c1f27d9b1)` at this time of writing)
15+
- 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**
16+
- 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")
17+
> 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.
18+
- Click **Launch**
19+
- You will be prompted to create a key pair
20+
> 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.
21+
- From the dropdown choose "create a new pair", give the key pair a name
22+
- Click **Download Key Pair**
23+
> 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.
24+
- Finally, click **Launch Instances**
25+
---
26+
### SSH Into EC2 Instance
27+
- First head to your [EC2 dashboard](https://console.aws.amazon.com/ec2/v2/home) and choose instances from the left panel
28+
- In the description of your EC2 instance copy the public DNS (iPv4) address using the copy to clipboard button
29+
- Open a terminal on your computer and use the following command to SSH into your EC2 instance
30+
```
31+
ssh i "path/to/your/keypair.pem" ubuntu@(paste the public DNS here)
32+
```
33+
>example: `ssh -i "/Users/John/Downloads/TestInstance.pem" [email protected]`
34+
- You should see a prompt for your EC2 instance like so<img src="../../assets/aws_ubuntu.png">
35+
- 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)
36+
- With the URL in the clipboard, run:
37+
```
38+
wget https://github.com/codercom/code-server/releases/download/0.1.4/code-server-linux
39+
```
40+
- If you run into any permission errors, make the binary executable by running:
41+
```
42+
chmod +x code-server-linux
43+
```
44+
> To ensure the connection between you and your server is encrypted view our guide on [securing your setup](../security/ssl.md)
45+
- Finally, run
46+
```
47+
sudo ./code-server-linux -p 80
48+
```
49+
- 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"**<img src ="../../assets/chrome_warning.png">
50+
- Then click **"proceed anyway"**<img src="../../assets/chrome_confirm.png">
51+
52+
> 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
53+
54+
> 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.
55+
56+
---
57+
> 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:[email protected]?subject=Self-hosted%20quickstart%20guide).

‎doc/admin/install/digitalocean.md

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Deploy on DigitalOcean
2+
3+
This tutorial shows you how to deploy `code-server` to a single node running on DigitalOcean.
4+
5+
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)
6+
7+
---
8+
9+
## Use the "Create Droplets" wizard
10+
11+
[Open your DigitalOcean dashboard](https://cloud.digitalocean.com/droplets/new) to create a new droplet
12+
13+
- **Choose an image -** Select the **Distributions** tab and then choose Ubuntu
14+
- **Choose a size -** We recommend at least 4GB RAM and 2 CPU, more depending on team size and number of repositories/languages enabled.
15+
- Launch your instance
16+
- Open a terminal on your computer and SSH into your instance
17+
> example: ssh [email protected]
18+
- 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
19+
- In the shell run the below command with the URL from your clipboard
20+
```
21+
wget https://github.com/codercom/code-server/releases/download/0.1.4/code-server-linux
22+
```
23+
- If you run into any permission errors when attempting to run the binary:
24+
```
25+
chmod +x code-server-linux
26+
```
27+
> To ensure the connection between you and your server is encrypted view our guide on [securing your setup](../security/ssl.md)
28+
- Finally start the code-server
29+
```
30+
sudo ./code-server-linux -p80
31+
```
32+
> 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
33+
- 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"**<img src ="../../assets/chrome_warning.png">
34+
- Then click **"proceed anyway"**<img src="../../assets/chrome_confirm.png">
35+
36+
---
37+
> 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:[email protected]?subject=Self-hosted%20quickstart%20guide).

‎doc/admin/install/google_cloud.md

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Deploy on Google Cloud
2+
3+
This tutorial shows you how to deploy `code-server` to a single node running on Google Cloud.
4+
5+
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)
6+
7+
---
8+
9+
## Deploy to Google Cloud VM
10+
> Pre-requisite: Please [set up Google Cloud SDK](https://cloud.google.com/sdk/docs/) on your local machine
11+
12+
- [Open your Google Cloud console](https://console.cloud.google.com/compute/instances) to create a new VM instance and click **Create Instance**
13+
- 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)
14+
- Choose Ubuntu 16.04 LTS as your boot disk
15+
- Check the boxes for **Allow HTTP traffic** and **Allow HTTPS traffic** in the **Firewall** section
16+
- Create your VM, and **take note** of it's public IP address.
17+
- Copy the link to download the latest Linux binary from our [releases page](https://github.com/codercom/code-server/releases)
18+
19+
---
20+
21+
## Final Steps
22+
23+
1. SSH into your Google Cloud VM
24+
```
25+
gcloud compute ssh --zone [region] [instance name]
26+
```
27+
2. Download the binary using the link we copied to clipboard
28+
```
29+
wget https://github.com/codercom/code-server/releases/download/0.1.4/code-server-linux
30+
```
31+
3. Make the binary executable if you run into any errors regarding permission:
32+
```
33+
chmod +x code-server-linux
34+
```
35+
> To ensure the connection between you and your server is encrypted view our guide on [securing your setup](../security/ssl.md)
36+
4. Start the code-server
37+
```
38+
sudo ./code-server-linux -p 80
39+
```
40+
> 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
41+
5. Access code-server from the public IP of your Google Cloud instance we noted earlier in your browser.
42+
> example: 32.32.32.234
43+
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"**<img src ="../../assets/chrome_warning.png">
44+
7. Then click **"proceed anyway"**<img src="../../assets/chrome_confirm.png">
45+
---
46+
> 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:[email protected]?subject=Self-hosted%20quickstart%20guide).

‎doc/assets/aws_ubuntu.png

51.6 KB
Loading

‎doc/assets/chrome_confirm.png

34.1 KB
Loading

‎doc/assets/chrome_warning.png

44.3 KB
Loading

‎doc/assets/cli.png

161 KB
Loading

‎doc/assets/ide.png

985 KB
Loading

‎doc/assets/logo-horizontal.png

22 KB
Loading

‎doc/assets/server-password-modal.png

96.7 KB
Loading

‎doc/security/ssl.md

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Generate a self-signed certificate 🔒
2+
3+
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.
4+
5+
This guide will show you how to create a self-signed certificate and start code-server using your certificate/key.
6+
7+
## TLS / HTTPS
8+
9+
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.
10+
11+
```shell
12+
mkdir ~/certs && cd ~/certs
13+
```
14+
15+
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`
16+
17+
```shell
18+
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ~/certs/MyKey.key -out ~/certs/MyCertificate.crt
19+
```
20+
21+
You will be prompted to add some identifying information about your organization
22+
```shell
23+
You are about to be asked to enter information that will be incorporated
24+
into your certificate request.
25+
What you are about to enter is what is called a Distinguished Name or a DN.
26+
There are quite a few fields but you can leave some blank
27+
For some fields there will be a default value,
28+
If you enter '.', the field will be left blank.
29+
-----
30+
Country Name (2 letter code) [AU]:US
31+
State or Province Name (full name) [Some-State]:TX
32+
Locality Name (eg, city) []:Austin
33+
Organization Name (eg, company) [Coder Technologies]:Coder
34+
Organizational Unit Name (eg, section) []:Docs
35+
Common Name (e.g. server FQDN or YOUR name) []:hostname.example.com
36+
Email Address []:[email protected]
37+
```
38+
>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
39+
40+
41+
## Starting code-server with certificate and key
42+
43+
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.
44+
```shell
45+
./code-server --cert=~/certs/MyCertificate.crt --cert-key=~/certs/MyKey.key
46+
```
47+
2. After that you will be running a secure code-server.
48+
49+
> 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.
50+
51+
## Other options
52+
53+
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/).

0 commit comments

Comments
 (0)