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

Final revisions for the docs before release

Browse Source 
🚀
This commit is contained in:
Anmol Sethi 2020-05-17 17:51:56 -04:00
parent e0dbd8f74a
commit 3a1e3bc596
No known key found for this signature in database
GPG Key ID: 8CEF1878FF10ADEB
2 changed files with 49 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
ci/build/code-server.service
View File

@ -8,4 +8,4 @@ ExecStart=/usr/bin/code-server
Restart=always Restart=always
[Install] [Install]
WantedBy=multi-user.target WantedBy=default.target

88
doc/guide.md
View File

@ -4,7 +4,7 @@
- [1. Acquire a remote machine](#1-acquire-a-remote-machine) - [1. Acquire a remote machine](#1-acquire-a-remote-machine)
- [Requirements](#requirements) - [Requirements](#requirements)
- [Google Cloud Platform](#google-cloud-platform) - [Google Cloud](#google-cloud)
- [2. Install code-server](#2-install-code-server) - [2. Install code-server](#2-install-code-server)
- [3. Expose code-server](#3-expose-code-server) - [3. Expose code-server](#3-expose-code-server)
- [SSH forwarding](#ssh-forwarding) - [SSH forwarding](#ssh-forwarding)
@ -18,10 +18,10 @@
This guide demonstrates how to setup and use code-server. This guide demonstrates how to setup and use code-server.
To reiterate, code-server lets you run VS Code on a remote server and then access it via a browser. To reiterate, code-server lets you run VS Code on a remote server and then access it via a browser.
See the [README](../README.md) for a general overview and the [FAQ](./FAQ.md) for further user docs. See [README.md](../README.md) for a general overview and [FAQ.md](./FAQ.md) for further user 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 and then exposing `code-server` so you can
easily access it. securely access it.
## 1. Acquire a remote machine ## 1. Acquire a remote machine
@ -35,9 +35,9 @@ For a good experience, we recommend at least:
- 1 GB of RAM - 1 GB of RAM
- 2 cores - 2 cores
You can use whatever linux distribution floats your boat but in this guide we assume Debian. You can use whatever linux distribution floats your boat but in this guide we assume Debian on Google Cloud.
### Google Cloud Platform ### Google Cloud
For demonstration purposes, this guide assumes you're using a VM on GCP but you should be For demonstration purposes, this guide assumes you're using a VM on GCP but you should be
able to easily use any machine or VM provider. able to easily use any machine or VM provider.
@ -47,19 +47,24 @@ free trial.
Once you've signed up and created a GCP project, create a new Compute Engine VM Instance. Once you've signed up and created a GCP project, create a new Compute Engine VM Instance.
1. Navigate to `Compute Engine -> VM Instances` on the sidebar 1. Navigate to `Compute Engine -> VM Instances` on the sidebar.
2. Now click `Create Instance` to create a new instance 2. Now click `Create Instance` to create a new instance.
3. Choose the region closest to you based on [gcping.com](http://www.gcping.com) 3. Name it whatever you want.
4. Name it whatever you want 4. Choose the region closest to you based on [gcping.com](http://www.gcping.com).
5. Any zone is fine 5. Any zone is fine.
6. We'd recommend a `e2-standard-2` instance from the E2 series and General-purpose family 6. We'd recommend a `E2` series instance from the General-purpose family.
- Add more vCPUs and memory as you prefer, you can edit after creating the instance as well - 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.
- 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 a SSD of at least 32 GB.
- Click `Change` under `Boot Disk` and change the type to `SSD Persistent Disk` and the size
to `32`.
- You can always grow your disk later.
- The default OS of Debian 10 is fine.
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.
@ -82,10 +87,10 @@ systemctl --user enable --now code-server
## 3. Expose code-server ## 3. Expose code-server
There are several approaches to operating and exposing code-server. **Never**, **ever** expose `code-server` directly to the internet without some form of authentication
and encryption as someone can completely takeover your machine with the terminal.
Since you can gain access to a terminal from within code-server, **never**, **ever** There are several approaches to securely operating and exposing code-server.
expose it directly to the internet without some form of authentication and encryption!
By default, code-server will enable password authentication which will By default, code-server will enable password authentication which will
require you to copy the password from the code-server config file to login. You require you to copy the password from the code-server config file to login. You
@ -99,17 +104,9 @@ We highly recommend this approach for not requiring any additional setup, you ju
SSH server on your remote machine. The downside is you won't be able to access `code-server` SSH server on your remote machine. The downside is you won't be able to access `code-server`
without an SSH client like an iPad. If that's important to you, skip to [Let's Encrypt](#lets-encrypt). without an SSH client like an iPad. If that's important to you, skip to [Let's Encrypt](#lets-encrypt).
Recommended reading: https://help.ubuntu.com/community/SSH/OpenSSH/PortForwarding Recommended reading: https://help.ubuntu.com/community/SSH/OpenSSH/PortForwarding.
```bash First, ssh into your instance and edit your code-server config file to disable password authentication.
# -N disables executing a remote shell
ssh -N -L 8080:127.0.0.1:8080 <instance-ip>
```
As long as this command hasn't exited, that means any request on local port 8080 goes to your
instance at `127.0.0.1:8080` which is where code-server is running.
Next ssh into your instance and edit your code-server config file to disable password authentication.
```bash ```bash
# Replaces "auth: password" with "auth: none" in the code-server config. # Replaces "auth: password" with "auth: none" in the code-server config.
@ -122,6 +119,13 @@ Restart code-server with (assuming you followed the guide):
systemctl --user restart code-server systemctl --user restart code-server
``` ```
Now forward local port 8080 to `127.0.0.1:8080` on the remote instance.
```bash
# -N disables executing a remote shell
ssh -N -L 8080:127.0.0.1:8080 <instance-ip>
```
Now if you access http://127.0.0.1:8080 locally, you should see code-server! Now if you access http://127.0.0.1:8080 locally, you should see code-server!
If you want to make the SSH port forwarding persistent we recommend using If you want to make the SSH port forwarding persistent we recommend using
@ -130,7 +134,7 @@ If you want to make the SSH port forwarding persistent we recommend using
``` ```
# Same as the above SSH command but runs in the background continously. # Same as the above SSH command but runs in the background continously.
# Add `mutagen daemon start` to your ~/.bashrc to start the mutagen daemon when you open a shell. # Add `mutagen daemon start` to your ~/.bashrc to start the mutagen daemon when you open a shell.
mutagen forward create --help -n=code-server tcp:127.0.0.1:8080 <instance-ip>:tcp:127.0.0.1:8080 mutagen forward create --name=code-server tcp:127.0.0.1:8080 <instance-ip>:tcp:127.0.0.1:8080
``` ```
We also recommend adding the following lines to your `~/.ssh/config` to quickly detect bricked SSH connections: We also recommend adding the following lines to your `~/.ssh/config` to quickly detect bricked SSH connections:
@ -149,14 +153,14 @@ and sign commits without copying your keys onto the instance.
### Let's Encrypt ### Let's Encrypt
Let's Encrypt is a great option if you want to access code-server on an iPad or just want password [Let's Encrypt](https://letsencrypt.org) is a great option if you want to access code-server on an iPad
based authentication. This does require that the remote machine is exposed to the internet. or do not want to use SSH forwarding. This does require that the remote machine is exposed to the internet.
Assuming you have been following the guide, edit your instance and checkmark the allow HTTP/HTTPS traffic options. Assuming you have been following the guide, edit your instance and checkmark the allow HTTP/HTTPS traffic options.
1. You'll need to buy a domain name. We recommend [Google Domains](https://domains.google.com) 1. You'll need to buy a domain name. We recommend [Google Domains](https://domains.google.com).
2. Add an A record to your domain with your instance's IP 2. Add an A record to your domain with your instance's IP.
3. Install caddy https://caddyserver.com/docs/download#debian-ubuntu-raspbian 3. Install caddy https://caddyserver.com/docs/download#debian-ubuntu-raspbian.
```bash ```bash
echo "deb [trusted=yes] https://apt.fury.io/caddy/ /" \ echo "deb [trusted=yes] https://apt.fury.io/caddy/ /" \
@ -189,11 +193,15 @@ the dependency on caddy.
**note:** Self signed certificates do not work with iPad and will cause a blank page. You'll **note:** Self signed certificates do not work with iPad and will cause a blank page. You'll
have to use [Let's Encrypt](#lets-encrypt) instead. have to use [Let's Encrypt](#lets-encrypt) instead.
Recommended reading: https://security.stackexchange.com/a/8112 Recommended reading: https://security.stackexchange.com/a/8112.
We recommend this as a last resort as self signed certificates do not work with iPads and can We recommend this as a last resort as self signed certificates do not work with iPads and can
cause other bizarre issues. Not to mention all the warnings when you access code-server. cause other bizarre issues. Not to mention all the warnings when you access code-server.
Only use this if you do not want to buy a domain or cannot expose the remote machine to the internet. Only use this if:
1. You do not want to buy a domain.
2. You cannot expose the remote machine to the internet.
3. You do not want to use SSH forwarding.
ssh into your instance and edit your code-server config file to use a randomly generated self signed certificate: ssh into your instance and edit your code-server config file to use a randomly generated self signed certificate:
@ -217,8 +225,8 @@ Edit your instance and checkmark the allow HTTPS traffic option.
Visit `https://<your-instance-ip>` to access code-server. Visit `https://<your-instance-ip>` to access code-server.
You'll get a warning when accessing but if you click through you should be good. You'll get a warning when accessing but if you click through you should be good.
You can also use [mkcert](https://mkcert.dev) to create a self signed certificate trusted by your To avoid the warnings, you can use [mkcert](https://mkcert.dev) to create a self signed certificate
OS to avoid the warnings and then pass it to code-server via the `cert` and `cert-key` config trusted by your OS and then pass it into code-server via the `cert` and `cert-key` config
fields. fields.
### Change the password? ### Change the password?
@ -234,4 +242,4 @@ systemctl --user restart code-server
If you're working on a web service and want to access it locally, code-server can proxy it for you. If you're working on a web service and want to access it locally, code-server can proxy it for you.
See the [FAQ](https://github.com/cdr/code-server/blob/master/doc/FAQ.md#how-do-i-securely-access-web-services). See [FAQ.md](https://github.com/cdr/code-server/blob/master/doc/FAQ.md#how-do-i-securely-access-web-services).