252 lines
9.6 KiB
Markdown
252 lines
9.6 KiB
Markdown
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
|
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
|
# Setup Guide
|
|
|
|
- [1. Acquire a remote machine](#1-acquire-a-remote-machine)
|
|
- [Requirements](#requirements)
|
|
- [Google Cloud](#google-cloud)
|
|
- [2. Install code-server](#2-install-code-server)
|
|
- [3. Expose code-server](#3-expose-code-server)
|
|
- [SSH forwarding](#ssh-forwarding)
|
|
- [Let's Encrypt](#lets-encrypt)
|
|
- [Self Signed Certificate](#self-signed-certificate)
|
|
- [Change the password?](#change-the-password)
|
|
- [How do I securely access development web services?](#how-do-i-securely-access-development-web-services)
|
|
|
|
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
|
|
|
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.
|
|
|
|
Further docs are at:
|
|
|
|
- [README.md](../README.md) for a general overview
|
|
- [FAQ.md](./FAQ.md) for common questions.
|
|
- [CONTRIBUTING.md](../doc/CONTRIBUTING.md) for development docs
|
|
|
|
We'll walk you through acquiring a remote machine to run code-server on and then exposing `code-server` so you can
|
|
securely access it.
|
|
|
|
## 1. Acquire a remote machine
|
|
|
|
First, you need a machine to run code-server on. You can use a physical
|
|
machine you have lying around or use a VM on GCP/AWS.
|
|
|
|
### Requirements
|
|
|
|
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 on Google Cloud.
|
|
|
|
### 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.
|
|
|
|
You can sign up at https://console.cloud.google.com/getting-started. You'll get a 12 month \$300
|
|
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. 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.
|
|
- 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.
|
|
10. Click create!
|
|
|
|
Remember, you can shutdown your server when not in use to lower costs.
|
|
We highly recommend learning to use the [`gcloud`](https://cloud.google.com/sdk/gcloud) cli
|
|
to avoid the slow dashboard.
|
|
|
|
## 2. Install code-server
|
|
|
|
SSH into your instance and run the appropriate commands documented in [README.md](../README.md).
|
|
|
|
Assuming Debian:
|
|
|
|
```bash
|
|
curl -OL https://github.com/cdr/code-server/releases/download/v3.3.1/code-server_3.3.1_amd64.deb
|
|
sudo dpkg -i code-server_3.3.1_amd64.deb
|
|
systemctl --user enable --now code-server
|
|
# Now code-server is running at http://127.0.0.1:8080
|
|
# Your password is in ~/.config/code-server/config.yaml
|
|
```
|
|
|
|
## 3. Expose 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.
|
|
|
|
By default, code-server will enable password authentication which will
|
|
require you to copy the password from the code-server config file to login. Since it
|
|
cannot use TLS by default, it will listen on `localhost` to avoid exposing itself
|
|
to the world. This is fine for testing but will not work if you want to access `code-server`
|
|
from a different machine.
|
|
|
|
There are several approaches to securely operating and exposing code-server.
|
|
|
|
**tip**: You can list the full set of code-server options with `code-server --help`
|
|
|
|
### SSH forwarding
|
|
|
|
We highly recommend this approach for not requiring any additional setup, you just need an
|
|
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.
|
|
|
|
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.
|
|
sed -i.bak 's/auth: password/auth: none/' ~/.config/code-server/config.yaml
|
|
```
|
|
|
|
Restart code-server with (assuming you followed the guide):
|
|
|
|
```bash
|
|
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
|
|
[mutagen](https://mutagen.io/documentation/introduction/installation).
|
|
|
|
```
|
|
# Same as the above SSH command but runs in the background continuously.
|
|
# Add `mutagen daemon start` to your ~/.bashrc to start the mutagen daemon when you open a shell.
|
|
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:
|
|
|
|
```bash
|
|
Host *
|
|
ServerAliveInterval 5
|
|
ExitOnForwardFailure yes
|
|
```
|
|
|
|
You can also forward your SSH key and GPG agent to the instance to securely access GitHub
|
|
and sign commits without copying your keys onto the instance.
|
|
|
|
1. https://developer.github.com/v3/guides/using-ssh-agent-forwarding/
|
|
2. https://wiki.gnupg.org/AgentForwarding
|
|
|
|
### Let's Encrypt
|
|
|
|
[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.
|
|
|
|
```bash
|
|
echo "deb [trusted=yes] https://apt.fury.io/caddy/ /" \
|
|
| sudo tee -a /etc/apt/sources.list.d/caddy-fury.list
|
|
sudo apt update
|
|
sudo apt install caddy
|
|
```
|
|
|
|
4. Replace `/etc/caddy/Caddyfile` with sudo to look like this:
|
|
|
|
```
|
|
mydomain.com
|
|
|
|
reverse_proxy 127.0.0.1:8080
|
|
```
|
|
|
|
5. Reload caddy with:
|
|
|
|
```bash
|
|
sudo systemctl reload caddy
|
|
```
|
|
|
|
Visit `https://<your-domain-name>` to access code-server. Congratulations!
|
|
|
|
In a future release we plan to integrate Let's Encrypt directly with code-server to avoid
|
|
the dependency on caddy.
|
|
|
|
### Self Signed Certificate
|
|
|
|
**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. See the [FAQ](https://github.com/cdr/code-server/blob/master/doc/FAQ.md#blank-screen-on-ipad).
|
|
|
|
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:
|
|
|
|
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:
|
|
|
|
```bash
|
|
# Replaces "cert: false" with "cert: true" in the code-server config.
|
|
sed -i.bak 's/cert: false/cert: true/' ~/.config/code-server/config.yaml
|
|
# Replaces "bind-addr: 127.0.0.1:8080" with "bind-addr: 0.0.0.0:443" in the code-server config.
|
|
sed -i.bak 's/bind-addr: 127.0.0.1:8080/bind-addr: 0.0.0.0:443/' ~/.config/code-server/config.yaml
|
|
# Allows code-server to listen on port 443.
|
|
sudo setcap cap_net_bind_service=+ep /usr/lib/code-server/lib/node
|
|
```
|
|
|
|
Assuming you have been following the guide, restart code-server with:
|
|
|
|
```bash
|
|
systemctl --user restart code-server
|
|
```
|
|
|
|
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.
|
|
|
|
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?
|
|
|
|
Edit the code-server config file at `~/.config/code-server/config.yaml` and then restart
|
|
code-server with:
|
|
|
|
```bash
|
|
systemctl --user restart code-server
|
|
```
|
|
|
|
### How do I securely access development web services?
|
|
|
|
If you're working on a web service and want to access it locally, code-server can proxy it for you.
|
|
|
|
See [FAQ.md](https://github.com/cdr/code-server/blob/master/doc/FAQ.md#how-do-i-securely-access-web-services).
|