local preview: add instructions for dev urls (type fixed) (coder#496)

bpmct · Katie Horne · web-flow · commit d65649f7db4d · 2021-07-19T15:31:09.000-04:00
* local preview: add instructions for dev urls

* add nip.io instructions

* fix broken links

* reword dev urls limitation

* Edit text

* Fix typos

* Lint

* fix "conf" type

Co-authored-by: Katie Horne &lt;katie@coder.com&gt;
diff --git a/setup/kubernetes/local-preview.md b/setup/kubernetes/local-preview.md
@@ -54,15 +54,7 @@ apply):
 
 1. Docker Desktop for Mac **must** use version [2.5.0.1][docker-mac-url]. This
    specific version is required because of a recent downgrade to Linux Kernel
-   4.9 due to a [bug](docker-bug-url).
-
-### Dev URLs
-
-Currently, the local preview doesn't support [dev URLs][devurl-url]. Instead,
-you can use tools like [ngrok][ngrok-url] to preview webpages from inside an
-workspace.
-
-We are working on bringing Dev URL support to local previews in later releases.
+   4.9 due to a [bug][docker-bug-url].
 
 ### SSH
 
@@ -80,19 +72,19 @@ The local preview option does not work in an air-gapped deployment.
 To install Coder, run:
 
 ```console
-curl -fsSL https://coder.com/try.sh | PORT="8080" sh -s --
+curl -fsSL https://coder.com/try.sh | PORT="80" sh -s --
 ```
 
 > Note: you can edit the value of `PORT` to control where the Coder dashboard
-> will be available.
+> will be available. However, dev URLs will only work when `PORT` is set to `80`.
 
 When the installation process completes, you'll see the URL and login
 credentials you need to access Coder:
 
 ```txt
 You can now access Coder at
 
-    http://localhost:8080
+    http://localhost:80
 
 You can tear down the deployment with
 
@@ -106,6 +98,90 @@ Password: yfu...yu2
 Visit the URL, and log in using the provided credentials. The platform is
 automatically configured for you, so there's no first-time setup to do.
 
+### Dev URLs
+
+Coder allows you to access services you're developing in your workspace via [dev
+URLs](../../workspaces/devurls.md). You can enable dev URLs after you've
+installed Coder.
+
+> If you do not want to enable dev URLs, you can use SSH port forwarding or
+> tools like [ngrok][ngrok-url] to preview webpages from inside you workspace.
+
+1. To use dev URLs, you must have a wildcard subdomain. One option to meet this
+   requirement is to use a service such as [nip.io][nip-url] to route domains to
+   a local IP address.
+
+1. [Update Coder](../updating.md#update-coder) with the following Helm values
+   added for either your local (`127.0.0.1`) or private (e.g., `192.168.1.x`)
+   address:
+
+   ```yaml
+   ingress:
+   host: "127.0.0.1.nip.io"
+   devurls:
+   host: "*.127.0.0.1.nip.io"
+   ```
+
+Alternatively, you can use [dnsmasq][dnsmasq-url] to create local domains (e.g.,
+`http://dashboard.coder` and `http://*.coder`). This may be useful if you do not
+want to rely on an external service/network or if your network has DNS rebinding
+protection. Here's how to do this:
+
+1. Install dnsmasq
+
+   ```console
+   # Mac OS
+   brew install dnsmasq
+
+   # Linux (Ubuntu)
+   sudo apt-get install dnsmasq
+   ```
+
+1. Create a dnsmasq configuration for the `.coder` domain
+
+   ```console
+   # Mac OS
+   sudo touch $(brew --prefix)/etc/dnsmasq.d/coder.conf
+   sudo vim $(brew --prefix)/etc/dnsmasq.d/coder.conf
+
+   # Linux (Ubuntu)
+   sudo touch /etc/dnsmasq.d/coder.conf
+   sudo vim /etc/dnsmasq.d/coder.conf
+   ```
+
+   ```text
+   # coder.conf
+   address=/coder/127.0.0.1
+   ```
+
+1. Add dnsmasq as DNS resolver on your machine
+
+   ```console
+   # Mac OS: this will only route
+   # .coder domains to dnsmasq
+   sudo mkdir -p /etc/resolver
+   sudo touch /etc/resolver/
+   sudo vim /etc/resolver/coder
+
+   # Linux (Ubuntu)
+   # add to top of the file
+   sudo vim /etc/resolv.conf
+   ```
+
+   ```text
+   nameserver 127.0.0.1
+   ```
+
+1. [Update Coder](../updating#update-coder) with these Helm values added to use
+   your new domains:
+
+   ```yaml
+   ingress:
+   host: "dashboard.coder"
+   devurls:
+   host: "*.coder"
+   ```
+
 ## Option 2: Docker Desktop
 
 [Docker Desktop](docker-desktop-url) includes a standalone Kubernetes server and
@@ -155,7 +231,25 @@ curl -fsSL https://coder.com/try.sh | sh -s -- down
 Because Coder runs inside Docker, you should have nothing left on your machine
 after tear down.
 
+If you added a custom DNS to use [dev URLs](#dev-urls), you can
+revert these changes by uninstalling dnsmasq and removing the resolver config:
+
+```console
+# MacOS
+brew remove dnsmasq
+sudo rm -r /etc/resolver/coder
+
+# Linux (Ubuntu)
+sudo apt-get remove dnsmasq
+sudo vim /etc/resolv.conf
+# remove "nameserver 127.0.0.1"
+# and ensure you have another
+# nameserver specified
+# e.g "nameserver 127.0.0.53"
+```
+
 [docker-url]: https://www.docker.com/
+[dnsmasq-url]: https://linux.die.net/man/8/dnsmasq
 [docker-desktop-url]: https://www.docker.com/products/docker-desktop
 [docker-k8s-docs]: https://docs.docker.com/desktop/kubernetes/
 [kind-url]: https://kind.sigs.k8s.io/
@@ -167,3 +261,4 @@ after tear down.
 [docker-bug-url]: https://github.com/docker/for-mac/issues/5044
 [ngrok-url]: https://ngrok.com
 [devurl-url]: https://coder.com/docs/workspaces/devurls
+[nip-url]: https://nip.io
