From a633705fa57981d861906811694785d8c21f558f Mon Sep 17 00:00:00 2001 From: Ben Potter Date: Mon, 12 Jul 2021 11:29:43 -0400 Subject: [PATCH 1/7] local preview: add instructions for dev urls --- setup/kubernetes/local-preview.md | 114 ++++++++++++++++++++++++++---- 1 file changed, 99 insertions(+), 15 deletions(-) diff --git a/setup/kubernetes/local-preview.md b/setup/kubernetes/local-preview.md index b80c5564b..f7af6ede9 100644 --- a/setup/kubernetes/local-preview.md +++ b/setup/kubernetes/local-preview.md @@ -4,8 +4,8 @@ description: Set up a Coder deployment locally for testing. --- Coder is typically deployed onto Kubernetes cluster, but if you would like to -set up a lightweight preview deployment, you can do so locally using using -[Docker][docker-url] and [kind][kind-url]. +set up a lightweight preview deployment, you can do so locally using using [URL] +and [URL]. > Coder currently supports local preview only on workstations running macOS or > Linux. @@ -31,9 +31,8 @@ deployment running entirely inside a Docker container. ### CVMs -The local preview supports [CVMs][cvm-url] if you meet the following -requirements (if you choose not to try out CVMs, these requirements do not -apply): +The local preview supports [URL] if you meet the following requirements (if you +choose not to try out CVMs, these requirements do not apply): 1. Your Linux hosts must be running Linux Kernel 5 and above. @@ -50,17 +49,17 @@ apply): linux linux-headers-5.11.4-arch1-1 ``` -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). +1. Docker Desktop for Mac **must** use version [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. +The local preview doesn't support [dev URL] by default. Instead, you can use +tools like [URL] to preview webpages from inside a workspace. -We are working on bringing Dev URL support to local previews in later releases. +To enable local dev URLs, follow +[the instructions below](#enable-local-dev-urls) after installing Coder. ### Air-gapped clusters @@ -71,11 +70,11 @@ 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 80 When the installation process completes, you'll see the URL and login credentials you need to access Coder: @@ -83,7 +82,7 @@ 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 @@ -97,6 +96,73 @@ 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. +## Enable local dev URLs + +To enable dev URLs on your local machine, [dnsmasq](dnsmasq-url) can be used to +create local domains (e.g and +). + +Here's how: + +1. Install dnsmasq + + ```console + # Mac OS + brew install dnsmasq + + # Linux (Ubuntu) + sudo apt-get install dnsmasq + ``` + +1. Create 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 + ``` + + ```conf + # 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. Add the domains to the helm config. Your deployment will need the following + helm values: + + ```yaml + ingress: + host: "dashboard.coder" + devurls: + host: "*.coder" + ``` + + If you have not done this before, follow our docs to + [update coder](https://coder.com/docs/coder/latest/setup/updating#update-coder) + while adding helm values. + ## Removing Coder To remove the local Coder deployment, run: @@ -108,7 +174,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 custom DNS for [local dev URLs](enable-local-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 [kind-url]: https://kind.sigs.k8s.io/ [cvm-url]: https://coder.com/docs/workspaces/cvms [docker-mac-url]: From 256c75062f325b96e56207c0cabadaf5a2815186 Mon Sep 17 00:00:00 2001 From: Ben Potter Date: Mon, 12 Jul 2021 12:53:06 -0400 Subject: [PATCH 2/7] add nip.io instructions --- setup/kubernetes/local-preview.md | 35 ++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 12 deletions(-) diff --git a/setup/kubernetes/local-preview.md b/setup/kubernetes/local-preview.md index f7af6ede9..6ee0fe634 100644 --- a/setup/kubernetes/local-preview.md +++ b/setup/kubernetes/local-preview.md @@ -98,11 +98,24 @@ automatically configured for you, so there's no first-time setup to do. ## Enable local dev URLs -To enable dev URLs on your local machine, [dnsmasq](dnsmasq-url) can be used to -create local domains (e.g and -). +A wildcard subdomain is required to use dev URLs with Coder. One option is to +use a service such as [nip.io](nip-url) to route domains local IP. + +[Update Coder](https://coder.com/docs/coder/latest/setup/updating#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" +``` -Here's how: +Alternatively, [dnsmasq](dnsmasq-url) can be used 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: 1. Install dnsmasq @@ -149,20 +162,17 @@ Here's how: nameserver 127.0.0.1 ``` -1. Add the domains to the helm config. Your deployment will need the following - helm values: +1. To use the new domains, + [update Coder](https://coder.com/docs/coder/latest/setup/updating#update-coder) + with these helm values added: ```yaml ingress: - host: "dashboard.coder" + host: "dashboard.coder" devurls: - host: "*.coder" + host: "*.coder" ``` - If you have not done this before, follow our docs to - [update coder](https://coder.com/docs/coder/latest/setup/updating#update-coder) - while adding helm values. - ## Removing Coder To remove the local Coder deployment, run: @@ -202,3 +212,4 @@ sudo vim /etc/resolv.conf [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 From 0bc5d1bca6713d9400a44c5676ddbb6daa129b10 Mon Sep 17 00:00:00 2001 From: Ben Potter Date: Mon, 12 Jul 2021 14:58:55 -0400 Subject: [PATCH 3/7] fix broken links --- setup/kubernetes/local-preview.md | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/setup/kubernetes/local-preview.md b/setup/kubernetes/local-preview.md index 6ee0fe634..04d95c385 100644 --- a/setup/kubernetes/local-preview.md +++ b/setup/kubernetes/local-preview.md @@ -4,8 +4,8 @@ description: Set up a Coder deployment locally for testing. --- Coder is typically deployed onto Kubernetes cluster, but if you would like to -set up a lightweight preview deployment, you can do so locally using using [URL] -and [URL]. +set up a lightweight preview deployment, you can do so locally using using +[Docker][docker-url] and [kind][kind-url]. > Coder currently supports local preview only on workstations running macOS or > Linux. @@ -31,8 +31,9 @@ deployment running entirely inside a Docker container. ### CVMs -The local preview supports [URL] if you meet the following requirements (if you -choose not to try out CVMs, these requirements do not apply): +The local preview supports [CVMs][cvm-url] if you meet the following +requirements (if you choose not to try out CVMs, these requirements do not +apply): 1. Your Linux hosts must be running Linux Kernel 5 and above. @@ -49,14 +50,15 @@ choose not to try out CVMs, these requirements do not apply): linux linux-headers-5.11.4-arch1-1 ``` -1. Docker Desktop for Mac **must** use version [URL]. This specific version is - required because of a recent downgrade to Linux Kernel 4.9 due to a - [bug](docker-bug-url). +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 -The local preview doesn't support [dev URL] by default. Instead, you can use -tools like [URL] to preview webpages from inside a workspace. +The local preview doesn't support [dev URLs](../workspaces/devurls) by default. +Instead, you can use tools like [ngrok][ngrok-url] to preview webpages from +inside a workspace. To enable local dev URLs, follow [the instructions below](#enable-local-dev-urls) after installing Coder. @@ -99,7 +101,7 @@ automatically configured for you, so there's no first-time setup to do. ## Enable local dev URLs A wildcard subdomain is required to use dev URLs with Coder. One option is to -use a service such as [nip.io](nip-url) to route domains local IP. +use a service such as [nip.io][nip-url] to route domains local IP. [Update Coder](https://coder.com/docs/coder/latest/setup/updating#update-coder) with the following helm values added for either your local (127.0.0.1) or @@ -112,7 +114,7 @@ devurls: host: "*.127.0.0.1.nip.io" ``` -Alternatively, [dnsmasq](dnsmasq-url) can be used to create local domains (e.g +Alternatively, [dnsmasq][dnsmasq-url] can be used 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: @@ -162,9 +164,8 @@ rebinding protection. Here's how: nameserver 127.0.0.1 ``` -1. To use the new domains, - [update Coder](https://coder.com/docs/coder/latest/setup/updating#update-coder) - with these helm values added: +1. To use the new domains, [update Coder](../updating#update-coder) with these + helm values added: ```yaml ingress: @@ -184,7 +185,7 @@ 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 custom DNS for [local dev URLs](enable-local-dev-urls), you can +If you added custom DNS for [local dev URLs](#enable-local-dev-urls), you can revert these changes by uninstalling dnsmasq and removing the resolver config: ```console From 4ea06da54fbdd90737803c918ef3423a9f0b89dc Mon Sep 17 00:00:00 2001 From: Ben Potter Date: Mon, 12 Jul 2021 16:30:02 -0400 Subject: [PATCH 4/7] reword dev urls limitation --- setup/kubernetes/local-preview.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/setup/kubernetes/local-preview.md b/setup/kubernetes/local-preview.md index 04d95c385..6bbe77dea 100644 --- a/setup/kubernetes/local-preview.md +++ b/setup/kubernetes/local-preview.md @@ -56,13 +56,14 @@ apply): ### Dev URLs -The local preview doesn't support [dev URLs](../workspaces/devurls) by default. -Instead, you can use tools like [ngrok][ngrok-url] to preview webpages from -inside a workspace. +When Coder is installed, dev URLs are not enabled by default. To enable local dev URLs, follow [the instructions below](#enable-local-dev-urls) after installing Coder. +If you do not want to enable dev URLs, you can use SSH portforwarding or tools +like [ngrok][ngrok-url] to preview webpages from inside a workspace. + ### Air-gapped clusters The local preview option does not work in an air-gapped deployment. From 337c829c1594bbf6993122b149a959dcdb2569ca Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Tue, 13 Jul 2021 14:34:10 -0500 Subject: [PATCH 5/7] Edit text --- setup/kubernetes/local-preview.md | 58 +++++++++++++++---------------- 1 file changed, 28 insertions(+), 30 deletions(-) diff --git a/setup/kubernetes/local-preview.md b/setup/kubernetes/local-preview.md index 6bbe77dea..0cd8b820e 100644 --- a/setup/kubernetes/local-preview.md +++ b/setup/kubernetes/local-preview.md @@ -54,16 +54,6 @@ apply): specific version is required because of a recent downgrade to Linux Kernel 4.9 due to a [bug][docker-bug-url]. -### Dev URLs - -When Coder is installed, dev URLs are not enabled by default. - -To enable local dev URLs, follow -[the instructions below](#enable-local-dev-urls) after installing Coder. - -If you do not want to enable dev URLs, you can use SSH portforwarding or tools -like [ngrok][ngrok-url] to preview webpages from inside a workspace. - ### Air-gapped clusters The local preview option does not work in an air-gapped deployment. @@ -77,7 +67,7 @@ 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. However, dev URLs will only work when PORT is 80 +> 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: @@ -99,26 +89,34 @@ 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. -## Enable local dev URLs +### Dev URLs -A wildcard subdomain is required to use dev URLs with Coder. One option is to -use a service such as [nip.io][nip-url] to route domains local IP. +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. -[Update Coder](https://coder.com/docs/coder/latest/setup/updating#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: +> 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. -```yaml -ingress: - host: "127.0.0.1.nip.io" -devurls: - host: "*.127.0.0.1.nip.io" -``` +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 local +IP address. + +1. [Update Coder](https://coder.com/docs/coder/latest/setup/updating#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, [dnsmasq][dnsmasq-url] can be used to create local domains (e.g +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: +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 @@ -130,7 +128,7 @@ rebinding protection. Here's how: sudo apt-get install dnsmasq ``` -1. Create dnsmasq configuration for the .coder domain +1. Create a dnsmasq configuration for the `.coder` domain ```console # Mac OS @@ -165,8 +163,8 @@ rebinding protection. Here's how: nameserver 127.0.0.1 ``` -1. To use the new domains, [update Coder](../updating#update-coder) with these - helm values added: +1. [Update Coder](../updating#update-coder) with these Helm values added to use + your new domains: ```yaml ingress: @@ -186,7 +184,7 @@ 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 custom DNS for [local dev URLs](#enable-local-dev-urls), you can +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 From cae06d43e3f380355be5c05ae918568abf62ca24 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Wed, 14 Jul 2021 10:55:28 -0500 Subject: [PATCH 6/7] Fix typos --- setup/kubernetes/local-preview.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/setup/kubernetes/local-preview.md b/setup/kubernetes/local-preview.md index 0cd8b820e..5efc9775a 100644 --- a/setup/kubernetes/local-preview.md +++ b/setup/kubernetes/local-preview.md @@ -99,12 +99,12 @@ installed Coder. > 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 local -IP address. + requirement is to use a service such as [nip.io][nip-url] to route domains to + a local IP address. -1. [Update Coder](https://coder.com/docs/coder/latest/setup/updating#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: +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: From c71b19a34f79d59ac4f5a001cbc84efd99bbc235 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Mon, 19 Jul 2021 09:38:35 -0500 Subject: [PATCH 7/7] Lint --- setup/kubernetes/local-preview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup/kubernetes/local-preview.md b/setup/kubernetes/local-preview.md index eaa2ab330..1f86d837a 100644 --- a/setup/kubernetes/local-preview.md +++ b/setup/kubernetes/local-preview.md @@ -181,7 +181,7 @@ protection. Here's how to do this: devurls: host: "*.coder" ``` - + ## Option 2: Docker Desktop [Docker Desktop](docker-desktop-url) includes a standalone Kubernetes server and