Merge pull request #916 from cdr/doc-rewrite

Rewrite and update documentation

doc/admin/install/aws.md

-# Deploy on AWS
+# Deploy on AWS EC2
 
-This tutorial shows you how to deploy `code-server` on an EC2 AWS instance.
+This tutorial shows you how to deploy `code-server` on an AWS EC2 instance.
 
-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.
+If you're just starting out, we recommend
+[installing code-server locally](self-hosted-docs). It takes only a few minutes
+and lets you try out all of the features locally.
+
+If you get stuck or need help at anytime, [file an issue](create-issue),
+[tweet (@coderhq)](twitter-coderhq) or [email](email-coder).
+
+[self-hosted-docs]: ../../self-hosted/index.md
+[create-issue]: https://github.com/cdr/code-server/issues/new?title=Improve+AWS+quickstart+guide
+[twitter-coderhq]: https://twitter.com/coderhq
+[email-coder]: mailto:support@coder.com?subject=AWS%20quickstart%20guide
+
+---
+
+### Creating an Instance using the AWS Launch Wizard
+
+1. Click **Launch Instance** from your [EC2 dashboard](ec2-home).
+2. Select the "Ubuntu Server 18.04 LTS (HVM), SSD Volume Type" AMI..
+3. 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**.
+4. 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".
+   > Rules with source of 0.0.0.0/0 allow all IP addresses to access your
+   > instance. We recommend setting [security group rules](ec2-sg-docs) to allow
+   > access from known IP addresses only.
+5. Click **Launch**.
+6. You will be prompted to create a keypair.
+   > A key pair consists of a public key that AWS stores, and a private key file
+   > that you store. For Linux AMIs, the private key file allows you to
+   > securely SSH into your instance.
+7. From the dropdown choose "create a new pair", give the key pair a name.
+8. Click **Download Key Pair**. 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.
+9. Finally, click **Launch Instances**.
+
+[ec2-home]: https://console.aws.amazon.com/ec2/v2/home
+[ec2-sg-docs]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html?icmpid=docs_ec2_console
 
 ---
 
-## Deploy to EC2
-
-### Use the AWS wizard
-
-- Click **Launch Instance** from your [EC2 dashboard](https://console.aws.amazon.com/ec2/v2/home).
-- Select the Ubuntu Server 18.04 LTS (HVM), SSD Volume Type
-- 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**
-- 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"
-  > 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.
-- Click **Launch**
-- You will be prompted to create a key pair
-    > 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.
-- From the dropdown choose "create a new pair", give the key pair a name
-- Click **Download Key Pair**
-  > 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.
-- Finally, click **Launch Instances**
+### Installing code-server onto an AWS Instance
+
+1. First head to your [EC2 dashboard](ec2-home) and choose **Instances** on the
+   left sidebar.
+2. Select the instance you just created, and in the description tab at the
+   bottom of the screen copy the **Public DNS (IPv4)** address using the copy to
+   clipboard button.
+3. Open a terminal on your computer and use the following command to SSH into
+   your EC2 instance. If you're using Windows, you can use [PuTTY](putty-guide)
+   to open an SSH connection.
+   ```
+   ssh -i "path/to/your/keypair.pem" ubuntu@(paste the public DNS here)
+   ```
+   > For example: `ssh -i "/Users/John/Downloads/TestInstance.pem" ubuntu@ec2-3-45-678-910.compute-1.amazonaws.co`
+4. If you get a warning about an unknown server key fingerprint, type "yes" to
+   approve the remote host.
+5. You should see a prompt for your EC2 instance like so:
+   <img src="../../assets/aws_ubuntu.png">
+6. At this point it is time to download the `code-server` binary. We will, of
+   course, want the linux version. Find the latest code-server release from the
+   [GitHub releases](code-server-latest) page.
+7. Right click the Linux x64 `.tar.gz` release asset and copy the URL. In the
+   SSH terminal, run the following command:
+   ```
+   wget (paste the URL here)
+   ```
+8. Extract the downloaded file with the following command:
+   ```
+   tar -xvzf code-server*.tar.gz
+   ```
+9. Navigate to extracted directory with this command:
+   ```
+   cd code-server*/
+   ```
+10. Ensure the code-server binary is executable with the following command:
+    ```
+    chmod +x code-server
+    ```
+11. Finally, to start code-server run this command:
+    ```
+    ./code-server
+    ```
+12. code-server will start up, and the password will be printed in the output.
+    Make sure to copy the password for the next step.
+13. 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">
+
+[putty-guide]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/putty.html
+[code-server-latest]: https://github.com/cdr/code-server/releases/latest
+
 ---
-### SSH Into EC2 Instance
-- First head to your [EC2 dashboard](https://console.aws.amazon.com/ec2/v2/home) and choose instances from the left panel
-- In the description of your EC2 instance copy the public DNS (iPv4) address using the copy to clipboard button
-- Open a terminal on your computer and use the following command to SSH into your EC2 instance
-  ```
-  ssh -i "path/to/your/keypair.pem" ubuntu@(paste the public DNS here)
-  ```
-  >example: `ssh -i "/Users/John/Downloads/TestInstance.pem" ubuntu@ec2-3-45-678-910.compute-1.amazonaws.co`
-- You should see a prompt for your EC2 instance like so<img src="../../assets/aws_ubuntu.png">
-- At this point it is time to download the `code-server` binary. We will of course want the linux version.
-- Find the latest Linux release from this URL:
-  ```
-  https://github.com/cdr/code-server/releases/latest
-  ```
-- 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):
-  ```
-  wget https://github.com/cdr/code-server/releases/download/{version}/code-server{version}-linux-x64.tar.gz
-  ```
-- Extract the downloaded tar.gz file with this command, for example:
-  ```
-  tar -xvzf code-server{version}-linux-x64.tar.gz
-  ```
-- Navigate to extracted directory with this command:
-  ```
-  cd code-server{version}-linux-x64
-  ```
-- If you run into any permission errors, make the binary executable by running:
-  ```
-  chmod +x code-server
-  ```
-  > To ensure the connection between you and your server is encrypted view our guide on [securing your setup](../../security/ssl.md)
-- Finally, run
-  ```
-  ./code-server
-  ```
-- 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">
-
-  > 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
-
-  ---
-> 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).
+
+### Post Installation Steps
+
+To ensure the connection between you and your server is encrypted, view our
+guides on [securing your setup](security-guide).
+
+For instructions on how to keep the server running after you end your SSH
+session please checkout [how to use systemd](systemd-guide). systemd will run
+code-server for you in the background as a service and restart it for you if it
+crashes.
+
+[security-guide]: ../../security/index.md
+[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

@@ -2,47 +2,124 @@
 
 This tutorial shows you how to deploy `code-server` to a single node running on DigitalOcean.
 
-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.
+If you're just starting out, we recommend
+[installing code-server locally](self-hosted-docs). It takes only a few minutes
+and lets you try out all of the features locally.
+
+If you get stuck or need help at anytime, [file an issue](create-issue),
+[tweet (@coderhq)](twitter-coderhq) or [email](email-coder).
+
+[self-hosted-docs]: ../../self-hosted/index.md
+[create-issue]: https://github.com/cdr/code-server/issues/new?title=Improve+DigitalOcean+quickstart+guide
+[twitter-coderhq]: https://twitter.com/coderhq
+[email-coder]: mailto:support@coder.com?subject=DigitalOcean%20quickstart%20guide
 
 ---
 
-## Use the "Create Droplets" wizard
-
-[Open your DigitalOcean dashboard](https://cloud.digitalocean.com/droplets/new) to create a new droplet
-
-- **Choose an image -** Select the **Distributions** tab and then choose Ubuntu
-- **Choose a size -** We recommend at least 4GB RAM and 2 CPU, more depending on team size and number of repositories/languages enabled.
-- Launch your instance
-- Open a terminal on your computer and SSH into your instance
-  > example: ssh root@203.0.113.0
-- 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
-- Find the latest Linux release from this URL:
-  ```
-  https://github.com/cdr/code-server/releases/latest
-  ```
-- 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):
-  ```
-  wget https://github.com/cdr/code-server/releases/download/{version}/code-server{version}-linux-x64.tar.gz
-  ```
-- Extract the downloaded tar.gz file with this command, for example:
-  ```
-  tar -xvzf code-server{version}-linux-x64.tar.gz
-  ```
-- Navigate to extracted directory with this command:
-  ```
-  cd code-server{version}-linux-x64
-  ```
-- If you run into any permission errors when attempting to run the binary:
-  ```
-  chmod +x code-server
-  ```
-  > To ensure the connection between you and your server is encrypted view our guide on [securing your setup](../../security/ssl.md)
-- Finally start the code-server
-  ```
-  ./code-server
-  ```
-    > 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
-- 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">
+### Recommended: Using the Marketplace
+
+[![Create a Droplet](../../assets/do-new-droplet-btn.svg)](https://marketplace.digitalocean.com/apps/code-server?action=deploy)
+
+1. On the **Create Droplets** page, choose a plan for your new code-server
+   instance. We recommend picking an instance with at least 4 GB of RAM and 2
+   CPU cores, or more depending on team size and number of
+   repositories/languages enabled.
+2. Optionally enable backups and add block storage.
+3. Choose the closest available region to your physical location to reduce
+   latency.
+4. Select an SSH key that you already have in your account, or click **New SSH
+   Key** and follow the tutorial on how to make your own SSH key.
+5. Click **Create Droplet**, then click on the droplet to expand it.
+6. While you're waiting for the droplet to deploy, copy the **IPv4** address.
+7. Once the droplet is ready, connect using SSH with the key you specified or
+   created earlier. You should be greeted with information on how to access your
+   code-server instance and how to view/change the password.
+   > You can SSH into your server using PuTTY or by running
+   > `ssh root@(paste ipv4 address here)`.
+8. In the droplet's terminal, run `cat /etc/code-server/pass` to view the
+   code-server password.
+9. Open your browser and visit `https://$public_ip` (where `$public_ip`
+   is your Droplet'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">
 
 ---
-> 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).
+
+### Using the "Create Droplets" Wizard
+
+If you used the Marketplace to set up code-server, you don't need to follow this
+section.
+
+[Open your DigitalOcean dashboard](create-droplet) to create a new droplet.
+
+1. **Choose an image:** Select the **Distributions** tab and then choose
+   **Ubuntu 18.04.3 (LTS) x64**.
+2. **Choose a size:** We recommend at least 4GB RAM and 2 CPU, or more depending
+   on team size and number of repositories/languages enabled.
+3. Select an SSH key that you already have in your account, or click **New SSH
+   Key** and follow the tutorial on how to make your own SSH key.
+4. Click **Create Droplet**, then click on the droplet to expand it.
+5. While you're waiting for the droplet to deploy, copy the **IPv4** address.
+6. Once the droplet is ready, connect using SSH with the key you specified or
+   created earlier. You should be greeted with information on how to access your
+   code-server instance and how to view/change the password.
+   > You can SSH into your server using PuTTY or by running
+   > `ssh root@(paste ipv4 address here)`.
+7. If you get a warning about an unknown server key fingerprint, type "yes" to
+   approve the remote host.
+8. You should see a prompt for your Droplet like so:
+   <img src="../../assets/digitalocean_ubuntu.png">
+9. At this point it is time to download the `code-server` binary. We will, of
+   course, want the linux version. Find the latest code-server release from the
+   [GitHub releases](code-server-latest) page.
+10. Right click the Linux x64 `.tar.gz` release asset and copy the URL. In the
+    SSH terminal, run the following command:
+    ```
+    wget (paste the URL here)
+    ```
+11. Extract the downloaded file with the following command:
+    ```
+    tar -xvzf code-server*.tar.gz
+    ```
+12. Navigate to extracted directory with this command:
+    ```
+    cd code-server*/
+    ```
+13. Ensure the code-server binary is executable with the following command:
+    ```
+    chmod +x code-server
+    ```
+14. Finally, to start code-server run this command:
+    ```
+    ./code-server
+    ```
+12. code-server will start up, and the password will be printed in the output.
+    Make sure to copy the password for the next step.
+13. Open your browser and visit `https://$public_ip:8443/` (where `$public_ip`
+    is your Droplet'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">
+
+[create-droplet]: https://cloud.digitalocean.com/droplets/new
+[code-server-latest]: https://github.com/cdr/code-server/releases/latest
+
+---
+
+### Post Installation Steps
+
+To ensure the connection between you and your server is encrypted, view our
+guides on [securing your setup](security-guide).
+
+For instructions on how to keep the server running after you end your SSH
+session please checkout [how to use systemd](systemd-guide). systemd will run
+code-server for you in the background as a service and restart it for you if it
+crashes. (Note: this doesn't apply for users of the Marketplace Droplet image.)
+
+[security-guide]: ../../security/index.md
+[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/google_cloud.md

-# Deploy on Google Cloud
+# Deploy on Google Cloud Platform
 
-This tutorial shows you how to deploy `code-server` to a single node running on Google Cloud.
+This tutorial shows you how to deploy `code-server` to a single node running on
+Google Cloud Platform.
 
-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.
+If you're just starting out, we recommend
+[installing code-server locally](self-hosted-docs). It takes only a few minutes
+and lets you try out all of the features locally.
 
----
-
-## Deploy to Google Cloud VM
-> Pre-requisite: Please [set up Google Cloud SDK](https://cloud.google.com/sdk/docs/) on your local machine
+If you get stuck or need help at anytime, [file an issue](create-issue),
+[tweet (@coderhq)](twitter-coderhq) or [email](email-coder).
 
-- [Open your Google Cloud console](https://console.cloud.google.com/compute/instances) to create a new VM instance and click **Create Instance**
-- Choose an appropriate machine type (we recommend 2 vCPU and 7.5 GB RAM, more depending on team size and number of repositories/languages enabled)
-- Choose Ubuntu 16.04 LTS as your boot disk
-- Expand the "Management, security, disks, networking, sole tenancy" section, go to the "Networking" tab, then under network tags add "code-server"
-- Create your VM, and **take note** of its public IP address.
-- Visit "VPC network" in the console and go to "Firewall rules". Create a new firewall rule called "http-8443". Under "Target tags" add "code-server", and under "Protocols and ports" tick "Specified protocols and ports" and "tcp". Beside "tcp", add "8443", then create the rule.
-- Copy the link to download the latest Linux binary from our [releases page](https://github.com/cdr/code-server/releases)
+[self-hosted-docs]: ../../self-hosted/index.md
+[create-issue]: https://github.com/cdr/code-server/issues/new?title=Improve+Google+Cloud+quickstart+guide
+[twitter-coderhq]: https://twitter.com/coderhq
+[email-coder]: mailto:support@coder.com?subject=Google%20Cloud%20quickstart%20guide
 
 ---
 
-## Final Steps
+## Deploy to Google Cloud VM
 
-- SSH into your Google Cloud VM
-```
-gcloud compute ssh --zone [region] [instance name]
-```
+[Open your Google Cloud console](create-instance) to create a new VM instance.
 
-- Find the latest Linux release from this URL:
-```
-https://github.com/cdr/code-server/releases/latest
-```
+1. Click **Create Instance**.
+2. Choose an appropriate machine type (we recommend 2 vCPU and 7.5 GB RAM, or
+   more depending on team size and number of repositories/languages enabled).
+3. Choose **Ubuntu 16.04 LTS** as your boot disk.
+4. Expand the **Management, security, disks, networking, sole tenancy** section,
+   go to the **Networking** tab, then under network tags add `code-server`.
+5. Create your VM, and **take note** of its public IP address.
+6. Visit **VPC networks** in the console and go to **Firewall rules**. Create a
+   new firewall rule called `http-8443`. Under **Target tags**, add
+   `code-server`, and under **Protocols and ports** tick **Specified protocols and
+   ports** and **tcp**. Beside **tcp**, add `8443`, then create the rule.
 
-- 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):
-```
-wget https://github.com/cdr/code-server/releases/download/{version}/code-server{version}-linux-x64.tar.gz
-```
+[create-instance]: https://console.cloud.google.com/compute/instances
 
-- Extract the downloaded tar.gz file with this command, for example:
-```
-tar -xvzf code-server{version}-linux-x64.tar.gz
-```
+---
 
-- Navigate to extracted directory with this command:
-```
-cd code-server{version}-linux-x64
-```
+## Final Steps
 
-- Make the binary executable if you run into any errors regarding permission:
-```
-chmod +x code-server
-```
+Please [set up Google Cloud SDK](gcloud-sdk) on your local machine, or access
+your instance terminal using another method.
+
+<!-- TODO: add a screenshot of the initial terminal like other guides -->
+
+1. SSH into your Google Cloud VM:
+   ```
+   gcloud compute ssh --zone [region] [instance name]
+   ```
+2. At this point it is time to download the `code-server` binary. We will, of
+   course, want the linux version. Find the latest code-server release from the
+   [GitHub releases](code-server-latest) page.
+3. Right click the Linux x64 `.tar.gz` release asset and copy the URL. In the
+   SSH terminal, run the following command:
+   ```
+   wget (paste the URL here)
+   ```
+4. Extract the downloaded file with the following command:
+   ```
+   tar -xvzf code-server*.tar.gz
+   ```
+5. Navigate to extracted directory with this command:
+   ```
+   cd code-server*/
+   ```
+6. Ensure the code-server binary is executable with the following command:
+   ```
+   chmod +x code-server
+   ```
+7. Finally, to start code-server run this command:
+   ```
+   ./code-server
+   ```
+8. code-server will start up, and the password will be printed in the output.
+   Make sure to copy the password for the next step.
+9. Open your browser and visit `https://$public_ip:8443/` (where `$public_ip`
+   is your 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">
+
+[gcloud-sdk]: https://cloud.google.com/sdk/docs/
+[code-server-latest]: https://github.com/cdr/code-server/releases/latest
 
-> To ensure the connection between you and your server is encrypted view our guide on [securing your setup](../../security/ssl.md)
+---
 
-- Start the code-server
-  ```
-  ./code-server
-  ```
-- Open your browser and visit `https://$public_ip:8443/` (where `$public_ip` is your Compute Engine 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">
+### Post Installation Steps
 
-> 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
+To ensure the connection between you and your server is encrypted, view our
+guides on [securing your setup](security-guide).
 
----
+For instructions on how to keep the server running after you end your SSH
+session please checkout [how to use systemd](systemd-guide). systemd will run
+code-server for you in the background as a service and restart it for you if it
+crashes.
 
-> 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).
+[security-guide]: ../../security/index.md
+[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/security/code-server.fail2ban.conf

 # Fail2Ban filter for code-server
-#
-#
 
 [Definition]
 
-
 failregex = ^INFO\s+Failed login attempt\s+{\"password\":\"(\\.|[^"])*\",\"remote_address\":\"<HOST>\"
 
 ignoreregex =
@@ -12,4 +9,3 @@ ignoreregex =
 datepattern = "timestamp":{EPOCH}}$
 
 # Author: Dean Sheather
-

doc/security/fail2ban.md

-# Protecting code-server from bruteforce attempts
+# Protecting code-server from Bruteforce Attempts
+
+<!-- TODO: remove this notice -->
+### **NOTE: FAILED LOGIN ATTEMPT LOGGING IS NOT IN THE CURRENT VERSION AND WILL BE RELEASED IN V2.**
 
 code-server outputs all failed login attempts, along with the IP address,
 provided password, user agent and timestamp by default. When using a reverse
@@ -39,4 +42,3 @@ authentication attempts for many applications through regex filters. A working
 filter for code-server can be found in `./code-server.fail2ban.conf`. Once this
 is installed and configured correctly, repeated failed login attempts should
 automatically be banned from connecting to your server.
-

doc/security/index.md

+# Security Guides
+
+We recommend users running code-server setup SSL and fail2ban on their
+instances for improved security and resilience to attacks.
+
+* [Self-signed SSL guide](./ssl.md)
+* [Let's Encrypt SSL guide](./ssl-certbot.md)
+* [Fail2Ban setup guide](./fail2ban.md)

doc/security/ssl-certbot.md

+# Generate a Certificate Using Let's Encrypt 🔒
+
+To get around the certificate warnings in Chrome, you might want to install a
+certificate from a trusted Certificate Authority (CA). Luckily, there are CAs
+like [Let's Encrypt](lets-encrypt) which provide certificates for free.
+
+[lets-encrypt]: https://letsencrypt.org/
+
+---
+
+### Using Certbot
+
+[Certbot](certbot) is the program we'll be using to issue certificates from
+Let's Encrypt.
+
+> Pre-requisites: You will need a domain name or subdomain pointed to the IP
+> address of your server.
+
+1. Install Certbot by heading to the [instructions page](certbot-instructions).
+   Select **None of the above** for the software and the right operating system
+   for your setup.
+2. Follow the installation instructions, and stop once you get up to the part
+   where you run the `certbot certonly` command.
+3. Ensure your code-server instance isn't running, and any other webservers that
+   could interfere are also stopped.
+4. Run the following command, replacing `code.example.com` with the
+   hostname/domain you want to run your server on, to issue a certificate:
+   ```
+   sudo certbot certonly --standalone -d code.example.com
+   ```
+5. Follow the prompts, providing your email address and accepting the terms
+   where required.
+6. Once the process is complete, it should print the paths to the certificates
+   and keys that were generated. You can now restart any webservers you stopped
+   in step 2.
+
+[certbot]: https://certbot.eff.org/
+[certbot-instructions]: https://certbot.eff.org/instructions
+
+---
+
+### Starting code-server with a Certificate and Key
+
+Just add the `--cert` and `--cert-key` flags when you run code-server:
+
+```shell
+./code-server --cert=/etc/letsencrypt/live/code.example.com/fullchain.pem --cert-key=/etc/letsencrypt/live/code.example.com/privkey.pem
+```
+
+You can now verify that your SSL installation is working properly by checking
+your site with [SSL Labs' SSL Test](ssl-labs-test).
+
+[ssl-labs-test]: https://www.ssllabs.com/ssltest/
+
+---
+
+### Next Steps
+
+You probably want to setup automatic renewal of your certificates, as they
+expire every 3 months. You can find instructions on how to do this in
+[Certbot's documentation](certbot-renew-docs).
+
+[certbot-renew-docs]: https://certbot.eff.org/docs/using.html?highlight=hooks#renewing-certificates

doc/security/ssl.md

-# Generate a self-signed certificate 🔒
+# Generate a Self-signed Certificate 🔒
 
-code-server has the ability to secure your connection between client and server using SSL/TSL certificates. By default, the server will start with an unencrypted connection. We recommend Self-signed TLS/SSL certificates for personal use of code-server or within an organization.
+code-server has the ability to secure your connection between client and server
+using SSL/TSL certificates. By default, the server will start with an
+unencrypted connection. We recommend Self-signed TLS/SSL certificates for
+personal use of code-server or within an organization.
 
-This guide will show you how to create a self-signed certificate and start code-server using your certificate/key.
+This guide will show you how to create a self-signed certificate and start
+code-server using your certificate/key.
 
 ## TLS / HTTPS
 
-You can specify any location that you want to save the certificate and key. In this example, we will navigate to the root directory, create a folder called `certs` and cd into it.
+You can specify any location that you want to save the certificate and key. In
+this example, we will navigate to the root directory, create a folder called
+`certs` and cd into it.
 
 ```shell
 mkdir ~/certs && cd ~/certs
 ```
 
-If you don't already have a TLS certificate and key, you can generate them with the command below. They will be placed in `~/certs`
+If you don't already have a TLS certificate and key, you can generate them with
+the command below. They will be placed in `~/certs`.
 
 ```shell
 openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ~/certs/MyKey.key -out ~/certs/MyCertificate.crt
 ```
 
-You will be prompted to add some identifying information about your organization
+You will be prompted to add some identifying information about your
+organization:
+
 ```shell
 You are about to be asked to enter information that will be incorporated
 into your certificate request.
@@ -35,19 +44,27 @@ Organizational Unit Name (eg, section) []:Docs
 Common Name (e.g. server FQDN or YOUR name) []:hostname.example.com
 Email Address []:admin@example.com
 ```
->If you already have a TLS certificate and key, you can simply reference them in the `--cert` and `--cert-key` flags when launching code-server
 
+> If you already have a TLS certificate and key, you can simply reference them
+> in the `--cert` and `--cert-key` flags when launching code-server.
+
+
+## Starting code-server with a Certificate and Key
 
-## Starting code-server with certificate and key
+Just add the `--cert` and `--cert-key` flags when you run code-server:
 
-1. At the end of the path to your binary, add the following flags followed by the path to your certificate and key like so. Then press enter to run code-server.
-   ```shell
-    ./code-server --cert=~/certs/MyCertificate.crt --cert-key=~/certs/MyKey.key
-   ```
-2. After that you will be running a secure code-server.
+```shell
+./code-server --cert=~/certs/MyCertificate.crt --cert-key=~/certs/MyKey.key
+```
 
-> You will know your connection is secure if the lines `WARN  No certificate specified. This could be insecure. WARN  Documentation on securing your setup: https://coder.com/docs` no longer appear.
+> You should check that the
+> `WARN  No certificate specified. This could be insecure` are no longer visible
+> in the output.
 
-## Other options
+## Other Options
 
-For larger organizations you may wish to rely on a Certificate Authority as opposed to a self-signed certificate. For more information on generating free and open certificates for your site, please check out EFF's [certbot](https://certbot.eff.org/). Certbot is a cli to generate certificates using [LetsEncrypt](https://letsencrypt.org/).
+For larger organizations you may wish to rely on a trusted Certificate Authority
+as opposed to a self-signed certificate. For more information on generating free
+and open certificates for your site, please check out EFF's
+[certbot](https://certbot.eff.org/). Certbot is a cli to generate certificates
+using [LetsEncrypt](https://letsencrypt.org/).

doc/self-hosted/cros-install.md

-# Installng code-server in your ChromiumOS/ChromeOS/CloudReady machine
+# Installng code-server on a ChromeOS/CloudReady machine
 
-This guide will show you how to install code-server into your CrOS machine.
+This guide will show you how to install code-server on your CrOS machine.
 
 ## Using Crostini
 
-One of the easier ways to run code-server is via [Crostini](https://www.aboutchromebooks.com/tag/project-crostini/), the Linux apps support feature in CrOS. Make sure you have enough RAM, HDD space and your CPU has VT-x/ AMD-V support. If your chromebook has this, then you are qualified to use Crostini.
+One of the easier ways to run code-server is via [Crostini](crostini), the Linux
+apps support feature in CrOS. Make sure you have enough RAM, HDD space and your
+CPU has VT-x/AMD-V support. If your Chromebook has this, then you are qualified
+to use Crostini.
 
-If you are running R69, you might want to enable this on [Chrome Flags](chrome://flags/#enable-experimental-crostini-ui). If you run R72, however, this is already enabled for you.
+If you are running R69, you might want to enable this on
+[Chrome Flags](r69-flag). If you run R72, however, this is already enabled for
+you.
 
-After checking your prerequisites, follow the steps in [the self-host install guide](index.md) on installing code-server. Once done, make sure code-server works by running it. After running it, simply go to `penguin.linux.test:8443` to access code-server. Now you should be greeted with this screen. If you did, congratulations, you have installed code-server in your Chromebook!
+After checking your prerequisites, follow the steps in [the self-host install
+guide](self-hosted-guide) on installing code-server. Once done, make sure
+code-server works by running it, then simply go to `penguin.linux.test:8443` to
+access code-server. You should be greeted with the following screen. If it
+works, congratulations, you have installed code-server in your Chromebook!
 
 ![code-server on Chromebook](../assets/cros.png)
 
-Alternatively, if you ran code-server in another container and you need the IP for that specific container, simply go to Termina's shell via `crosh` and type `vsh termina`.
+Alternatively, if you ran code-server in another container and you need the IP
+for that specific container, simply go to Termina's shell via `crosh` and type
+`vsh termina`.
 
-```bash
+```
 Loading extra module: /usr/share/crosh/dev.d/50-crosh.sh
 Welcome to crosh, the Chrome OS developer shell.
 
@@ -28,26 +39,43 @@ Load it by using the Ctrl+Shift+P keyboard shortcut.
 crosh> vsh termina
 (termina) chronos@localhost ~ $
 ```
-While in termina, run `lxc list`. It should output the list of running containers.
 
-```bash
+While in termina, run `lxc list`. It should output the list of running
+containers.
+
+```
 (termina) chronos@localhost ~ $ lxc list
 +---------+---------+-----------------------+------+------------+-----------+
 |  NAME   |  STATE  |         IPV4          | IPV6 |    TYPE    | SNAPSHOTS |
 +---------+---------+-----------------------+------+------------+-----------+
 | penguin | RUNNING | 100.115.92.199 (eth0) |      | PERSISTENT | 0         |
 +---------+---------+-----------------------+------+------------+-----------+
-(termina) chronos@localhost ~ $ 
+(termina) chronos@localhost ~ $
 ```
 
-For this example, we show the default `penguin` container, which is exposed on `eth0` at 100.115.92.199. Simply enter the IP of the container where the code-server runs to Chrome.
+For this example, we show the default `penguin` container, which is exposed on
+`eth0` at 100.115.92.199. Simply enter the IP of the container where code-server
+is running into Chrome to access code-server.
+
+[crostini]: https://www.aboutchromebooks.com/tag/project-crostini/
+[r69-flag]: chrome://flags/#enable-experimental-crostini-ui
+[self-hosted-guide]: ./index.md
 
 ## Using Crouton
 
-[Crouton](https://github.com/dnschneid/crouton) is one of the old ways to get a running full Linux via `chroot` on a Chromebook. To use crouton, enable developer mode and go to `crosh`. This time, run `shell`, which should drop you to `bash`.
+[Crouton](crouton) is one of the old ways to get a running full Linux via
+`chroot` on a Chromebook. To use crouton, enable developer mode and go to
+`crosh`. This time, run `shell`, which should drop you to `bash`.
+
+Make sure you downloaded `crouton`, if so, go ahead and run it under
+`~/Downloads`. After installing your chroot container via crouton, go ahead and
+enter `enter-chroot` to enter your container.
 
-Make sure you downloaded `crouton`, if so, go ahead and run it under `~/Downloads`. After installing your chroot container via crouton, go ahead and enter `enter-chroot` to enter your container.
+Follow the instructions set in [the self-host install guide](self-hosted-guide)
+to install code-server. After that is done, run `code-server` and verify it
+works by going to `localhost:8443`.
 
-Follow the instructions set in [the self-host install guide](index.md) to install code-server. After that is done, run `code-server` and verify it works by going to `localhost:8443`.
+> At this point in writing, `localhost` seems to work in this method. However,
+> it might not apply to newer Chromebooks.
 
-> At this point in writing, `localhost` seems to work in this method. However, the author is not sure if it applies still to newer Chromebooks.
+[crouton]: https://github.com/dnschneid/crouton

doc/self-hosted/index.md

 # Getting Started
 
-[code-server](https://coder.com) is used by developers at Azure, Google, Reddit, and more to give them access to VS Code in the browser.
+This document pertains to Coder-specific implementation of VS Code: code-server.
+For documentation on how to use VS Code itself, please refer to the official
+[VS Code documentation](vscode-documentation).
+
+If you get stuck or need help at anytime, [file an issue](create-issue),
+[tweet (@coderhq)](twitter-coderhq) or [email](email-coder).
+
+[vscode-documentation]: https://code.visualstudio.com/docs
+[create-issue]: https://github.com/cdr/code-server/issues/new?title=Improve+self-hosted+quickstart+guide
+[twitter-coderhq]: https://twitter.com/coderhq
+[email-coder]: mailto:support@coder.com?subject=Self-hosted%20quickstart%20guide
+
 
 ## Quickstart Guide
 
-> 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).
+It takes just a few minutes to get your own self-hosted server running. If
+you've got a machine running macOS or Linux, you're ready to start the
+binary which listens on port `8443` by default.
+
+<!-- DO NOT CHANGE THIS TO A CODEBLOCK. We want line breaks for readability, but
+     backslashes to escape them do not work cross-platform. This uses line
+     breaks that are rendered but not copy-pasted to the clipboard.  -->
 
-This document pertains to Coder specific implementations of VS Code. For documentation on how to use VS Code itself, please refer to the official [documentation for VS Code](https://code.visualstudio.com/docs)
+1. Visit the [releases](code-server-releases) page and download the latest
+   release for your operating system.
+2. Extract the archive and double click the executable to run in the current
+   directory.
+3. Copy the password that appears in the output.
+   <img src="../assets/cli.png">
+4. In your browser navigate to https://localhost:8443. You will be greeted with
+   an SSL warning as code-server uses a self-signed certificate (more on that
+   below). Skip the warning.
+5. Login using the password from earlier.
 
-It takes just a few minutes to get your own self-hosted server running. If you've got a machine running macOS, Windows, or Linux, you're ready to start the binary which listens on port `8443` by default.
+Be careful about who you share your password with, as it will grant them full
+access to your server.
 
-<!--
-  DO NOT CHANGE THIS TO A CODEBLOCK.
-  We want line breaks for readability, but backslashes to escape them do not work cross-platform.
-  This uses line breaks that are rendered but not copy-pasted to the clipboard.
--->
+[code-server-releases]: https://github.com/cdr/code-server/releases
 
 
-1. Visit [the releases](https://github.com/cdr/code-server/releases) page and download the latest cli for your operating system
-2. Double click the executable to run in the current directory
-3. Copy the password that appears in the cli<img src="../assets/cli.png">
-4. In your browser navigate to `localhost:8443`
-5. Paste the password from the cli into the login window<img src="../assets/server-password-modal.png">
-> NOTE: Be careful with your password as sharing it will grant those users access to your server's file system
+### Security Warnings
 
-### Things To Know
-- When you visit the IP for your code-server instance, 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">
+When you visit your code-server instance, you will be greeted with a warning
+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">
 
-## Usage
-<pre class="pre-wrap"><code>code-server<span class="virtual-br"></span> --help</code></pre>
 
-code-server can be ran with a number of arguments to customize your working directory, host, port, and SSL certificate.
+## code-server Usage
+
+You can bring up code-server usage by using `code-server --help`. Arguments let
+you customize your working directory, host, port, SSL certificates, and more.
+
+Flags can be supplied to code-server like `--flag-name value` or
+`--flag-name=value`. To supply values with whitespace, use double quotes.
 
 ```
+$ code-server --help
 Usage: code-server [options]
 
 Run VS Code on a remote server.
@@ -44,7 +71,7 @@ Options:
   -e, --extensions-dir <dir>            Override the main default path for user extensions.
   --extra-extensions-dir [dir]          Path to an extra user extension directory (repeatable). (default: [])
   --extra-builtin-extensions-dir [dir]  Path to an extra built-in extension directory (repeatable). (default: [])
-  -d, --user-data-dir <dir>             Specifies the directory that user data is kept in, useful when running as root.
+  -d --user-data-dir <dir>              Specifies the directory that user data is kept in, useful when running as root.
   -h, --host <value>                    Customize the hostname. (default: "0.0.0.0")
   -o, --open                            Open in the browser on startup.
   -p, --port <number>                   Port to bind on. (default: 8443)
@@ -52,74 +79,228 @@ Options:
   -H, --allow-http                      Allow http connections.
   --disable-telemetry                   Disables ALL telemetry.
   --socket <value>                      Listen on a UNIX socket. Host and port will be ignored when set.
-  --trust-proxy                         Trust the X-Forwarded-For header, useful when using a reverse proxy.
   --install-extension <value>           Install an extension by its ID.
   -h, --help                            output usage information
 ```
 
-  ### Data Directory
-  Use `code-server -d (path/to/directory)` or `code-server --user-data-dir=(path/to/directory)`, excluding the parentheses to specify the root folder that VS Code will start in.
-
-  ### Host
-  By default, code-server will use `0.0.0.0` as its address. This can be changed by using `code-server -h` or `code-server --host=` followed by the address you want to use.
-  > Example: `code-server -h 127.0.0.1`
-
-  ### Open
-  You can have the server automatically open the VS Code in your browser on startup by using the `code-server -o` or `code-server --open` flags
-
-  ### Port
-  By default, code-server will use `8443` as its port. This can be changed by using `code-server -p` or `code-server --port=` followed by the port you want to use.
-  > Example: `code-server -p 9000`
-
-  ### Telemetry
-  Disable all telemetry with `code-server --disable-telemetry`.
-
-  ### Cert and Cert Key
-  To encrypt the traffic between the browser and server use `code-server --cert=` followed by the path to your `.cer` file. Additionally, you can use certificate keys with `code-server --cert-key` followed by the path to your `.key` file.
-> Example (certificate and key): `code-server --cert /etc/letsencrypt/live/example.com/fullchain.cer --cert-key /etc/letsencrypt/live/example.com/fullchain.key`
-> Example (if you are using Letsencrypt or similar): `code-server --cert /etc/letsencrypt/live/example.com/fullchain.pem --cert-key /etc/letsencrypt/live/example.com/privkey.key`
-
-> To ensure the connection between you and your server is encrypted view our guide on [securing your setup](../security/ssl.md)
-
-  ### Nginx Reverse Proxy
-  Below is a virtual host example that works with code-server. Please also pass `--allow-http` and `--trust-proxy` to code-server to allow the proxy to connect. You can also use Let's Encrypt to get a SSL certificates for free.
-  ```
-  server {
-    listen 80;
-    listen [::]:80;
-    server_name code.example.com code.example.org;
-    location / {
-       proxy_pass http://localhost:8443/;
-       proxy_set_header Upgrade $http_upgrade;
-       proxy_set_header Connection upgrade;
-       proxy_set_header Accept-Encoding gzip;
-    }
+By default, code-server listens on `0.0.0.0:8443`. If you'd like to customize
+this, use the `--host` and `--port` flags:
+`code-server --host 127.0.0.1 --port 1234`.
+
+You can instruct code-server to automatically open itself in your default
+browser by using the `-o` or `--open` flag.
+
+Use `code-server -d path/to/directory` to specify where code-server stores it's
+configuration data. You can specify where extensions are installed using the
+`-e`, `--extra-extensions-dir` and `--extra-builtin-extensions-dir` flags.
+
+
+### SSL Certificates
+
+To change the certificate code-server uses for HTTPS connections, specify a
+certificate with `--cert` and a private key with `--cert-key`.
+
+If you're using Let's Encrypt, you should be using the `fullchain.pem` file as
+the certificate and `privkey.pem` as the private key.
+
+```
+code-server \
+        --cert /etc/letsencrypt/live/example.com/fullchain.pem \
+	--cert-key /etc/letsencrypt/live/example.com/privkey.pem
+```
+
+For more information on security and SSL configuration, please visit the
+[security documentation](../security).
+
+
+#### Telemetry
+
+Telemetry can be disabled by using the `--disable-telemetry` flag or by setting
+the `DISABLE_TELEMETRY` environment variable to `true`. If telemetry is enabled,
+code-server will send the following data along with VS Code's telemetry data:
+
+- Unique machine ID
+- CPU core count and model
+- Memory information
+- Shell information (which shell you use)
+- OS release and architecture
+
+
+### Nginx Reverse Proxy
+
+The following site configuration file works with code-server. When starting
+code-server, be sure to provide the `--allow-http` and `--trust-proxy` flags so
+Nginx can connect to code-server properly.
+
+Some of these directives require a version of Nginx greater than or equal to
+`1.13.0`, which might not be available in your distro's repositories. Check out
+[Nginx's documentation](nginx-install) for more information on how to install
+the latest version of Nginx from the official repository.
+
+```
+# HTTP configuration
+server {
+  listen 80;
+  listen [::]:80;
+  server_name code.example.com code.example.org;
+
+  # If you're using CloudFlare, uncomment the following line.
+  # real_ip_header CF-Connecting-IP;
+
+  # Other security options.
+  add_header X-Frame-Options DENY;
+  add_header X-Content-Type-Options nosniff;
+  add_header X-XSS-Protection "1; mode=block";
+
+  location / {
+    proxy_pass http://localhost:8443/;
+    proxy_set_header Accept-Encoding gzip;
+    proxy_set_header Connection upgrade;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
   }
-  ```
+}
+
+# HTTPS configuration. Scores an A on SSL Labs' SSL Server Test.
+server {
+  listen 443 ssl http2;
+  listen [::]:443 ssl http2;
+  server_name code.example.com code.example.org;
+
+  # If you're using CloudFlare, uncomment the following line.
+  # real_ip_header CF-Connecting-IP;
 
-  ### Apache Reverse Proxy
-  Example of a HTTPS virtualhost configuration for Apache as a reverse proxy. Please also pass `--allow-http` and `--trust-proxy` to code-server to allow the proxy to connect. You can also use Let's Encrypt to get a SSL certificates for free.
-  ```
-  <VirtualHost *:80>
+  # SSL certificate and key.
+  ssl_certificate /path/to/cert.pem;
+  ssl_certificate_key /path/to/cert-key.pem;
+
+  # Strong TLS configuration. Originally taken from https://cipherli.st/.
+  ssl_protocols TLSv1.2 TLSv1.3;
+  ssl_prefer_server_ciphers on;
+  # ssl_dhparam /etc/nginx/dhparam.pem; # openssl dhparam -out /etc/nginx/dhparam.pem 4096
+  ssl_ciphers EECDH+AESGCM:EDH+AESGCM;
+  ssl_ecdh_curve secp384r1;
+  ssl_session_timeout 10m;
+  ssl_session_cache shared:SSL:10m;
+  ssl_session_tickets off;
+  ssl_stapling on;
+  ssl_stapling_verify on;
+  resolver 8.8.8.8 8.8.4.4 valid=300s;
+  resolver_timeout 5s;
+
+  # Other security options.
+  # add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload";
+  add_header X-Frame-Options DENY;
+  add_header X-Content-Type-Options nosniff;
+  add_header X-XSS-Protection "1; mode=block";
+
+  location / {
+    proxy_pass http://localhost:8443/;
+    proxy_set_header Accept-Encoding gzip;
+    proxy_set_header Connection upgrade;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+  }
+}
+```
+
+Make sure to set the `proxy_pass` directive to the actual address of your
+code-server instance and the `server_name` directive to the hostname/s of your
+website. If you're using an SSL certificate, make sure to change the
+`ssl_certificate` and `ssl_certificate_key` directives. If not, remove the HTTPS
+`server` block entirely.
+
+[nginx-install]: https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/#installing-a-prebuilt-package
+
+
+### Apache Reverse Proxy
+
+The following virtual host configuration file works with code-server. When
+starting code-server, be sure to provide the `--allow-http` and `--trust-proxy`
+flags so Apache can connect to code-server properly.
+
+Some of these directives require a version of Apache greater than or equal to
+`2.4.0`, which might not be available in your distro's repositories. You will
+also need to enable the following modules: `rewrite`, `proxy`, `proxy_http`,
+`proxy_wstunnel`, `ssl`, and `socache_shmcb`.
+
+```
+# HTTP configuration.
+<VirtualHost *:80>
+  ServerName code.example.com
+
+  # If you're using CloudFlare, uncomment the following line.
+  # RemoteIPHeader CF-Connecting-IP;
+
+  # Other security options.
+  Header always set X-Frame-Options DENY
+  Header always set X-Content-Type-Options nosniff
+
+  RewriteEngine On
+  RewriteCond %{HTTP:Upgrade} websocket [NC]
+  RewriteCond %{HTTP:Connection} upgrade [NC]
+  RewriteRule .* "ws://localhost:8443%{REQUEST_URI}" [P]
+
+  RequestHeader set X-Forwarded-Proto https
+  RequestHeader set X-Forwarded-Port 443
+
+  ProxyRequests off
+  ProxyPass / http://localhost:8443/ nocanon
+  ProxyPassReverse / http://localhost:8443/
+</VirtualHost>
+
+# HTTPS configuration. Scores an A on SSL Labs' SSL Server Test.
+<IfModule mod_ssl.c>
+  SSLStaplingCache shmcb:/tmp/stapling_cache(150000)
+  <VirtualHost *:443>
     ServerName code.example.com
 
-    RewriteEngine On
-    RewriteCond %{HTTP:Upgrade} =websocket [NC]
-    RewriteRule /(.*)           ws://localhost:8443/$1 [P,L]
-    RewriteCond %{HTTP:Upgrade} !=websocket [NC]
-    RewriteRule /(.*)           http://localhost:8443/$1 [P,L]
+    # If you're using CloudFlare, uncomment the following line.
+    # RemoteIPHeader CF-Connecting-IP;
 
-    ProxyRequests off
+    # SSL certificate and key.
+    SSLEngine On
+    SSLCertificateFile /path/to/cert.pem
+    SSLCertifcateKeyFile /path/to/cert-key.pem
+    SSLCertificateChainFile /path/to/chain.pem
+
+    # Strong TLS configuration. Originally taken from https://cipherli.st/.
+    SSLCipherSuite EECDH+AESGCM:EDH+AESGCM
+    SSLProtocol -all +TLSv1.2
+    SSLHonorCipherOrder On
+    SSLCompression off
+    SSLUseStapling on
+    SSLStaplingCache "shmcb:logs/stapling-cache(150000)"
+    SSLSessionTickets Off
+
+    # Other security options.
+    # Header always set Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"
+    Header always set X-Frame-Options DENY
+    Header always set X-Content-Type-Options nosniff
+
+    RewriteEngine On
+    RewriteCond %{HTTP:Upgrade} websocket [NC]
+    RewriteCond %{HTTP:Connection} upgrade [NC]
+    RewriteRule .* "ws://localhost:8443%{REQUEST_URI}" [P]
 
     RequestHeader set X-Forwarded-Proto https
     RequestHeader set X-Forwarded-Port 443
 
+    ProxyRequests off
     ProxyPass / http://localhost:8443/ nocanon
     ProxyPassReverse / http://localhost:8443/
-
   </VirtualHost>
-  ```
-  *Important:* For more details about Apache reverse proxy configuration checkout the [documentation](https://httpd.apache.org/docs/current/mod/mod_proxy.html) - especially the [Securing your Server](https://httpd.apache.org/docs/current/mod/mod_proxy.html#access) section
+</IfModule>
+```
+
+Make sure to set the `ProxyPass`, `ProxyPassReverse` and `RewriteRule`
+directives to the actual address of your code-server instance and the
+`ServerName` directive to the hostname of your website. If you're using SSL,
+make sure to change the `SSLCertificateFile`, `SSLCertificateKeyFile`, and
+`SSLCertificateChainFile` directives. If not, remove the HTTPS `IfModule` block
+entirely.
+
+For more details about Apache reverse proxy configuration, check out the
+[mod_proxy documentation](apache-mod_proxy).
 
-  ### Help
-  Use `code-server --help` to view the usage for the CLI. This is also shown at the beginning of this section.
+[apache-mod_proxy]: https://httpd.apache.org/docs/current/mod/mod_proxy.html