docs: Document agent readiness issues (startup script) (coder#5877)

mafredri · web-flow · commit 90c4d5d28abe · 2023-01-27T22:23:47.000+02:00
Refs: coder#5749, coder#5851
diff --git a/docs/templates.md b/docs/templates.md
@@ -375,25 +375,61 @@ customize them however you like.
 ## Troubleshooting templates
 
 Occasionally, you may run into scenarios where a workspace is created, but the
-agent is not connected. This means the agent or [init script](https://github.com/coder/coder/tree/main/provisionersdk/scripts)
+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 [agent] to connect...
+⢄⡱ Waiting for connection from [agent]...
 ```
 
 While troubleshooting steps vary by resource, here are some general best
 practices:
 
-- Ensure the resource has `curl` installed
+- 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`
 
+### 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
