Skip to content

Commit ed3e9d3

Browse files
authored
Merge pull request #916 from cdr/doc-rewrite
Rewrite and update documentation
2 parents 0f1bbc3 + c94761f commit ed3e9d3

File tree

12 files changed

+716
-259
lines changed

12 files changed

+716
-259
lines changed

doc/admin/install/aws.md

Lines changed: 110 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,116 @@
1-
# Deploy on AWS
1+
# Deploy on AWS EC2
22

3-
This tutorial shows you how to deploy `code-server` on an EC2 AWS instance.
3+
This tutorial shows you how to deploy `code-server` on an AWS EC2 instance.
44

5-
If you're just starting out, we recommend [installing code-server locally](../../self-hosted/index.md). It takes only a few minutes and lets you try out all of the features.
5+
If you're just starting out, we recommend
6+
[installing code-server locally](self-hosted-docs). It takes only a few minutes
7+
and lets you try out all of the features locally.
8+
9+
If you get stuck or need help at anytime, [file an issue](create-issue),
10+
[tweet (@coderhq)](twitter-coderhq) or [email](email-coder).
11+
12+
[self-hosted-docs]: ../../self-hosted/index.md
13+
[create-issue]: https://github.com/cdr/code-server/issues/new?title=Improve+AWS+quickstart+guide
14+
[twitter-coderhq]: https://twitter.com/coderhq
15+
[email-coder]: mailto:support@coder.com?subject=AWS%20quickstart%20guide
16+
17+
---
18+
19+
### Creating an Instance using the AWS Launch Wizard
20+
21+
1. Click **Launch Instance** from your [EC2 dashboard](ec2-home).
22+
2. Select the "Ubuntu Server 18.04 LTS (HVM), SSD Volume Type" AMI..
23+
3. Select an appropriate instance size (we recommend t2.medium/large, depending
24+
on team size and number of repositories/languages enabled), then **Next:
25+
Configure Instance Details**.
26+
4. Select **Next: ...** until you get to the **Configure Security Group** page,
27+
then add a **Custom TCP Rule** rule with port range set to `8443` and source
28+
set to "Anywhere".
29+
> Rules with source of 0.0.0.0/0 allow all IP addresses to access your
30+
> instance. We recommend setting [security group rules](ec2-sg-docs) to allow
31+
> access from known IP addresses only.
32+
5. Click **Launch**.
33+
6. You will be prompted to create a keypair.
34+
> A key pair consists of a public key that AWS stores, and a private key file
35+
> that you store. For Linux AMIs, the private key file allows you to
36+
> securely SSH into your instance.
37+
7. From the dropdown choose "create a new pair", give the key pair a name.
38+
8. Click **Download Key Pair**. This is necessary before you proceed. A `.pem`
39+
file will be downloaded. make sure you store is in a safe location because it
40+
can't be retrieved once we move on.
41+
9. Finally, click **Launch Instances**.
42+
43+
[ec2-home]: https://console.aws.amazon.com/ec2/v2/home
44+
[ec2-sg-docs]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html?icmpid=docs_ec2_console
645

746
---
847

9-
## Deploy to EC2
10-
11-
### Use the AWS wizard
12-
13-
- Click **Launch Instance** from your [EC2 dashboard](https://console.aws.amazon.com/ec2/v2/home).
14-
- Select the Ubuntu Server 18.04 LTS (HVM), SSD Volume Type
15-
- Select an appropriate instance size (we recommend t2.medium/large, depending on team size and number of repositories/languages enabled), then **Next: Configure Instance Details**
16-
- Select **Next: ...** until you get to the **Configure Security Group** page, then add a **Custom TCP Rule** rule with port range set to `8443` and source set to "Anywhere"
17-
> Rules with source of 0.0.0.0/0 allow all IP addresses to access your instance. We recommend setting [security group rules](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html?icmpid=docs_ec2_console) to allow access from known IP addresses only.
18-
- Click **Launch**
19-
- You will be prompted to create a key pair
20-
> A key pair consists of a public key that AWS stores, and a private key file that you store. Together, they allow you to connect to your instance securely. For Windows AMIs, the private key file is required to obtain the password used to log into your instance. For Linux AMIs, the private key file allows you to securely SSH into your instance.
21-
- From the dropdown choose "create a new pair", give the key pair a name
22-
- Click **Download Key Pair**
23-
> This is necessary before you proceed. A `.pem` file will be downloaded. make sure you store is in a safe location because it can't be retrieved once we move on.
24-
- Finally, click **Launch Instances**
48+
### Installing code-server onto an AWS Instance
49+
50+
1. First head to your [EC2 dashboard](ec2-home) and choose **Instances** on the
51+
left sidebar.
52+
2. Select the instance you just created, and in the description tab at the
53+
bottom of the screen copy the **Public DNS (IPv4)** address using the copy to
54+
clipboard button.
55+
3. Open a terminal on your computer and use the following command to SSH into
56+
your EC2 instance. If you're using Windows, you can use [PuTTY](putty-guide)
57+
to open an SSH connection.
58+
```
59+
ssh -i "path/to/your/keypair.pem" ubuntu@(paste the public DNS here)
60+
```
61+
> For example: `ssh -i "/Users/John/Downloads/TestInstance.pem" ubuntu@ec2-3-45-678-910.compute-1.amazonaws.co`
62+
4. If you get a warning about an unknown server key fingerprint, type "yes" to
63+
approve the remote host.
64+
5. You should see a prompt for your EC2 instance like so:
65+
<img src="../../assets/aws_ubuntu.png">
66+
6. At this point it is time to download the `code-server` binary. We will, of
67+
course, want the linux version. Find the latest code-server release from the
68+
[GitHub releases](code-server-latest) page.
69+
7. Right click the Linux x64 `.tar.gz` release asset and copy the URL. In the
70+
SSH terminal, run the following command:
71+
```
72+
wget (paste the URL here)
73+
```
74+
8. Extract the downloaded file with the following command:
75+
```
76+
tar -xvzf code-server*.tar.gz
77+
```
78+
9. Navigate to extracted directory with this command:
79+
```
80+
cd code-server*/
81+
```
82+
10. Ensure the code-server binary is executable with the following command:
83+
```
84+
chmod +x code-server
85+
```
86+
11. Finally, to start code-server run this command:
87+
```
88+
./code-server
89+
```
90+
12. code-server will start up, and the password will be printed in the output.
91+
Make sure to copy the password for the next step.
92+
13. Open your browser and visit `https://$public_ip:8443/` (where `$public_ip`
93+
is your AWS instance's public IP address). You will be greeted with a page
94+
similar to the following screenshot. code-server is using a self-signed SSL
95+
certificate for easy setup. In Chrome/Chromium, click **Advanced** then
96+
click **proceed anyway**. In Firefox, click **Advanced**, then **Add
97+
Exception**, then finally **Confirm Security Exception**.
98+
<img src="../../assets/chrome_warning.png">
99+
100+
[putty-guide]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/putty.html
101+
[code-server-latest]: https://github.com/cdr/code-server/releases/latest
102+
25103
---
26-
### SSH Into EC2 Instance
27-
- First head to your [EC2 dashboard](https://console.aws.amazon.com/ec2/v2/home) and choose instances from the left panel
28-
- In the description of your EC2 instance copy the public DNS (iPv4) address using the copy to clipboard button
29-
- Open a terminal on your computer and use the following command to SSH into your EC2 instance
30-
```
31-
ssh -i "path/to/your/keypair.pem" ubuntu@(paste the public DNS here)
32-
```
33-
>example: `ssh -i "/Users/John/Downloads/TestInstance.pem" ubuntu@ec2-3-45-678-910.compute-1.amazonaws.co`
34-
- You should see a prompt for your EC2 instance like so<img src="../../assets/aws_ubuntu.png">
35-
- At this point it is time to download the `code-server` binary. We will of course want the linux version.
36-
- Find the latest Linux release from this URL:
37-
```
38-
https://github.com/cdr/code-server/releases/latest
39-
```
40-
- Replace {version} in the following command with the version found on the releases page and run it (or just copy the download URL from the releases page):
41-
```
42-
wget https://github.com/cdr/code-server/releases/download/{version}/code-server{version}-linux-x64.tar.gz
43-
```
44-
- Extract the downloaded tar.gz file with this command, for example:
45-
```
46-
tar -xvzf code-server{version}-linux-x64.tar.gz
47-
```
48-
- Navigate to extracted directory with this command:
49-
```
50-
cd code-server{version}-linux-x64
51-
```
52-
- If you run into any permission errors, make the binary executable by running:
53-
```
54-
chmod +x code-server
55-
```
56-
> To ensure the connection between you and your server is encrypted view our guide on [securing your setup](../../security/ssl.md)
57-
- Finally, run
58-
```
59-
./code-server
60-
```
61-
- Open your browser and visit `https://$public_ip:8443/` (where `$public_ip` is your AWS instance's public IP address). You will be greeted with a page similar to the following screenshot. Code-server is using a self-signed SSL certificate for easy setup. In Chrome/Chromium, click **"Advanced"** then click **"proceed anyway"**. In Firefox, click **Advanced**, then **Add Exception**, then finally **Confirm Security Exception**.<img src ="../../assets/chrome_warning.png">
62-
63-
> For instructions on how to keep the server running after you end your SSH session please checkout [how to use systemd](https://www.linode.com/docs/quick-answers/linux/start-service-at-boot/) to start linux based services if they are killed
64-
65-
---
66-
> NOTE: If you get stuck or need help, [file an issue](https://github.com/cdr/code-server/issues/new?&title=Improve+self-hosted+quickstart+guide), [tweet (@coderhq)](https://twitter.com/coderhq) or [email](mailto:support@coder.com?subject=Self-hosted%20quickstart%20guide).
104+
105+
### Post Installation Steps
106+
107+
To ensure the connection between you and your server is encrypted, view our
108+
guides on [securing your setup](security-guide).
109+
110+
For instructions on how to keep the server running after you end your SSH
111+
session please checkout [how to use systemd](systemd-guide). systemd will run
112+
code-server for you in the background as a service and restart it for you if it
113+
crashes.
114+
115+
[security-guide]: ../../security/index.md
116+
[systemd-guide]: https://www.digitalocean.com/community/tutorials/how-to-configure-a-linux-service-to-start-automatically-after-a-crash-or-reboot-part-1-practical-examples

doc/admin/install/digitalocean.md

Lines changed: 116 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -2,47 +2,124 @@
22

33
This tutorial shows you how to deploy `code-server` to a single node running on DigitalOcean.
44

5-
If you're just starting out, we recommend [installing code-server locally](../../self-hosted/index.md). It takes only a few minutes and lets you try out all of the features.
5+
If you're just starting out, we recommend
6+
[installing code-server locally](self-hosted-docs). It takes only a few minutes
7+
and lets you try out all of the features locally.
8+
9+
If you get stuck or need help at anytime, [file an issue](create-issue),
10+
[tweet (@coderhq)](twitter-coderhq) or [email](email-coder).
11+
12+
[self-hosted-docs]: ../../self-hosted/index.md
13+
[create-issue]: https://github.com/cdr/code-server/issues/new?title=Improve+DigitalOcean+quickstart+guide
14+
[twitter-coderhq]: https://twitter.com/coderhq
15+
[email-coder]: mailto:support@coder.com?subject=DigitalOcean%20quickstart%20guide
616

717
---
818

9-
## Use the "Create Droplets" wizard
10-
11-
[Open your DigitalOcean dashboard](https://cloud.digitalocean.com/droplets/new) to create a new droplet
12-
13-
- **Choose an image -** Select the **Distributions** tab and then choose Ubuntu
14-
- **Choose a size -** We recommend at least 4GB RAM and 2 CPU, more depending on team size and number of repositories/languages enabled.
15-
- Launch your instance
16-
- Open a terminal on your computer and SSH into your instance
17-
> example: ssh root@203.0.113.0
18-
- Once in the SSH session, visit code-server [releases page](https://github.com/cdr/code-server/releases/) and copy the link to the download for the latest linux release
19-
- Find the latest Linux release from this URL:
20-
```
21-
https://github.com/cdr/code-server/releases/latest
22-
```
23-
- Replace {version} in the following command with the version found on the releases page and run it (or just copy the download URL from the releases page):
24-
```
25-
wget https://github.com/cdr/code-server/releases/download/{version}/code-server{version}-linux-x64.tar.gz
26-
```
27-
- Extract the downloaded tar.gz file with this command, for example:
28-
```
29-
tar -xvzf code-server{version}-linux-x64.tar.gz
30-
```
31-
- Navigate to extracted directory with this command:
32-
```
33-
cd code-server{version}-linux-x64
34-
```
35-
- If you run into any permission errors when attempting to run the binary:
36-
```
37-
chmod +x code-server
38-
```
39-
> To ensure the connection between you and your server is encrypted view our guide on [securing your setup](../../security/ssl.md)
40-
- Finally start the code-server
41-
```
42-
./code-server
43-
```
44-
> For instructions on how to keep the server running after you end your SSH session please checkout [how to use systemd](https://www.linode.com/docs/quick-answers/linux/start-service-at-boot/) to start linux based services if they are killed
45-
- Open your browser and visit `https://$public_ip:8443/` (where `$public_ip` is your Digital Ocean instance's public IP address). You will be greeted with a page similar to the following screenshot. Code-server is using a self-signed SSL certificate for easy setup. In Chrome/Chromium, click **"Advanced"** then click **"proceed anyway"**. In Firefox, click **Advanced**, then **Add Exception**, then finally **Confirm Security Exception**.<img src ="../../assets/chrome_warning.png">
19+
### Recommended: Using the Marketplace
20+
21+
[![Create a Droplet](../../assets/do-new-droplet-btn.svg)](https://marketplace.digitalocean.com/apps/code-server?action=deploy)
22+
23+
1. On the **Create Droplets** page, choose a plan for your new code-server
24+
instance. We recommend picking an instance with at least 4 GB of RAM and 2
25+
CPU cores, or more depending on team size and number of
26+
repositories/languages enabled.
27+
2. Optionally enable backups and add block storage.
28+
3. Choose the closest available region to your physical location to reduce
29+
latency.
30+
4. Select an SSH key that you already have in your account, or click **New SSH
31+
Key** and follow the tutorial on how to make your own SSH key.
32+
5. Click **Create Droplet**, then click on the droplet to expand it.
33+
6. While you're waiting for the droplet to deploy, copy the **IPv4** address.
34+
7. Once the droplet is ready, connect using SSH with the key you specified or
35+
created earlier. You should be greeted with information on how to access your
36+
code-server instance and how to view/change the password.
37+
> You can SSH into your server using PuTTY or by running
38+
> `ssh root@(paste ipv4 address here)`.
39+
8. In the droplet's terminal, run `cat /etc/code-server/pass` to view the
40+
code-server password.
41+
9. Open your browser and visit `https://$public_ip` (where `$public_ip`
42+
is your Droplet's public IP address). You will be greeted with a page similar
43+
to the following screenshot. code-server is using a self-signed SSL
44+
certificate for easy setup. In Chrome/Chromium, click **Advanced** then
45+
click **proceed anyway**. In Firefox, click **Advanced**, then **Add
46+
Exception**, then finally **Confirm Security Exception**.
47+
<img src="../../assets/chrome_warning.png">
4648

4749
---
48-
> NOTE: If you get stuck or need help, [file an issue](https://github.com/cdr/code-server/issues/new?&title=Improve+self-hosted+quickstart+guide), [tweet (@coderhq)](https://twitter.com/coderhq) or [email](mailto:support@coder.com?subject=Self-hosted%20quickstart%20guide).
50+
51+
### Using the "Create Droplets" Wizard
52+
53+
If you used the Marketplace to set up code-server, you don't need to follow this
54+
section.
55+
56+
[Open your DigitalOcean dashboard](create-droplet) to create a new droplet.
57+
58+
1. **Choose an image:** Select the **Distributions** tab and then choose
59+
**Ubuntu 18.04.3 (LTS) x64**.
60+
2. **Choose a size:** We recommend at least 4GB RAM and 2 CPU, or more depending
61+
on team size and number of repositories/languages enabled.
62+
3. Select an SSH key that you already have in your account, or click **New SSH
63+
Key** and follow the tutorial on how to make your own SSH key.
64+
4. Click **Create Droplet**, then click on the droplet to expand it.
65+
5. While you're waiting for the droplet to deploy, copy the **IPv4** address.
66+
6. Once the droplet is ready, connect using SSH with the key you specified or
67+
created earlier. You should be greeted with information on how to access your
68+
code-server instance and how to view/change the password.
69+
> You can SSH into your server using PuTTY or by running
70+
> `ssh root@(paste ipv4 address here)`.
71+
7. If you get a warning about an unknown server key fingerprint, type "yes" to
72+
approve the remote host.
73+
8. You should see a prompt for your Droplet like so:
74+
<img src="../../assets/digitalocean_ubuntu.png">
75+
9. At this point it is time to download the `code-server` binary. We will, of
76+
course, want the linux version. Find the latest code-server release from the
77+
[GitHub releases](code-server-latest) page.
78+
10. Right click the Linux x64 `.tar.gz` release asset and copy the URL. In the
79+
SSH terminal, run the following command:
80+
```
81+
wget (paste the URL here)
82+
```
83+
11. Extract the downloaded file with the following command:
84+
```
85+
tar -xvzf code-server*.tar.gz
86+
```
87+
12. Navigate to extracted directory with this command:
88+
```
89+
cd code-server*/
90+
```
91+
13. Ensure the code-server binary is executable with the following command:
92+
```
93+
chmod +x code-server
94+
```
95+
14. Finally, to start code-server run this command:
96+
```
97+
./code-server
98+
```
99+
12. code-server will start up, and the password will be printed in the output.
100+
Make sure to copy the password for the next step.
101+
13. Open your browser and visit `https://$public_ip:8443/` (where `$public_ip`
102+
is your Droplet's public IP address). You will be greeted with a page
103+
similar to the following screenshot. code-server is using a self-signed SSL
104+
certificate for easy setup. In Chrome/Chromium, click **Advanced** then
105+
click **proceed anyway**. In Firefox, click **Advanced**, then **Add
106+
Exception**, then finally **Confirm Security Exception**.
107+
<img src="../../assets/chrome_warning.png">
108+
109+
[create-droplet]: https://cloud.digitalocean.com/droplets/new
110+
[code-server-latest]: https://github.com/cdr/code-server/releases/latest
111+
112+
---
113+
114+
### Post Installation Steps
115+
116+
To ensure the connection between you and your server is encrypted, view our
117+
guides on [securing your setup](security-guide).
118+
119+
For instructions on how to keep the server running after you end your SSH
120+
session please checkout [how to use systemd](systemd-guide). systemd will run
121+
code-server for you in the background as a service and restart it for you if it
122+
crashes. (Note: this doesn't apply for users of the Marketplace Droplet image.)
123+
124+
[security-guide]: ../../security/index.md
125+
[systemd-guide]: https://www.digitalocean.com/community/tutorials/how-to-configure-a-linux-service-to-start-automatically-after-a-crash-or-reboot-part-1-practical-examples

0 commit comments

Comments
 (0)