Skip to content

Commit adf3703

Browse files
nhooyrnhooyr
committed
wip
1 parent dbcb01a commit adf3703

File tree

2 files changed

+183
-15
lines changed

2 files changed

+183
-15
lines changed

Diff for: ‎doc/FAQ.md

+39-15
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,29 @@
1+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
2+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
13
# FAQ
24

5+
- [Questions?](#questions)
6+
- [What's the deal with extensions?](#whats-the-deal-with-extensions)
7+
- [How is this different from VS Code Online?](#how-is-this-different-from-vs-code-online)
8+
- [How should I expose code-server to the internet?](#how-should-i-expose-code-server-to-the-internet)
9+
- [How do I securely access web services?](#how-do-i-securely-access-web-services)
10+
- [Sub-domains](#sub-domains)
11+
- [Sub-paths](#sub-paths)
12+
- [x86 releases?](#x86-releases)
13+
- [Multi Tenancy](#multi-tenancy)
14+
- [Docker in code-server docker container?](#docker-in-code-server-docker-container)
15+
- [Collaboration](#collaboration)
16+
- [How can I disable telemetry?](#how-can-i-disable-telemetry)
17+
- [How does code-server decide what workspace or folder to open?](#how-does-code-server-decide-what-workspace-or-folder-to-open)
18+
- [GPG and SSH forwarding](#gpg-and-ssh-forwarding)
19+
- [Enterprise](#enterprise)
20+
21+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
22+
323
## Questions?
424

5-
Please file all questions and support requests at https://www.reddit.com/r/codeserver/
25+
Please file all questions and support requests at https://www.reddit.com/r/codeserver/.
26+
627
The issue tracker is only for bugs.
728

829
## What's the deal with extensions?
@@ -34,6 +55,8 @@ code-server is open source and can be freely run on any machine.
3455

3556
## How should I expose code-server to the internet?
3657

58+
### sshcode
59+
3760
By far the most secure method of using code-server is via
3861
[sshcode](https://github.com/codercom/sshcode) as it runs code-server and then forwards
3962
its port over SSH and requires no setup on your part other than having a working SSH server.
@@ -44,21 +67,25 @@ and securely sign commits without duplicating your keys onto the the remote mach
4467
1. https://developer.github.com/v3/guides/using-ssh-agent-forwarding/
4568
1. https://wiki.gnupg.org/AgentForwarding
4669

47-
If you cannot use sshcode, then you will need to ensure there is some sort of authorization in
48-
front of code-server and that you are using HTTPS to secure all connections.
70+
### Direct
71+
72+
If you cannot use sshcode, then you will need to expose code-server directly
73+
to the internet and ensure there is some sort of authorization and that you
74+
are using HTTPS to secure all connections.
4975

50-
By default when listening externally, code-server enables password authentication using a
51-
randomly generated password so you can use that. You can set the `PASSWORD` environment variable
52-
to use your own instead. If you want to handle authentication yourself, use `--auth none`
53-
to disable password authentication.
76+
By default, code-server enables password authentication using a
77+
randomly generated password so you can use that. You can set the `PASSWORD`
78+
environment variable to use your own instead. If you want to handle
79+
authentication yourself, use `--auth none` to disable password authentication.
5480

5581
**note**: code-server will rate limit password authentication attempts at 2 a minute and 12 an hour.
5682

5783
If you want to use external authentication you should handle this with a reverse
5884
proxy using something like [oauth2_proxy](https://github.com/pusher/oauth2_proxy).
5985

60-
For HTTPS, you can use a self signed certificate by passing in just `--cert` or pass in an existing
61-
certificate by providing the path to `--cert` and the path to its key with `--cert-key`.
86+
For HTTPS, you can use a self signed certificate by passing in just `--cert` or
87+
pass in an existing certificate by providing the path to `--cert` and the path to
88+
its key with `--cert-key`.
6289

6390
If `code-server` has been passed a certificate it will also respond to HTTPS
6491
requests and will redirect all HTTP requests to HTTPS. Otherwise it will respond
@@ -101,10 +128,6 @@ Just browse to `/proxy/<port>/`.
101128
node has dropped support for x86 and so we decided to as well. See
102129
[nodejs/build/issues/885](https://github.com/nodejs/build/issues/885).
103130

104-
## Alpine builds?
105-
106-
Just install `libc-dev` and code-server should work.
107-
108131
## Multi Tenancy
109132

110133
If you want to run multiple code-server's on shared infrastructure, we recommend using virtual
@@ -127,8 +150,9 @@ to make volume mounts in any other directory work.
127150

128151
## Collaboration
129152

130-
At the moment we have no plans for multi user collaboration on code-server but we understand there is strong
131-
demand and will work on it when the time is right.
153+
We understand the high demand but tgihe team is swamped right now.
154+
155+
You can follow progress at [#33](https://github.com/cdr/code-server/issues/33).
132156

133157
## How can I disable telemetry?
134158

Diff for: ‎doc/setup.md

+144
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
2+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
3+
# Setup Guide
4+
5+
- [Machine](#machine)
6+
- [Requirements](#requirements)
7+
- [Install](#install)
8+
- [Authentication](#authentication)
9+
10+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
11+
12+
This guide will explain how to setup and use code-server. To reiterate, code-server
13+
lets you run VS Code on a remote server and then access it via a browser.
14+
15+
See the [README](../README.md) for a general overview and the [FAQ](./FAQ.md) for further docs.
16+
17+
## Machine
18+
19+
First, you need a machine to run code-server on. You can use a physical
20+
machine you have lying around or use a VM on GCP/AWS.
21+
22+
### Requirements
23+
24+
- 64-bit OS
25+
- At least 1 GB of RAM.
26+
- At least 2 cores
27+
- For Linux: GLIBC >= v2.17 and GLIBCXX >= 3.4.15
28+
29+
You can use whatever linux distribution floats your boat.
30+
31+
## Install
32+
33+
You can manually install by downloading from our
34+
[releases page](https://github.com/cdr/code-server/releases) but the below options are more convenient.
35+
36+
### Linux
37+
38+
```bash
39+
curl --silent https://raw.githubusercontent.com/cdr/code-server/issue-1396/install_helper.sh | bash
40+
```
41+
42+
The above script will download the latest release of code-server into
43+
`~/.local/share/code-server/<version>`. It will symlink the installed release into
44+
`~/.local/bin/code-server` so you'll need to make sure you have `~/.local/bin` in `$PATH`.
45+
46+
### Mac
47+
48+
**We are working on this in [#1542](https://github.com/cdr/code-server/issues/1542).**
49+
50+
```bash
51+
brew install code-server
52+
```
53+
54+
## Operation
55+
56+
There are several approaches to operating and exposing code-server.
57+
58+
Since you can gain access to a terminal from within code-server, never, ever
59+
expose it directly to the internet without some form of authentication and encryption.
60+
61+
By default, code-server will always enable password authentication which will
62+
require you to copy the password from the code-server output to access it. You
63+
can set a custom password with $PASSWORD.
64+
65+
With all that said, let's go through some secure setups.
66+
67+
**note**: You can list the full set of code-server options with `code-server --help`
68+
69+
### SSH
70+
71+
A very secure and convenient approach is with [sshcode](https://github.com/codercom/sshcode) ([FAQ](https://github.com/cdr/code-server/blob/setup/doc/FAQ.md#sshcode))
72+
to start code-server on any Linux machine over SSH. We highly recommend this unless you
73+
need to access code-server from a machine without ssh such as an iPad.
74+
75+
### Self Signed
76+
77+
This example shows how to run code-server with a self signed certificate.
78+
You'll get a warning when accessing but if you click through you should be good.
79+
80+
```bash
81+
./code-server --host 0.0.0.0 --cert --port 8080
82+
```
83+
84+
Now, visit `https://<your-server-ip>:8080` to access code-server.
85+
86+
**note:** Self signed certificates do not work with iPad and will cause a blank page so check out the Domain section below
87+
88+
#### mkcert
89+
90+
You can use [mkcert](https://github.com/FiloSottile/mkcert) if you want a self signed
91+
certificate automatically trusted by your operating system:
92+
93+
You'd run `mkcert` locally to generate the certificate:
94+
95+
```
96+
mkcert <server-ip>
97+
```
98+
99+
And then transfer the certificate and key file to your server and run:
100+
101+
```bash
102+
./code-server --host 0.0.0.0 --cert=<server-ip>.pem --cert-key=<server-ip>-key.pem --port 8080
103+
```
104+
105+
### Domain
106+
107+
Let's say you don't want to use a self signed certificate like in the basic example. In order to
108+
get a non self signed certificate, you'll need a domain name.
109+
110+
The easiest way is to put cloudflare in front of code-server and have it
111+
112+
1. You can put cloudflare in front of code-server and have it act as a proxy for all requests
113+
- It will fetch the TLS certificate for you so you don't have to manage anything
114+
- We highly recommend this approach as it requires very little effort on your part, just sign
115+
up for cloudflare and follow their instructions
116+
1. You can put nginx or another proxy in front and use their letsencrypt integrations
117+
1. You could generate a single one off letsencrypt
118+
119+
### Persistence?
120+
121+
So the above examples only demonstrate how to execute `code-server` from a terminal but you really
122+
want to use your operating system's init system to manage code-server. i.e systemd for Linux, launchd
123+
for macOS etc.
124+
125+
Here's an example systemd unit file:
126+
127+
```
128+
[Unit]
129+
Description=code-server
130+
After=network.target
131+
132+
[Service]
133+
ExecStart=/usr/local/bin/code-server
134+
Restart=always
135+
136+
[Install]
137+
WantedBy=multi-user.target
138+
```
139+
140+
Depends on your platform/distribution.
141+
142+
## How do I securely access web services?
143+
144+
See the [FAQ](https://github.com/cdr/code-server/blob/master/doc/FAQ.md#how-do-i-securely-access-web-services).

0 commit comments

Comments
 (0)