parent
e0dbd8f74a
commit
3a1e3bc596
|
@ -8,4 +8,4 @@ ExecStart=/usr/bin/code-server
|
|||
Restart=always
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
WantedBy=default.target
|
||||
|
|
88
doc/guide.md
88
doc/guide.md
|
@ -4,7 +4,7 @@
|
|||
|
||||
- [1. Acquire a remote machine](#1-acquire-a-remote-machine)
|
||||
- [Requirements](#requirements)
|
||||
- [Google Cloud Platform](#google-cloud-platform)
|
||||
- [Google Cloud](#google-cloud)
|
||||
- [2. Install code-server](#2-install-code-server)
|
||||
- [3. Expose code-server](#3-expose-code-server)
|
||||
- [SSH forwarding](#ssh-forwarding)
|
||||
|
@ -18,10 +18,10 @@
|
|||
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.
|
||||
|
||||
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
|
||||
easily access it.
|
||||
securely access it.
|
||||
|
||||
## 1. Acquire a remote machine
|
||||
|
||||
|
@ -35,9 +35,9 @@ For a good experience, we recommend at least:
|
|||
- 1 GB of RAM
|
||||
- 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
|
||||
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.
|
||||
|
||||
1. Navigate to `Compute Engine -> VM Instances` on the sidebar
|
||||
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)
|
||||
4. Name it whatever you want
|
||||
5. Any zone is fine
|
||||
6. We'd recommend a `e2-standard-2` instance from the E2 series and General-purpose family
|
||||
- Add more vCPUs and memory as you prefer, you can edit after creating the instance as well
|
||||
1. Navigate to `Compute Engine -> VM Instances` on the sidebar.
|
||||
2. Now click `Create Instance` to create a new instance.
|
||||
3. 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.
|
||||
6. We'd recommend a `E2` series instance from the General-purpose family.
|
||||
- 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
|
||||
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
|
||||
to use a static external IP
|
||||
- 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
|
||||
to use a static external IP.
|
||||
- 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.
|
||||
10. Click create!
|
||||
|
||||
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
|
||||
|
||||
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**
|
||||
expose it directly to the internet without some form of authentication and encryption!
|
||||
There are several approaches to securely operating and exposing code-server.
|
||||
|
||||
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
|
||||
|
@ -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`
|
||||
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
|
||||
# -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.
|
||||
First, ssh into your instance and edit your code-server config file to disable password authentication.
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
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!
|
||||
|
||||
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.
|
||||
# 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:
|
||||
|
@ -149,14 +153,14 @@ and sign commits without copying your keys onto the instance.
|
|||
|
||||
### Let's Encrypt
|
||||
|
||||
Let's Encrypt is a great option if you want to access code-server on an iPad or just want password
|
||||
based authentication. This does require that the remote machine is exposed to the internet.
|
||||
[Let's Encrypt](https://letsencrypt.org) is a great option if you want to access code-server on an iPad
|
||||
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.
|
||||
|
||||
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
|
||||
3. Install caddy https://caddyserver.com/docs/download#debian-ubuntu-raspbian
|
||||
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.
|
||||
3. Install caddy https://caddyserver.com/docs/download#debian-ubuntu-raspbian.
|
||||
|
||||
```bash
|
||||
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
|
||||
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
|
||||
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:
|
||||
|
||||
|
@ -217,8 +225,8 @@ Edit your instance and checkmark the allow HTTPS traffic option.
|
|||
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 can also use [mkcert](https://mkcert.dev) to create a self signed certificate trusted by your
|
||||
OS to avoid the warnings and then pass it to code-server via the `cert` and `cert-key` config
|
||||
To avoid the warnings, you can use [mkcert](https://mkcert.dev) to create a self signed certificate
|
||||
trusted by your OS and then pass it into code-server via the `cert` and `cert-key` config
|
||||
fields.
|
||||
|
||||
### 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.
|
||||
|
||||
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).
|
||||
|
|
Loading…
Reference in New Issue