11 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.
Further docs are at:
- README for a general overview
- INSTALL for installation
- FAQ for common questions.
- CONTRIBUTING for development docs
We highly recommend reading the FAQ on the Differences compared to VS Code before beginning.
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.
- Navigate to
Compute Engine -> VM Instances
on the sidebar. - Now click
Create Instance
to create a new instance. - Name it whatever you want.
- Choose the region closest to you based on gcping.com.
- Any zone is fine.
- 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
- We highly recommend switching the persistent disk to an SSD of at least 32 GB.
- Click
Change
underBoot Disk
and change the type toSSD Persistent Disk
and the size to32
. - You can always grow your disk later.
- Click
- 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
We have a script to install code-server
for Linux, macOS and FreeBSD.
It tries to use the system package manager if possible.
First run to print out the install process:
curl -fsSL https://code-server.dev/install.sh | sh -s -- --dry-run
Now to actually install:
curl -fsSL https://code-server.dev/install.sh | sh
The install script will print out how to run and start using code-server
.
Docs on the install script, manual installation and docker image are at ./install.md.
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 thecode-server
config file to login. It will listen onlocalhost
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
on any machine without an SSH client like on iPad. If that's important to you, skip to Let's Encrypt.
First, 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):
sudo systemctl restart code-server@$USER
Now forward local port 8080 to 127.0.0.1:8080
on the remote instance by running the following command on your local machine.
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 [user]@<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.
# 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:
Host *
ServerAliveInterval 5
ExitOnForwardFailure yes
You can also forward your SSH and GPG agent to the instance to securely access GitHub and sign commits without copying your keys.
- 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 do not want to use SSH forwarding. This does require that the remote machine be 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
Remember to replace mydomain.com
with your domain name!
- 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.
NGINX
If you prefer to use NGINX instead of Caddy then please follow steps 1-2 above and then:
- Install
nginx
:
sudo apt update
sudo apt install -y nginx certbot python-certbot-nginx
- Put the following config into
/etc/nginx/sites-available/code-server
with sudo:
server {
listen 80;
listen [::]:80;
server_name mydomain.com;
location / {
proxy_pass http://localhost:8080/;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection upgrade;
proxy_set_header Accept-Encoding gzip;
}
}
Remember to replace mydomain.com
with your domain name!
- Enable the config:
sudo ln -s ../sites-available/code-server /etc/nginx/sites-enabled/code-server
sudo certbot --non-interactive --redirect --agree-tos --nginx -d mydomain.com -m me@example.com
Make sure to substitute me@example.com
with your actual email.
Visit https://<your-domain-name>
to access code-server
. Congratulations!
Self Signed Certificate
note: Self signed certificates do not work with iPad normally. See ./ipad.md for details.
Recommended reading: https://security.stackexchange.com/a/8112.
We recommend this as a last resort because 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 you cannot expose the remote machine to the internet.
- 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:
# 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:
sudo systemctl restart code-server@$USER
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 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 password
field in the code-server
config file at ~/.config/code-server/config.yaml
and then restart code-server
with:
sudo systemctl restart code-server@$USER
Alternatively, you can specify the SHA-256 of your password at the hashed-password
field in the config file.
The hashed-password
field takes precedence over password
.
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.