From a13d696298ec698c3a2bedc3abf20a1f8d8650b3 Mon Sep 17 00:00:00 2001 From: Ben Date: Thu, 2 Mar 2023 15:44:15 +0000 Subject: [PATCH 1/5] docs: clarify requirements for offline deployments --- docs/install/offline.md | 27 +++++++++++++++++++++++++-- docs/networking.md | 14 ++++++++------ 2 files changed, 33 insertions(+), 8 deletions(-) diff --git a/docs/install/offline.md b/docs/install/offline.md index 94e856a364e03..252fd5e585c58 100644 --- a/docs/install/offline.md +++ b/docs/install/offline.md @@ -1,8 +1,21 @@ # Offline Deployments -Coder can run in offline / air-gapped environments. +All Coder features are supported in offline / behind firewalls / in air-gapped environments. However, some changes to your configuration are necessary. -## Building & push a custom Coder image +> This is a general comparison. Keep reading for a full tutorial running Coder offline with Kubernetes or Docker. + +| | Public deployments | Offline deployments | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Terraform binary | By default, Coder downloads Terraform binary from [releases.hashicorp.com](https://releases.hashicorp.com) | Terraform binary must be included in `PATH` for the VM or container image. [Supported versions](https://github.com/coder/coder/blob/main/provisioner/terraform/install.go#L23-L24) | +| Terraform registry | Coder templates will attempt to download providers from [registry.terraform.io](https://registry.terraform.io) or [custom source addresses](https://developer.hashicorp.com/terraform/language/providers/requirements#source-addresses) specified in each template | [Custom source addresses](https://developer.hashicorp.com/terraform/language/providers/requirements#source-addresses) can be specified in each Coder template, or a custom registry/mirror can be used. More details below | +| STUN | By default, Coder uses Google's public STUN server for direct workspace connections | STUN can be safely [disabled](../cli/coder_server#--derp-server-stun-addresses), users can still connect via [relayed connections](../networking.md#-geo-distribution). Alternatively, you can set a [custom DERP server](../cli/coder_server#--derp-server-stun-addresses) | +| DERP | By default, Coder's built-in DERP relay can be used, or [Tailscale's public relays](../networking.md#relayed-connections). | By default, Coder's built-in DERP relay can be used, or [custom relays](../networking.md#custom-relays). | +| PostgreSQL | If no [PostgreSQL connection URL](../cli/coder_server#--postgres-url) is specified, Coder will download Postgres from [repo1.maven.org](https://repo1.maven.org). | An external database is required, you must specified a [PostgreSQL connection URL](../cli/coder_server#--postgres-url) | +| Telemetry | Telemetry is on by default, and [can be disabled](../cli/coder_server#--telemetry) | Telemetry [can be disabled](../cli/coder_server#--telemetry) | + +## Offline container images + +The following instructions walk you through how to build a custom Coder server image for Docker or Kubernetes First, build and push a container image extending our official image with the following: @@ -127,6 +140,9 @@ services: volumes: - ./plugins:/opt/terraform/plugins # ... + environment: + CODER_TELEMETRY_ENABLE: false # disable telemetry + CODER_DERP_SERVER_STUN_ADDRESSES: "" # only use relayed connections database: image: registry.example.com/postgres:13 # ... @@ -144,5 +160,12 @@ coder: image: repo: "registry.example.com/coder" tag: "latest" + env: + # Disable telemetry + - name: "CODER_TELEMETRY_ENABLE" + value: "false" + # Only use relayed connections + - name: "CODER_DERP_SERVER_STUN_ADDRESSES" + value: "" # ... ``` diff --git a/docs/networking.md b/docs/networking.md index d37d4633a6aa3..0844a936ec1ae 100644 --- a/docs/networking.md +++ b/docs/networking.md @@ -50,12 +50,16 @@ Direct connections are a straight line between the user and workspace, so there is no special geo-distribution configuration. To speed up direct connections, move the user and workspace closer together. +If a direct connection is not available (e.g. client or server is behind NAT), Coder +will use a relayed connection. By default, [Coder uses Google's public STUN server](./cli/coder_server#--derp-server-stun-addresses), but +this can be disabled or changed for [offline deployments](./install/offline.md). + ### Relayed connections -Tailscale has graciously allowed us to use -[their global DERP relays](https://tailscale.com/kb/1118/custom-derp-servers/#what-are-derp-servers). +By default, your Coder server also runs a built-in DERP relay which can be used for both public and [offline deployments](./install/offline.md). -You can launch `coder server` with Tailscale's DERPs like so: +However, Tailscale has graciously allowed us to use +[their global DERP relays](https://tailscale.com/kb/1118/custom-derp-servers/#what-are-derp-servers). You can launch `coder server` with Tailscale's DERPs like so: ```bash $ coder server --derp-config-url https://controlplane.tailscale.com/derpmap/default @@ -63,9 +67,7 @@ $ coder server --derp-config-url https://controlplane.tailscale.com/derpmap/defa #### Custom Relays -If you run Coder in air-gap mode or want lower latency than what Tailscale offers, -you may run custom DERP servers. Refer to -[Tailscale's documentation](https://tailscale.com/kb/1118/custom-derp-servers/#why-run-your-own-derp-server) +If you want lower latency than what Tailscale offers or want additional DERP relays for offline deployments, you may run custom DERP servers. Refer to [Tailscale's documentation](https://tailscale.com/kb/1118/custom-derp-servers/#why-run-your-own-derp-server) to learn how to set them up. After you have custom DERP servers, you can launch Coder with them like so: From 58b7546f70708630c36b2147df993144b844dc93 Mon Sep 17 00:00:00 2001 From: Ben Date: Thu, 2 Mar 2023 15:51:52 +0000 Subject: [PATCH 2/5] fix punctuation --- docs/install/offline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/offline.md b/docs/install/offline.md index 252fd5e585c58..3de020b1d6068 100644 --- a/docs/install/offline.md +++ b/docs/install/offline.md @@ -10,7 +10,7 @@ All Coder features are supported in offline / behind firewalls / in air-gapped e | Terraform registry | Coder templates will attempt to download providers from [registry.terraform.io](https://registry.terraform.io) or [custom source addresses](https://developer.hashicorp.com/terraform/language/providers/requirements#source-addresses) specified in each template | [Custom source addresses](https://developer.hashicorp.com/terraform/language/providers/requirements#source-addresses) can be specified in each Coder template, or a custom registry/mirror can be used. More details below | | STUN | By default, Coder uses Google's public STUN server for direct workspace connections | STUN can be safely [disabled](../cli/coder_server#--derp-server-stun-addresses), users can still connect via [relayed connections](../networking.md#-geo-distribution). Alternatively, you can set a [custom DERP server](../cli/coder_server#--derp-server-stun-addresses) | | DERP | By default, Coder's built-in DERP relay can be used, or [Tailscale's public relays](../networking.md#relayed-connections). | By default, Coder's built-in DERP relay can be used, or [custom relays](../networking.md#custom-relays). | -| PostgreSQL | If no [PostgreSQL connection URL](../cli/coder_server#--postgres-url) is specified, Coder will download Postgres from [repo1.maven.org](https://repo1.maven.org). | An external database is required, you must specified a [PostgreSQL connection URL](../cli/coder_server#--postgres-url) | +| PostgreSQL | If no [PostgreSQL connection URL](../cli/coder_server#--postgres-url) is specified, Coder will download Postgres from [repo1.maven.org](https://repo1.maven.org) | An external database is required, you must specified a [PostgreSQL connection URL](../cli/coder_server#--postgres-url) | | Telemetry | Telemetry is on by default, and [can be disabled](../cli/coder_server#--telemetry) | Telemetry [can be disabled](../cli/coder_server#--telemetry) | ## Offline container images From 7df498cb887a281bfd72342ae34f738b46823f3d Mon Sep 17 00:00:00 2001 From: Ben Date: Thu, 2 Mar 2023 15:52:56 +0000 Subject: [PATCH 3/5] fix typo and add postgres --- docs/install/offline.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/install/offline.md b/docs/install/offline.md index 3de020b1d6068..e294be6c1a5a0 100644 --- a/docs/install/offline.md +++ b/docs/install/offline.md @@ -10,7 +10,7 @@ All Coder features are supported in offline / behind firewalls / in air-gapped e | Terraform registry | Coder templates will attempt to download providers from [registry.terraform.io](https://registry.terraform.io) or [custom source addresses](https://developer.hashicorp.com/terraform/language/providers/requirements#source-addresses) specified in each template | [Custom source addresses](https://developer.hashicorp.com/terraform/language/providers/requirements#source-addresses) can be specified in each Coder template, or a custom registry/mirror can be used. More details below | | STUN | By default, Coder uses Google's public STUN server for direct workspace connections | STUN can be safely [disabled](../cli/coder_server#--derp-server-stun-addresses), users can still connect via [relayed connections](../networking.md#-geo-distribution). Alternatively, you can set a [custom DERP server](../cli/coder_server#--derp-server-stun-addresses) | | DERP | By default, Coder's built-in DERP relay can be used, or [Tailscale's public relays](../networking.md#relayed-connections). | By default, Coder's built-in DERP relay can be used, or [custom relays](../networking.md#custom-relays). | -| PostgreSQL | If no [PostgreSQL connection URL](../cli/coder_server#--postgres-url) is specified, Coder will download Postgres from [repo1.maven.org](https://repo1.maven.org) | An external database is required, you must specified a [PostgreSQL connection URL](../cli/coder_server#--postgres-url) | +| PostgreSQL | If no [PostgreSQL connection URL](../cli/coder_server#--postgres-url) is specified, Coder will download Postgres from [repo1.maven.org](https://repo1.maven.org) | An external database is required, you must specify a [PostgreSQL connection URL](../cli/coder_server#--postgres-url) | | Telemetry | Telemetry is on by default, and [can be disabled](../cli/coder_server#--telemetry) | Telemetry [can be disabled](../cli/coder_server#--telemetry) | ## Offline container images @@ -167,5 +167,8 @@ coder: # Only use relayed connections - name: "CODER_DERP_SERVER_STUN_ADDRESSES" value: "" + # You must set up an external PostgreSQL database + - name: "CODER_PG_CONNECTION_URL" + value: "" # ... ``` From 155bfdca798ad1ab869697f1d71153312b2dfa5e Mon Sep 17 00:00:00 2001 From: Ben Date: Thu, 2 Mar 2023 19:02:26 +0000 Subject: [PATCH 4/5] mention update check --- docs/install/offline.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/install/offline.md b/docs/install/offline.md index e294be6c1a5a0..3a79e778fc5d8 100644 --- a/docs/install/offline.md +++ b/docs/install/offline.md @@ -12,6 +12,7 @@ All Coder features are supported in offline / behind firewalls / in air-gapped e | DERP | By default, Coder's built-in DERP relay can be used, or [Tailscale's public relays](../networking.md#relayed-connections). | By default, Coder's built-in DERP relay can be used, or [custom relays](../networking.md#custom-relays). | | PostgreSQL | If no [PostgreSQL connection URL](../cli/coder_server#--postgres-url) is specified, Coder will download Postgres from [repo1.maven.org](https://repo1.maven.org) | An external database is required, you must specify a [PostgreSQL connection URL](../cli/coder_server#--postgres-url) | | Telemetry | Telemetry is on by default, and [can be disabled](../cli/coder_server#--telemetry) | Telemetry [can be disabled](../cli/coder_server#--telemetry) | +| Update check | By default, Coder checks for updates from [GitHub releases](https:/github.com/coder/coder/releases) | Update checks [can be disabled](../cli/coder_server#--update-check) | ## Offline container images From 3121ab26bc70aafc72c0ecd45190d5d51412a257 Mon Sep 17 00:00:00 2001 From: Ben Date: Thu, 2 Mar 2023 20:05:15 +0000 Subject: [PATCH 5/5] disable update checks --- docs/install/offline.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/install/offline.md b/docs/install/offline.md index 3a79e778fc5d8..cf1fe1ac0cabe 100644 --- a/docs/install/offline.md +++ b/docs/install/offline.md @@ -142,8 +142,9 @@ services: - ./plugins:/opt/terraform/plugins # ... environment: - CODER_TELEMETRY_ENABLE: false # disable telemetry - CODER_DERP_SERVER_STUN_ADDRESSES: "" # only use relayed connections + CODER_TELEMETRY_ENABLE: "false" # Disable telemetry + CODER_DERP_SERVER_STUN_ADDRESSES: "" # Only use relayed connections + CODER_UPDATE_CHECK: "false" # Disable automatic update checks database: image: registry.example.com/postgres:13 # ... @@ -165,6 +166,9 @@ coder: # Disable telemetry - name: "CODER_TELEMETRY_ENABLE" value: "false" + # Disable automatic update checks + - name: "CODER_UPDATE_CHECK" + value: "false" # Only use relayed connections - name: "CODER_DERP_SERVER_STUN_ADDRESSES" value: ""