9.0 KiB
Setup Guide
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 for a general overview and the FAQ 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.
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.
Google Cloud Platform
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.
- Navigate to
Compute Engine -> VM Instances
on the sidebar - Now click
Create Instance
to create a new instance - Choose the region closest to you based on gcping.com
- Name it whatever you want
- Any zone is fine
- 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
- https://cloud.google.com/compute/docs/machine-types#general_purpose
- We highly recommend switching the persistent disk to a SSD of at least 32 GB
- Navigate to
Networking -> Network interfaces
and edit the existing interface to use a static external IP- Click done to save network interface changes
- If you do not have a project wide SSH key, navigate to
Security - > SSH Keys
and add your public key there - Click create!
Remember, you can shutdown your server when not in use to lower costs.
We highly recommend learning to use the gcloud
cli
to avoid the slow dashboard.
2. Install code-server
SSH into your instance and run the appropriate commands documented in README.md.
Assuming Debian:
curl -sSOL https://github.com/cdr/code-server/releases/download/3.3.0/code-server_3.3.0_amd64.deb
sudo dpkg -i code-server_3.3.0_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
There are several approaches to operating and exposing code-server.
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!
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
can also set a custom password with $PASSWORD
.
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.
Recommended reading: https://help.ubuntu.com/community/SSH/OpenSSH/PortForwarding
# -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.
# 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):
systemctl --user restart 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 mutagen.
# 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
We also recommend adding the following lines to your ~/.ssh/config
to quickly detect bricked SSH connections:
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.
- https://developer.github.com/v3/guides/using-ssh-agent-forwarding/
- https://wiki.gnupg.org/AgentForwarding
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.
Assuming you have been following the guide, edit your instance and checkmark the allow HTTP/HTTPS traffic options.
- You'll need to buy a domain name. We recommend Google Domains
- Add an A record to your domain with your instance's IP
- Install caddy https://caddyserver.com/docs/download#debian-ubuntu-raspbian
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
- Replace
/etc/caddy/Caddyfile
with sudo to look like this:
mydomain.com
reverse_proxy 127.0.0.1:8080
- Reload caddy with:
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 instead.
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.
ssh into your instance and edit your code-server config file to use a randomly generated self signed certificate:
# 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:
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.
You can also use mkcert 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
fields.
Change the password?
Edit the code-server config file at ~/.config/code-server/config.yaml
and then restart
code-server with:
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 the FAQ.