selfhosted
/
coder
mirror of https://github.com/coder/coder.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: resolve README 404s (#7822)

This commit is contained in:
Eric Paulsen 2023-06-02 16:56:06 -04:00 committed by GitHub
parent edccd2de73
commit 6715cb6a95
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
23 changed files with 457 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/README.md
View File

@ -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)

2
docs/about/architecture.md
View File

@ -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

2
docs/admin/configure.md
View File

@ -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

4
docs/admin/high-availability.md
View File

@ -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)

2
docs/ides.md
View File

@ -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

2
docs/install/binary.md
View File

@ -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)

2
docs/install/database.md
View File

@ -84,4 +84,4 @@ psql -U coder -c '\dn'
## Next steps
- [Configuring Coder](../admin/configure.md)
- [Templates](../templates/README.md)
- [Templates](../templates/index.md)

4
docs/install/docker.md
View File

@ -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)

2
docs/install/install.sh.md
View File

@ -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)

4
docs/install/kubernetes.md
View File

@ -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)

18
docs/install/offline.md
View File

@ -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

2
docs/install/packages.md
View File

@ -38,4 +38,4 @@ sudo systemctl restart coder
## Next steps
- [Configuring Coder](../admin/configure.md)
- [Templates](../templates/README.md)
- [Templates](../templates/index.md)

2
docs/install/windows.md
View File

@ -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)

4
docs/manifest.json
View File

@ -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": [
{

0
docs/networking/README.md → docs/networking/index.md
View File

2
docs/platforms/aws.md
View File

@ -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)

2
docs/platforms/azure.md
View File

@ -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)

4
docs/platforms/docker.md
View File

@ -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)

2
docs/platforms/google-cloud-platform.md
View File

@ -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)

2
docs/platforms/other.md
View File

@ -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)

421
docs/templates/index.md vendored Normal file
View File

@ -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 <your-api-key> 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 <template-name>/main.tf
# add the template to Coder deployment
coder templates create <template-name>
```
> 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 = <<EOT
#!/bin/bash
# Install code-server 4.8.3 under /tmp/code-server using the "standalone" installation
# that does not require root permissions. Note that /tmp may be mounted in tmpfs which
# can lead to increased RAM usage. To avoid this, you can pre-install code-server inside
# the Docker image or VM image.
curl -fsSL https://code-server.dev/install.sh | sh -s -- --method=standalone --prefix=/tmp/code-server --version 4.8.3
# The & prevents the startup_script from blocking so the next commands can run.
# The stdout and stderr of code-server is redirected to /tmp/code-server.log.
/tmp/code-server/bin/code-server --auth none --port 13337 >/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 <template-name> --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 <template-name> 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 <template-name>
```
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 <template-name>
```
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)

2
docs/templates/resource-persistence.md vendored
View File

@ -87,4 +87,4 @@ resource "docker_volume" "home_volume" {
## Up next
- [Templates](../templates/README.md)
- [Templates](../templates/index.md)

4
docs/workspaces.md
View File

@ -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