OCram85/code-server
Archived
1
0
Fork 0
Code Pull Requests 2 Activity

Add doc/guide.md

Browse Source
This commit is contained in:
Anmol Sethi
2020-05-14 03:17:17 -04:00
parent f4a78587b0
commit a0a77e379e
11 changed files with 537 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
doc/FAQ.md
View File

@ -1,9 +1,31 @@
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
# FAQ
- [Questions?](#questions)
- [What's the deal with extensions?](#whats-the-deal-with-extensions)
- [Where are extensions stored?](#where-are-extensions-stored)
- [How is this different from VS Code Codespaces?](#how-is-this-different-from-vs-code-codespaces)
- [How should I expose code-server to the internet?](#how-should-i-expose-code-server-to-the-internet)
- [How do I securely access web services?](#how-do-i-securely-access-web-services)
- [Sub-domains](#sub-domains)
- [Sub-paths](#sub-paths)
- [Multi Tenancy](#multi-tenancy)
- [Docker in code-server docker container?](#docker-in-code-server-docker-container)
- [Collaboration](#collaboration)
- [How can I disable telemetry?](#how-can-i-disable-telemetry)
- [How does code-server decide what workspace or folder to open?](#how-does-code-server-decide-what-workspace-or-folder-to-open)
- [How do I debug issues with code-server?](#how-do-i-debug-issues-with-code-server)
- [Heartbeat file](#heartbeat-file)
- [Enterprise](#enterprise)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Questions?
Please file all questions and support requests at https://www.reddit.com/r/codeserver/
The issue tracker is only for bugs.
Please file all questions and support requests at https://www.reddit.com/r/codeserver/.
The issue tracker is **only** for bugs.
## What's the deal with extensions?
@ -23,42 +45,53 @@ Issue [#1299](https://github.com/cdr/code-server/issues/1299) is a big one in ma
better by allowing the community to submit extensions and repos to avoid waiting until the scraper finds
an extension.
If an extension does not work, try to grab its VSIX from its Github releases or build it yourself and
copy it to the extensions folder.
If an extension is not available or does not work, you can grab its VSIX from its Github releases or
build it yourself and [Install from VSIX](https://code.visualstudio.com/docs/editor/extension-gallery#_install-from-a-vsix).
## How is this different from VS Code Online?
Feel free to file an issue to add a missing extension to the marketplace.
VS Code Online is a closed source managed service by Microsoft and only runs on Azure.
## Where are extensions stored?
code-server is open source and can be freely run on any machine.
Defaults to `~/.local/share/code-server/extensions`.
If the `XDG_DATA_HOME` environment variable is set the data directory will be
`$XDG_DATA_HOME/code-server/extensions`.
You can install an extension on the CLI with:
```bash
# From the Coder extension marketplace
code-server --install-extension ms-python.python
# From a downloaded VSIX on the file system
code-server --install-extension downloaded-ms-python.python.vsix
```
## How is this different from VS Code Codespaces?
VS Code Codespaces is a closed source and paid service by Microsoft. It also allows you to access
VS Code via the browser.
However, code-server is free, open source and can be ran on any machine without any limitations.
While you can self host environments with VS Code Codespaces, you still need to an Azure billing
account and you access VS Code via the Codespaces web dashboard instead of directly connecting to
your instance.
## How should I expose code-server to the internet?
By far the most secure method of using code-server is via
[sshcode](https://github.com/codercom/sshcode) as it runs code-server and then forwards
its port over SSH and requires no setup on your part other than having a working SSH server.
Please follow [./guide.md]](./guide.md) for our recommendations on setting up and using code-server.
You can also forward your SSH key and GPG agent to the remote machine to securely access GitHub
and securely sign commits without duplicating your keys onto the the remote machine.
1. https://developer.github.com/v3/guides/using-ssh-agent-forwarding/
1. https://wiki.gnupg.org/AgentForwarding
If you cannot use sshcode, then you will need to ensure there is some sort of authorization in
front of code-server and that you are using HTTPS to secure all connections.
By default when listening externally, code-server enables password authentication using a
randomly generated password so you can use that. You can set the `PASSWORD` environment variable
to use your own instead. If you want to handle authentication yourself, use `--auth none`
to disable password authentication.
code-server only supports password authentication natively.
**note**: code-server will rate limit password authentication attempts at 2 a minute and 12 an hour.
If you want to use external authentication you should handle this with a reverse
proxy using something like [oauth2_proxy](https://github.com/pusher/oauth2_proxy).
If you want to use external authentication (i.e sign in with Google) you should handle this
with a reverse proxy using something like [oauth2_proxy](https://github.com/pusher/oauth2_proxy).
For HTTPS, you can use a self signed certificate by passing in just `--cert` or pass in an existing
certificate by providing the path to `--cert` and the path to its key with `--cert-key`.
For HTTPS, you can use a self signed certificate by passing in just `--cert` or
pass in an existing certificate by providing the path to `--cert` and the path to
its key with `--cert-key`.
If `code-server` has been passed a certificate it will also respond to HTTPS
requests and will redirect all HTTP requests to HTTPS. Otherwise it will respond
@ -67,6 +100,8 @@ only to HTTP requests.
You can use [Let's Encrypt](https://letsencrypt.org/) to get an SSL certificate
for free.
Again, Please follow [./guide.md]](./guide.md) for our recommendations on setting up and using code-server.
## How do I securely access web services?
code-server is capable of proxying to any port using either a subdomain or a
@ -96,15 +131,6 @@ ensure your reverse proxy forwards that information if you are using one.
Just browse to `/proxy/<port>/`.
## x86 releases?
node has dropped support for x86 and so we decided to as well. See
[nodejs/build/issues/885](https://github.com/nodejs/build/issues/885).
## Alpine builds?
Just install `libc-dev` and code-server should work.
## Multi Tenancy
If you want to run multiple code-server's on shared infrastructure, we recommend using virtual
@ -127,8 +153,9 @@ to make volume mounts in any other directory work.
## Collaboration
At the moment we have no plans for multi user collaboration on code-server but we understand there is strong
demand and will work on it when the time is right.
We understand the high demand but the team is swamped right now.
You can follow progress at [#33](https://github.com/cdr/code-server/issues/33).
## How can I disable telemetry?
@ -165,13 +192,16 @@ information from the following places:
Additionally, collecting core dumps (you may need to enable them first) if
code-server crashes can be helpful.
### Where is the data directory?
## Heartbeat file
If the `XDG_DATA_HOME` environment variable is set the data directory will be
`$XDG_DATA_HOME/code-server`. Otherwise:
`code-server` touches `~/.local/share/code-server/heartbeat` once a minute as long
as there is an active browser connection.
1. Unix: `~/.local/share/code-server`
1. Windows: `%APPDATA%\Local\code-server\Data`
If you want to shutdown `code-server` if there hasn't been an active connection in X minutes
you can do so by continously checking the last modified time on the heartbeat file and if it is
older than X minutes, you should kill `code-server`.
[#1636](https://github.com/cdr/code-server/issues/1636) will make the experience here better.
## Enterprise

236
doc/guide.md Normal file
View File

@ -0,0 +1,236 @@
<!-- 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 Platform](#google-cloud-platform)
- [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.
See the [README](../README.md) for a general overview and the [FAQ](./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.
## 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.
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
- 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
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 -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](#lets-encrypt).
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.
```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 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 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:
```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 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.
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-instance-ip>` 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.
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:
```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.
You can also use [mkcert](https://mkcert.dev) to create a self signed certificate trusted by your
OS to avoid the warnings.
### 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 the [FAQ](https://github.com/cdr/code-server/blob/master/doc/FAQ.md#how-do-i-securely-access-web-services).