diff --git a/docs/README.md b/docs/README.md index af6521cae1..b2e55d1f07 100644 --- a/docs/README.md +++ b/docs/README.md @@ -28,7 +28,7 @@ product. Coder workspaces don't stop at compute. You can add storage buckets, secrets, sidecars and whatever else Terraform lets you dream up. -[Learn more about managing infrastructure.](./templates/README.md) +[Learn more about managing infrastructure.](./templates/index.md) ## IDE Support @@ -104,5 +104,5 @@ Azure, Google Cloud, Kubernetes, and more. ## Up next -- Learn about [Templates](./templates/README.md) +- Learn about [Templates](./templates/index.md) - [Install Coder](./install/install.sh.md) diff --git a/docs/about/architecture.md b/docs/about/architecture.md index 57f18965e7..45ef36b99b 100644 --- a/docs/about/architecture.md +++ b/docs/about/architecture.md @@ -40,7 +40,7 @@ It offers the following services along with much more: - Liveness checks - `startup_script` automation -Templates are responsible for [creating and running agents](../templates/README.md#coder-agent) within workspaces. +Templates are responsible for [creating and running agents](../templates/index.md#coder-agent) within workspaces. ## Service Bundling diff --git a/docs/admin/configure.md b/docs/admin/configure.md index 6b3aa12c88..ca8517342a 100644 --- a/docs/admin/configure.md +++ b/docs/admin/configure.md @@ -35,7 +35,7 @@ coder server ## Wildcard access URL `CODER_WILDCARD_ACCESS_URL` is necessary for [port forwarding](../networking/port-forwarding.md#dashboard) -via the dashboard or running [coder_apps](../templates/README.md#coder-apps) on an absolute path. Set this to a wildcard +via the dashboard or running [coder_apps](../templates/index.md#coder-apps) on an absolute path. Set this to a wildcard subdomain that resolves to Coder (e.g. `*.coder.example.com`). If you are providing TLS certificates directly to the Coder server, either diff --git a/docs/admin/high-availability.md b/docs/admin/high-availability.md index 037a758298..430c0c8dbb 100644 --- a/docs/admin/high-availability.md +++ b/docs/admin/high-availability.md @@ -21,7 +21,7 @@ to the same Postgres endpoint. HA brings one configuration variable to set in each Coder node: `CODER_DERP_SERVER_RELAY_URL`. The HA nodes use these URLs to communicate with each other. Inter-node communication is only required while using the -embedded relay (default). If you're using [custom relays](../networking/README.md#custom-relays), Coder ignores `CODER_DERP_SERVER_RELAY_URL` since Postgres is the sole rendezvous for the Coder nodes. +embedded relay (default). If you're using [custom relays](../networking/index.md#custom-relays), Coder ignores `CODER_DERP_SERVER_RELAY_URL` since Postgres is the sole rendezvous for the Coder nodes. `CODER_DERP_SERVER_RELAY_URL` will never be `CODER_ACCESS_URL` because `CODER_ACCESS_URL` is a load balancer to all Coder nodes. @@ -57,6 +57,6 @@ Then, increase the number of pods. ## Up next -- [Networking](../networking/README.md) +- [Networking](../networking/index.md) - [Kubernetes](../install/kubernetes.md) - [Enterprise](../enterprise.md) diff --git a/docs/ides.md b/docs/ides.md index 05d7065c13..6cf26bb441 100644 --- a/docs/ides.md +++ b/docs/ides.md @@ -22,7 +22,7 @@ Click `VS Code Desktop` in the dashboard to one-click enter a workspace. This au ![Demo](https://github.com/coder/vscode-coder/raw/main/demo.gif?raw=true) -> The `VS Code Desktop` button can be hidden by enabling [Browser-only connections](./networking/README.md#Browser-only). +> The `VS Code Desktop` button can be hidden by enabling [Browser-only connections](./networking/index.md#Browser-only). ### Manual Installation diff --git a/docs/install/binary.md b/docs/install/binary.md index a77b7eb4a1..33e2bbc1c5 100644 --- a/docs/install/binary.md +++ b/docs/install/binary.md @@ -30,4 +30,4 @@ Coder publishes self-contained .zip and .tar.gz archives in [GitHub releases](ht ## Next steps - [Configuring Coder](../admin/configure.md) -- [Templates](../templates/README.md) +- [Templates](../templates/index.md) diff --git a/docs/install/database.md b/docs/install/database.md index 4c3b1ef45e..e88daa3b0e 100644 --- a/docs/install/database.md +++ b/docs/install/database.md @@ -84,4 +84,4 @@ psql -U coder -c '\dn' ## Next steps - [Configuring Coder](../admin/configure.md) -- [Templates](../templates/README.md) +- [Templates](../templates/index.md) diff --git a/docs/install/docker.md b/docs/install/docker.md index 492f78186a..038146b300 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -88,7 +88,7 @@ an PostgreSQL container and volume. ### Docker-based workspace is stuck in "Connecting..." -Ensure you have an externally-reachable `CODER_ACCESS_URL` set. See [troubleshooting templates](../templates/README.md#troubleshooting-templates) for more steps. +Ensure you have an externally-reachable `CODER_ACCESS_URL` set. See [troubleshooting templates](../templates/index.md#troubleshooting-templates) for more steps. ### Permission denied while trying to connect to the Docker daemon socket @@ -97,4 +97,4 @@ See Docker's official documentation to [Manage Docker as a non-root user](https: ## Next steps - [Configuring Coder](../admin/configure.md) -- [Templates](../templates/README.md) +- [Templates](../templates/index.md) diff --git a/docs/install/install.sh.md b/docs/install/install.sh.md index 0a1129f6b2..4acd34288e 100644 --- a/docs/install/install.sh.md +++ b/docs/install/install.sh.md @@ -25,4 +25,4 @@ By default, the Coder server runs on `http://127.0.0.1:3000` and uses a [public ## Next steps - [Configuring Coder](../admin/configure.md) -- [Templates](../templates/README.md) +- [Templates](../templates/index.md) diff --git a/docs/install/kubernetes.md b/docs/install/kubernetes.md index 62b3846955..662ed11e4d 100644 --- a/docs/install/kubernetes.md +++ b/docs/install/kubernetes.md @@ -176,9 +176,9 @@ Cloud's log management system if you are using managed Kubernetes. Ensure you have an externally-reachable `CODER_ACCESS_URL` set in your helm chart. If you do not have a domain set up, this should be the IP address of Coder's LoadBalancer (`kubectl get svc -n coder`). -See [troubleshooting templates](../templates/README.md#troubleshooting-templates) for more steps. +See [troubleshooting templates](../templates/index.md#troubleshooting-templates) for more steps. ## Next steps - [Configuring Coder](../admin/configure.md) -- [Templates](../templates/README.md) +- [Templates](../templates/index.md) diff --git a/docs/install/offline.md b/docs/install/offline.md index fb7cf6a06d..f7573b5c99 100644 --- a/docs/install/offline.md +++ b/docs/install/offline.md @@ -4,15 +4,15 @@ All Coder features are supported in offline / behind firewalls / in air-gapped e > 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/server.md#--derp-server-stun-addresses), users can still connect via [relayed connections](../networking/README.md#-geo-distribution). Alternatively, you can set a [custom DERP server](../cli/server.md#--derp-server-stun-addresses) | -| DERP | By default, Coder's built-in DERP relay can be used, or [Tailscale's public relays](../networking/README.md#relayed-connections). | By default, Coder's built-in DERP relay can be used, or [custom relays](../networking/README.md#custom-relays). | -| PostgreSQL | If no [PostgreSQL connection URL](../cli/server.md#--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/server.md#--postgres-url) | -| Telemetry | Telemetry is on by default, and [can be disabled](../cli/server.md#--telemetry) | Telemetry [can be disabled](../cli/server.md#--telemetry) | -| Update check | By default, Coder checks for updates from [GitHub releases](https:/github.com/coder/coder/releases) | Update checks [can be disabled](../cli/server.md#--update-check) | +| | 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/server.md#--derp-server-stun-addresses), users can still connect via [relayed connections](../networking/index.md#-geo-distribution). Alternatively, you can set a [custom DERP server](../cli/server.md#--derp-server-stun-addresses) | +| DERP | By default, Coder's built-in DERP relay can be used, or [Tailscale's public relays](../networking/index.md#relayed-connections). | By default, Coder's built-in DERP relay can be used, or [custom relays](../networking/index.md#custom-relays). | +| PostgreSQL | If no [PostgreSQL connection URL](../cli/server.md#--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/server.md#--postgres-url) | +| Telemetry | Telemetry is on by default, and [can be disabled](../cli/server.md#--telemetry) | Telemetry [can be disabled](../cli/server.md#--telemetry) | +| Update check | By default, Coder checks for updates from [GitHub releases](https:/github.com/coder/coder/releases) | Update checks [can be disabled](../cli/server.md#--update-check) | ## Offline container images diff --git a/docs/install/packages.md b/docs/install/packages.md index 3f9479eaf9..c17431c576 100644 --- a/docs/install/packages.md +++ b/docs/install/packages.md @@ -38,4 +38,4 @@ sudo systemctl restart coder ## Next steps - [Configuring Coder](../admin/configure.md) -- [Templates](../templates/README.md) +- [Templates](../templates/index.md) diff --git a/docs/install/windows.md b/docs/install/windows.md index 09dec83093..86de80da77 100644 --- a/docs/install/windows.md +++ b/docs/install/windows.md @@ -31,4 +31,4 @@ Use the Windows installer to download the CLI and add Coder to `PATH`. Alternati ## Next steps - [Configuring Coder](../admin/configure.md) -- [Templates](../templates/README.md) +- [Templates](../templates/index.md) diff --git a/docs/manifest.json b/docs/manifest.json index c4616ff960..47ddd9d7f9 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -125,7 +125,7 @@ { "title": "Templates", "description": "Learn about templates, which define the infrastructure underlying workspaces", - "path": "./templates/README.md", + "path": "./templates/index.md", "icon_path": "./images/icons/picture.svg", "children": [ { @@ -216,7 +216,7 @@ { "title": "Networking", "description": "Learn about networking in Coder", - "path": "./networking/README.md", + "path": "./networking/index.md", "icon_path": "./images/icons/networking.svg", "children": [ { diff --git a/docs/networking/README.md b/docs/networking/index.md similarity index 100% rename from docs/networking/README.md rename to docs/networking/index.md diff --git a/docs/platforms/aws.md b/docs/platforms/aws.md index 58585936d9..c74f65b7b2 100644 --- a/docs/platforms/aws.md +++ b/docs/platforms/aws.md @@ -58,6 +58,6 @@ From there, you can import the AWS starter template in the dashboard and begin c ## Next steps - [IDEs with Coder](../ides.md) -- [Writing custom templates for Coder](../templates/README.md) +- [Writing custom templates for Coder](../templates/index.md) - [Configure the Coder server](../admin/configure.md) - [Use your own domain + TLS](../admin/configure.md#tls--reverse-proxy) diff --git a/docs/platforms/azure.md b/docs/platforms/azure.md index 061d070452..318b1d8b4c 100644 --- a/docs/platforms/azure.md +++ b/docs/platforms/azure.md @@ -105,5 +105,5 @@ Congrats! You can now navigate to your Coder dashboard and use this Linux on Azu ## Next Steps - [Port-forward](../networking/port-forwarding.md) -- [Learn more about template configuration](../templates/README.md) +- [Learn more about template configuration](../templates/index.md) - [Configure more IDEs](../ides/web-ides.md) diff --git a/docs/platforms/docker.md b/docs/platforms/docker.md index 7f97fbca4a..0ab0397957 100644 --- a/docs/platforms/docker.md +++ b/docs/platforms/docker.md @@ -74,7 +74,7 @@ Coder with Docker has the following advantages: ### Docker-based workspace is stuck in "Connecting..." -Ensure you have an externally-reachable `CODER_ACCESS_URL` set. See [troubleshooting templates](../templates/README.md#Troubleshooting) for more steps. +Ensure you have an externally-reachable `CODER_ACCESS_URL` set. See [troubleshooting templates](../templates/index.md#Troubleshooting) for more steps. ### Permission denied while trying to connect to the Docker daemon socket @@ -83,5 +83,5 @@ See Docker's official documentation to [Manage Docker as a non-root user](https: ## Next Steps - [Port-forward](../networking/port-forwarding.md) -- [Learn more about template configuration](../templates/README.md) +- [Learn more about template configuration](../templates/index.md) - [Configure more IDEs](../ides/web-ides.md) diff --git a/docs/platforms/google-cloud-platform.md b/docs/platforms/google-cloud-platform.md index f13935f683..8f20820c65 100644 --- a/docs/platforms/google-cloud-platform.md +++ b/docs/platforms/google-cloud-platform.md @@ -110,5 +110,5 @@ Congrats! You can now create new Linux-based workspaces that use Google Cloud Pl ## Next Steps -- [Learn more about template configuration](../templates/README.md) +- [Learn more about template configuration](../templates/index.md) - [Configure more IDEs](../ides/web-ides.md) diff --git a/docs/platforms/other.md b/docs/platforms/other.md index 0422384bd4..7cccea0968 100644 --- a/docs/platforms/other.md +++ b/docs/platforms/other.md @@ -8,4 +8,4 @@ The following resources may help as you're deploying Coder. - [Run Coder as a system service](../install/packages.md) - [Deploy Coder offline](../install/offline.md) - [Supported resources (Terraform registry)](https://registry.terraform.io) -- [Writing custom templates](../templates/README.md) +- [Writing custom templates](../templates/index.md) diff --git a/docs/templates/index.md b/docs/templates/index.md new file mode 100644 index 0000000000..fc338650b8 --- /dev/null +++ b/docs/templates/index.md @@ -0,0 +1,421 @@ +# Templates + +Templates are written in [Terraform](https://www.terraform.io/) and describe the +infrastructure for workspaces (e.g., docker_container, aws_instance, +kubernetes_pod). + +In most cases, a small group of users (team leads or Coder administrators) [have permissions](../admin/users.md#roles) to create and manage templates. Then, other +users provision their [workspaces](../workspaces.md) from templates using the UI +or CLI. + +## Get the CLI + +The CLI and the server are the same binary. We did this to encourage virality so +individuals can start their own Coder deployments. + +From your local machine, download the CLI for your operating system from the +[releases](https://github.com/coder/coder/releases/latest) or run: + +```console +curl -fsSL https://coder.com/install.sh | sh +``` + +To see the sub-commands for managing templates, run: + +```console +coder templates --help +``` + +## Login to your Coder Deployment + +Before you can create templates, you must first login to your Coder deployment +with the CLI. + +```console +coder login https://coder.example.com # aka the URL to your coder instance +``` + +This will open a browser and ask you to authenticate to your Coder deployment, +returning an API Key. + +> Make a note of the API Key. You can re-use the API Key in future CLI logins or +> sessions. + +```console +coder --token login https://coder.example.com/ # aka the URL to your coder instance +``` + +## Add a template + +Before users can create workspaces, you'll need at least one template in Coder. + +```sh +# create a local directory to store templates +mkdir -p $HOME/coder/templates +cd $HOME/coder/templates + +# start from an example +coder templates init + +# optional: modify the template +vim /main.tf + +# add the template to Coder deployment +coder templates create +``` + +> See the documentation and source code for each example as well as community +> templates in the +> [examples/](https://github.com/coder/coder/tree/main/examples/templates) +> directory in the repo. + +## Configure Max Workspace Autostop + +To control cost, specify a maximum time to live flag for a template in hours or +minutes. + +```sh +coder templates create my-template --default-ttl 4h +``` + +## Customize templates + +Example templates are not designed to support every use (e.g +[examples/aws-linux](https://github.com/coder/coder/tree/main/examples/templates/aws-linux) +does not support custom VPCs). You can add these features by editing the +Terraform code once you run `coder templates init` (new) or `coder templates pull` (existing). + +Refer to the following resources to build your own templates: + +- Terraform: [Documentation](https://developer.hashicorp.com/terraform/docs) and + [Registry](https://registry.terraform.io) +- Common [concepts in templates](#concepts-in-templates) and [Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs) +- [Coder example templates](https://github.com/coder/coder/tree/main/examples/templates) code + +## Concepts in templates + +While templates are written with standard Terraform, the [Coder Terraform Provider](https://registry.terraform.io/providers/coder/coder/latest/docs) is used to define the workspace lifecycle and establish a connection from resources +to Coder. + +Below is an overview of some key concepts in templates (and workspaces). For all +template options, reference [Coder Terraform provider docs](https://registry.terraform.io/providers/coder/coder/latest/docs). + +### Resource + +Resources in Coder are simply [Terraform resources](https://www.terraform.io/language/resources). +If a Coder agent is attached to a resource, users can connect directly to the +resource over SSH or web apps. + +### Coder agent + +Once a Coder workspace is created, the Coder agent establishes a connection +between a resource (docker_container) and Coder, so that a user can connect to +their workspace from the web UI or CLI. A template can have multiple agents to +allow users to connect to multiple resources in their workspace. + +> Resources must download and start the Coder agent binary to connect to Coder. +> This means the resource must be able to reach your Coder URL. + +```hcl +data "coder_workspace" "me" { +} + +resource "coder_agent" "pod1" { + os = "linux" + arch = "amd64" +} + +resource "kubernetes_pod" "pod1" { + spec { + ... + container { + command = ["sh", "-c", coder_agent.pod1.init_script] + env { + name = "CODER_AGENT_TOKEN" + value = coder_agent.dev.token + } + } + } +} +``` + +The `coder_agent` resource can be configured with additional arguments. For example, +you can use the `env` property to set environment variables that will be inherited +by all child processes of the agent, including SSH sessions. See the +[Coder Terraform Provider documentation](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent) +for the full list of supported arguments for the `coder_agent`. + +#### startup_script + +Use the Coder agent's `startup_script` to run additional commands like +installing IDEs, [cloning dotfiles](../dotfiles.md#templates), and cloning +project repos. + +```hcl +resource "coder_agent" "coder" { + os = "linux" + arch = "amd64" + dir = "/home/coder" + startup_script = </tmp/code-server.log 2>&1 & + +# var.repo and var.dotfiles_uri is specified +# elsewhere in the Terraform code as input +# variables. + +# clone repo +ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts +git clone --progress git@github.com:${var.repo} + +# use coder CLI to clone and install dotfiles +coder dotfiles -y ${var.dotfiles_uri} + + EOT +} +``` + +### Start/stop + +[Learn about resource persistence in Coder](./resource-persistence.md) + +Coder workspaces can be started/stopped. This is often used to save on cloud +costs or enforce ephemeral workflows. When a workspace is started or stopped, +the Coder server runs an additional [terraform apply](https://www.terraform.io/cli/commands/apply), +informing the Coder provider that the workspace has a new transition state. + +This template sample has one persistent resource (docker volume) and one +ephemeral resource (docker container). + +```hcl +data "coder_workspace" "me" { +} + +resource "docker_volume" "home_volume" { + # persistent resource (remains a workspace is stopped) + count = 1 + name = "coder-${data.coder_workspace.me.id}-home" + lifecycle { + ignore_changes = all + } +} + +resource "docker_container" "workspace" { + # ephemeral resource (deleted when workspace is stopped, created when started) + count = data.coder_workspace.me.start_count # 0 (stopped), 1 (started) + volumes { + container_path = "/home/coder/" + volume_name = docker_volume.home_volume.name + read_only = false + } + # ... other config +} +``` + +#### Using updated images when rebuilding a workspace + +To ensure that Coder uses an updated image when rebuilding a workspace, we +suggest that admins update the tag in the template (e.g., `my-image:v0.4.2` -> +`my-image:v0.4.3`) or digest (`my-image@sha256:[digest]` -> +`my-image@sha256:[new_digest]`). + +Alternatively, if you're willing to wait for longer start times from Coder, you +can set the `imagePullPolicy` to `Always` in your Terraform template; when set, +Coder will check `image:tag` on every build and update if necessary: + +```tf +resource "kubernetes_pod" "podName" { + spec { + container { + image_pull_policy = "Always" + } + } +} +``` + +### Edit templates + +You can edit a template using the coder CLI or the UI. Only [template admins and +owners](../admin/users.md) can edit a template. + +Using the UI, navigate to the template page, click on the menu, and select "Edit files". In the template editor, you create, edit and remove files. Before publishing a new template version, you can test your modifications by clicking the "Build template" button. Newly published template versions automatically become the default version selection when creating a workspace. + +> **Tip**: Even without publishing a version as active, you can still use it to create a workspace before making it the default for everybody in your organization. This may help you debug new changes without impacting others. + +Using the CLI, login to Coder and run the following command to edit a single +template: + +```console +coder templates edit --description "This is my template" +``` + +Review editable template properties by running `coder templates edit -h`. + +Alternatively, you can pull down the template as a tape archive (`.tar`) to your +current directory: + +```console +coder templates pull file.tar +``` + +Then, extract it by running: + +```sh +tar -xf file.tar +``` + +Make the changes to your template then run this command from the root of the +template folder: + +```console +coder templates push +``` + +Your updated template will now be available. Outdated workspaces will have a +prompt in the dashboard to update. + +### Delete templates + +You can delete a template using both the coder CLI and UI. Only [template admins +and owners](../admin/users.md) can delete a template, and the template must not +have any running workspaces associated to it. + +Using the CLI, login to Coder and run the following command to delete a +template: + +```console +coder templates delete +``` + +In the UI, navigate to the template you want to delete, and select the dropdown +in the right-hand corner of the page to delete the template. + +![delete-template](../images/delete-template.png) + +#### Delete workspaces + +When a workspace is deleted, the Coder server essentially runs a [terraform +destroy](https://www.terraform.io/cli/commands/destroy) to remove all resources +associated with the workspace. + +> Terraform's +> [prevent-destroy](https://www.terraform.io/language/meta-arguments/lifecycle#prevent_destroy) +> and +> [ignore-changes](https://www.terraform.io/language/meta-arguments/lifecycle#ignore_changes) +> meta-arguments can be used to prevent accidental data loss. + +### Coder apps + +By default, all templates allow developers to connect over SSH and a web +terminal. See [Configuring Web IDEs](../ides/web-ides.md) to learn how to give +users access to additional web applications. + +### Data source + +When a workspace is being started or stopped, the `coder_workspace` data source +provides some useful parameters. See the [Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace) for more information. + +For example, the [Docker quick-start template](https://github.com/coder/coder/tree/main/examples/templates/docker) +sets a few environment variables based on the username and email address of the +workspace's owner, so that you can make Git commits immediately without any +manual configuration: + +```tf +resource "coder_agent" "main" { + # ... + env = { + GIT_AUTHOR_NAME = "${data.coder_workspace.me.owner}" + GIT_COMMITTER_NAME = "${data.coder_workspace.me.owner}" + GIT_AUTHOR_EMAIL = "${data.coder_workspace.me.owner_email}" + GIT_COMMITTER_EMAIL = "${data.coder_workspace.me.owner_email}" + } +} +``` + +You can add these environment variable definitions to your own templates, or +customize them however you like. + +## Troubleshooting templates + +Occasionally, you may run into scenarios where a workspace is created, but the +agent is either not connected or the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) +has failed or timed out. + +### Agent connection issues + +If the agent is not connected, it means the agent or [init script](https://github.com/coder/coder/tree/main/provisionersdk/scripts) +has failed on the resource. + +```console +$ coder ssh myworkspace +⢄⡱ Waiting for connection from [agent]... +``` + +While troubleshooting steps vary by resource, here are some general best +practices: + +- Ensure the resource has `curl` installed (alternatively, `wget` or `busybox`) +- Ensure the resource can `curl` your Coder [access + URL](../admin/configure.md#access-url) +- Manually connect to the resource and check the agent logs (e.g., `kubectl exec`, `docker exec` or AWS console) + - The Coder agent logs are typically stored in `/tmp/coder-agent.log` + - The Coder agent startup script logs are typically stored in `/tmp/coder-startup-script.log` + - The Coder agent shutdown script logs are typically stored in `/tmp/coder-shutdown-script.log` +- This can also happen if the websockets are not being forwarded correctly when running Coder behind a reverse proxy. [Read our reverse-proxy docs](https://coder.com/docs/v2/latest/admin/configure#tls--reverse-proxy) + +### Agent does not become ready + +If the agent does not become ready, it means the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) is still running or has exited with a non-zero status. This also means the [login before ready](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#login_before_ready) option hasn't been set to true. + +```console +$ coder ssh myworkspace +⢄⡱ Waiting for [agent] to become ready... +``` + +To troubleshoot readiness issues, check the agent logs as suggested above. You can connect to the workspace using `coder ssh` with the `--no-wait` flag. Please note that while this makes login possible, the workspace may be in an incomplete state. + +```console +$ coder ssh myworkspace --no-wait + + > The workspace is taking longer than expected to get + ready, the agent startup script is still executing. + See troubleshooting instructions at: [...] + +user@myworkspace $ +``` + +If the startup script is expected to take a long time, you can try raising the timeout defined in the template: + +```tf +resource "coder_agent" "main" { + # ... + login_before_ready = false + startup_script_timeout = 1800 # 30 minutes in seconds. +} +``` + +## Template permissions (enterprise) + +Template permissions can be used to give users and groups access to specific +templates. [Learn more about RBAC](../admin/rbac.md) to learn how to manage + +## Community Templates + +You can see a list of community templates by our users +[here](https://github.com/coder/coder/blob/main/examples/templates/community-templates.md). + +## Next Steps + +- Learn about [Authentication & Secrets](./authentication.md) +- Learn about [Change Management](./change-management.md) +- Learn about [Resource Metadata](./resource-metadata.md) +- Learn about [Workspaces](../workspaces.md) diff --git a/docs/templates/resource-persistence.md b/docs/templates/resource-persistence.md index 0ac9765702..97233460f3 100644 --- a/docs/templates/resource-persistence.md +++ b/docs/templates/resource-persistence.md @@ -87,4 +87,4 @@ resource "docker_volume" "home_volume" { ## Up next -- [Templates](../templates/README.md) +- [Templates](../templates/index.md) diff --git a/docs/workspaces.md b/docs/workspaces.md index f61f21c6a3..d2d11e88f8 100644 --- a/docs/workspaces.md +++ b/docs/workspaces.md @@ -5,7 +5,7 @@ for software development. ## Create workspaces -Each Coder user has their own workspaces created from [shared templates](./templates/README.md): +Each Coder user has their own workspaces created from [shared templates](./templates/index.md): ```console # create a workspace from the template; specify any variables @@ -22,7 +22,7 @@ Coder [supports multiple IDEs](./ides.md) for use with your workspaces. ## Workspace lifecycle Workspaces in Coder are started and stopped, often based on whether there was -any activity or if there was a [template update](./templates/README.md#Start/stop) available. +any activity or if there was a [template update](./templates/index.md#Start/stop) available. Resources are often destroyed and re-created when a workspace is restarted, though the exact behavior depends on the template. For more