From a3432b4265551d18af5572a9a4cbdcb53b058633 Mon Sep 17 00:00:00 2001 From: Stephen Kirby <58410745+stirby@users.noreply.github.com> Date: Wed, 13 Dec 2023 15:56:11 -0600 Subject: [PATCH] docs: add faqs from sharkymark (#11168) * added sharkymark FAQs page * make fmt * fixed typos for link * changed FAQs icon to (i) * satisfied review * make fmt * added docs links for coder_app, CODER_ACCESS_URL * removed mentions of mark * fixed some minor code formatting issues * fixed numbered bullets rendering, make fmt --- docs/faqs.md | 405 +++++++++++++++++++++++++++++++++++++++++++++ docs/manifest.json | 6 + 2 files changed, 411 insertions(+) create mode 100644 docs/faqs.md diff --git a/docs/faqs.md b/docs/faqs.md new file mode 100644 index 0000000000..000109ecf0 --- /dev/null +++ b/docs/faqs.md @@ -0,0 +1,405 @@ +# FAQs + +Frequently asked questions on Coder OSS and Enterprise deployments. These FAQs +come from our community and enterprise customers, feel free to +[contribute to this page](https://github.com/coder/coder/edit/main/docs/faqs.md). + +## How do I add an enterprise license? + +Visit https://coder.com/trial or contact +[sales@coder.com](mailto:sales@coder.com?subject=License) to get a v2 enterprise +trial key. + +You can add a license through the UI or CLI. + +In the UI, click the Deployment tab -> Licenses and upload the `jwt` license +file. + +> To add the license with the CLI, first +> [install the Coder CLI](https://coder.com/docs/v2/latest/install/install.sh) +> and server to the latest release. + +If the license is a text string: + +```sh +coder licenses add -l 1f5...765 +``` + +If the license is in a file: + +```sh +coder licenses add -f +``` + +## I'm experiencing networking issues, so want to disable Tailscale, STUN, Direct connections and force use of websockets + +The primary developer use case is a local IDE connecting over SSH to a Coder +workspace. + +Coder's networking stack has intelligence to attempt a peer-to-peer or +[Direct connection](https://coder.com/docs/v2/latest/networking#direct-connections) +between the local IDE and the workspace. However, this requires some additional +protocols like UDP and being able to reach a STUN server to echo the IP +addresses of the local IDE machine and workspace, for sharing using a Wireguard +Coordination Server. By default, Coder assumes Internet and attempts to reach +Google's STUN servers to perform this IP echo. + +Operators experimenting with Coder may run into networking issues if UDP (which +STUN requires) or the STUN servers are unavailable, potentially resulting in +lengthy local IDE and SSH connection times as the Coder control plane attempts +to establish these direct connections. + +Setting the following flags as shown disables this logic to simplify +troubleshooting. + +| Flag | Value | Meaning | +| -------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------- | +| [`CODER_BLOCK_DIRECT`](https://coder.com/docs/v2/latest/cli/server#--block-direct-connections) | `true` | Blocks direct connections | +| [`CODER_DERP_SERVER_STUN_ADDRESSES`](https://coder.com/docs/v2/latest/cli/server#--derp-server-stun-addresses) | `"disable"` | Disables STUN | +| [`CODER_DERP_FORCE_WEBSOCKETS`](https://coder.com/docs/v2/latest/cli/server#--derp-force-websockets) | `true` | Forces websockets over Tailscale DERP | + +## How do I configure NGINX as the reverse proxy in front of Coder? + +[This doc](https://github.com/coder/coder/tree/main/examples/web-server/nginx#configure-nginx) +in our repo explains in detail how to configure NGINX with Coder so that our +Tailscale Wireguard networking functions properly. + +## How do I hide some of the default icons in a workspace like VS Code Desktop, Terminal, SSH, Ports? + +The visibility of Coder apps is configurable in the template. To change the +default (shows all), add this block inside the +[`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app) +of a template and configure as needed: + +```hcl + display_apps { + vscode = false + vscode_insiders = false + ssh_helper = false + port_forwarding_helper = false + web_terminal = true + } +``` + +This example will hide all built-in coder_app icons except the web terminal. + +## I want to allow code-server to be accessible by other users in my deployment. + +> It is **not** recommended to share a web IDE, but if required, the following +> deployment environment variable settings are required. + +Set deployment (Kubernetes) to allow path app sharing + +```yaml +# allow authenticated users to access path-based workspace apps +- name: CODER_DANGEROUS_ALLOW_PATH_APP_SHARING + value: "true" +# allow Coder owner roles to access path-based workspace apps +- name: CODER_DANGEROUS_ALLOW_PATH_APP_SITE_OWNER_ACCESS + value: "true" +``` + +In the template, set +[`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app) +[`share`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app#share) +option to `authenticated` and when a workspace is built with this template, the +pretty globe shows up next to path-based `code-server`: + +```hcl +resource "coder_app" "code-server" { + ... + share = "authenticated" + ... +} +``` + +## I installed Coder and created a workspace but the icons do not load. + +An important concept to understand is that Coder creates workspaces which have +an agent that must be able to reach the `coder server`. + +If the +[`CODER_ACCESS_URL`](https://coder.com/docs/v2/latest/admin/configure#access-url) +is not accessible from a workspace, the workspace may build, but the agent +cannot reach Coder, and thus the missing icons. e.g., Terminal, IDEs, Apps. + +> By default, `coder server` automatically creates an Internet-accessible +> reverse proxy so that workspaces you create can reach the server. + +If you are doing a standalone install, e.g., on a Macbook and want to build +workspaces in Docker Desktop, everything is self-contained and workspaces +(containers in Docker Desktop) can reach the Coder server. + +```sh +coder server --access-url http://localhost:3000 --address 0.0.0.0:3000 +``` + +> Even `coder server` which creates a reverse proxy, will let you use +> http://localhost to access Coder from a browser. + +## I updated a template, and an existing workspace based on that template fails to start. + +When updating a template, be aware of potential issues with input variables. For +example, if a template prompts users to choose options like a +[code-server](https://github.com/coder/code-server) +[VS Code](https://code.visualstudio.com/) IDE release, a +[container image](https://hub.docker.com/u/codercom), or a +[VS Code extension](https://marketplace.visualstudio.com/vscode), removing any +of these values can lead to existing workspaces failing to start. This issue +occurs because the Terraform state will not be in sync with the new template. + +However, a lesser-known CLI sub-command, +[`coder update`](https://coder.com/docs/v2/latest/cli/update), can resolve this +issue. This command re-prompts users to re-enter the input variables, +potentially saving the workspace from a failed status. + +```sh +coder update --always-prompt +``` + +## I'm running coder on a VM with systemd but latest release installed isn't showing up. + +Take, for example, a Coder deployment on a VM with a 2 shared vCPU systemd +service. In this scenario, it's necessary to reload the daemon and then restart +the Coder service. This prevents the `systemd` daemon from trying to reference +the previous Coder release service since the unit file has changed. + +The following commands can be used to update Coder and refresh the service: + +```sh +curl -fsSL https://coder.com/install.sh | sh +sudo systemctl daemon-reload +sudo systemctl restart coder.service +``` + +## I'm using the built-in Postgres database and forgot admin email I set up. + +1. Run the `coder server` command below to retrieve the `psql` connection URL + which includes the database user and password. +2. `psql` into Postgres, and do a select query on the `users` table. +3. Restart the `coder server`, pull up the Coder UI and log in (you will still + need your password) + +```sh +coder server postgres-builtin-url +psql "postgres://coder@localhost:53737/coder?sslmode=disable&password=I2S...pTk" +``` + +## How to find out Coder's latest Terraform provider version? + +[Coder is on the HashiCorp's Terraform registry](https://registry.terraform.io/providers/coder/coder/latest). +Check this frequently to make sure you are on the latest version. + +Sometimes, the version may change and `resource` configurations will either +become deprecated or new ones will be added when you get warnings or errors +creating and pushing templates. + +## How can I set up TLS for my deployment and not create a signed certificate? + +Caddy is an easy-to-configure reverse proxy that also automatically creates +certificates from Let's Encrypt. +[Install docs here](https://caddyserver.com/docs/quick-starts/reverse-proxy) You +can start Caddy as a `systemd` service. + +The Caddyfile configuration will appear like this where `127.0.0.1:3000` is your +`CODER_ACCESS_URL`: + +```text +coder.example.com { + + reverse_proxy 127.0.0.1:3000 + + tls { + + issuer acme { + email user@example.com + } + + } +} +``` + +## I'm using Caddy as my reverse proxy in front of Coder. How do I set up a wildcard domain for port forwarding? + +Caddy requires your DNS provider's credentials to create wildcard certificates. +This involves building the Caddy binary +[from source](https://github.com/caddyserver/caddy) with the DNS provider plugin +added. e.g., +[Google Cloud DNS provider here](https://github.com/caddy-dns/googleclouddns) + +To compile Caddy, the host running Coder requires Go. Once installed, replace +the existing Caddy binary in `usr/bin` and restart the Caddy service. + +The updated Caddyfile configuration will look like this: + +```text +*.coder.example.com, coder.example.com { + + reverse_proxy 127.0.0.1:3000 + + tls { + issuer acme { + email user@example.com + dns googleclouddns { + gcp_project my-gcp-project + } + } + } + +} +``` + +## Can I use local or remote Terraform Modules in Coder templates? + +One way is to reference a Terraform module from a GitHub repo to avoid +duplication and then just extend it or pass template-specific +parameters/resources: + +```hcl +# template1/main.tf +module "central-coder-module" { + source = "github.com/yourorg/central-coder-module" + myparam = "custom-for-template1" +} + +resource "ebs_volume" "custom_template1_only_resource" { +} +``` + +```hcl +# template2/main.tf +module "central-coder-module" { + source = "github.com/yourorg/central-coder-module" + myparam = "custom-for-template2" + myparam2 = "bar" +} + +resource "aws_instance" "custom_template2_only_resource" { +} +``` + +Another way using local modules is to symlink the module directory inside the +template directory and then `tar` the template. + +```sh +ln -s modules template_1/modules +tar -cvh -C ./template_1 | coder templates -d - +``` + +References: + +- [Public Github Issue 6117](https://github.com/coder/coder/issues/6117) +- [Public Github Issue 5677](https://github.com/coder/coder/issues/5677) +- [Coder docs: Templates/Change Management](https://coder.com/docs/v2/latest/templates/change-management) + +## Can I run Coder in an air-gapped or offline mode? (no Internet)? + +Yes, Coder can be deployed in air-gapped or offline mode. +https://coder.com/docs/v2/latest/install/offline + +Our product bundles with the Terraform binary so assume access to terraform.io +during installation. The docs outline rebuilding the Coder container with +Terraform built-in as well as any required Terraform providers. + +Direct networking from local SSH to a Coder workspace needs a STUN server. Coder +defaults to Google's STUN servers, so you can either create your STUN server in +your network or disable and force all traffic through the control plane's DERP +proxy. + +## Create a randomized computer_name for an Azure VM + +Azure VMs have a 15 character limit for the `computer_name` which can lead to +duplicate name errors. + +This code produces a hashed value that will be difficult to replicate. + +```hcl +locals { + concatenated_string = "${data.coder_workspace.me.name}+${data.coder_workspace.me.owner}" + hashed_string = md5(local.concatenated_string) + truncated_hash = substr(local.hashed_string, 0, 16) +} +``` + +## Do you have example JetBrains Gateway templates? + +In August 2023, JetBrains certified the Coder plugin signifying enhanced +stability and reliability. + +The Coder plugin will appear in the Gateway UI when opened. + +Selecting the most suitable template depends on how the deployment manages +JetBrains IDE versions. If downloading from +[jetbrains.com](https://www.jetbrains.com/remote-development/gateway/) is +acceptable, see the example templates below which specifies the product code, +IDE version and build number in the +[`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app#share) +resource. This will present an icon in the workspace dashboard which when +clicked, will look for a locally installed Gateway, and open it. Alternatively, +the IDE can be baked into the container image and manually open Gateway (or +IntelliJ which has Gateway built-in), using a session token to Coder and then +open the IDE. + +- [IntelliJ IDEA](https://github.com/sharkymark/v2-templates/tree/main/pod-idea) +- [IntelliJ IDEA with Icon](https://github.com/sharkymark/v2-templates/tree/main/pod-idea-icon) + +## What options do I have for adding VS Code extensions into code-server, VS Code Desktop or Microsoft's Code Server? + +Coder has an open-source project called +[`code-marketplace`](https://github.com/coder/code-marketplace) which is a +private VS Code extension marketplace. There is even integration with JFrog +Artifactory. + +- [Blog post](https://coder.com/blog/running-a-private-vs-code-extension-marketplace) +- [OSS project](https://github.com/coder/code-marketplace) + +[See this example template](https://github.com/sharkymark/v2-templates/blob/main/code-marketplace/main.tf#L229C1-L232C12) +where the agent specifies the URL and config environment variables which +code-server picks up and points the developer to. + +Another option is to use Microsoft's code-server - which is like Coder's, but it +can connect to Microsoft's extension marketplace so Copilot and chat can be +retrieved there. +[See a sample template here](https://github.com/sharkymark/v2-templates/blob/main/vs-code-server/main.tf). + +Another option is to use VS Code Desktop (local) and that connects to +Microsoft's marketplace. +https://github.com/sharkymark/v2-templates/blob/main/vs-code-server/main.tf + +> Note: these are example templates with no SLAs on them and are not guaranteed +> for long-term support. + +## I want to run Docker for my workspaces but not install Docker Desktop. + +[Colima](https://github.com/abiosoft/colima) is a Docker Desktop alternative. + +This example is meant for a users who want to try out Coder on a macOS device. + +Install Colima and docker with: + +```sh +brew install colima +brew install docker +``` + +Start Colima: + +```sh +colima start +``` + +Start Colima with specific compute options: + +```sh +colima start --cpu 4 --memory 8 +``` + +Starting Colima on a M3 Macbook Pro: + +```sh +colima start --arch x86_64 --cpu 4 --memory 8 --disk 10 +``` + +Colima will show the path to the docker socket so I have a +[Coder template](./docker-code-server/main.tf) that prompts the Coder admin to +enter the docker socket as a Terraform variable. diff --git a/docs/manifest.json b/docs/manifest.json index a2afe8f3b0..be663809c2 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1012,6 +1012,12 @@ "path": "./security/0001_user_apikeys_invalidation.md" } ] + }, + { + "title": "FAQs", + "description": "Frequently asked questions", + "path": "./faqs.md", + "icon_path": "./images/icons/info.svg" } ] }