docs(templates): Document startup_script_behavior in-depth

mafredri · mafredri · commit ec07da698158 · 2023-06-05T16:34:46.000Z
Fixes #7759
diff --git a/docs/templates/index.md b/docs/templates/index.md
@@ -145,12 +145,14 @@ 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
+#### `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.
 
+**Note:** By default, the startup script is executed in the background allowing users to access the workspace before the script completes. If you want to change this, see `startup_script_behavior` below.
+
 ```hcl
 resource "coder_agent" "coder" {
   os   = "linux"
@@ -163,10 +165,12 @@ resource "coder_agent" "coder" {
 # 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.
+echo "Installing code-server..."
 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.
+echo "Starting code-server..."
 /tmp/code-server/bin/code-server --auth none --port 13337 >/tmp/code-server.log 2>&1 &
 
 # var.repo and var.dotfiles_uri is specified
@@ -175,15 +179,56 @@ curl -fsSL https://code-server.dev/install.sh | sh -s -- --method=standalone --p
 
 # clone repo
 ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts
+echo "Cloning ${var.repo}..."
 git clone --progress git@github.com:${var.repo}
 
 # use coder CLI to clone and install dotfiles
+echo "Cloning dotfiles..."
 coder dotfiles -y ${var.dotfiles_uri}
 
   EOT
 }
 ```
 
+We recommend that startup scripts always have an end, meaning that long running
+processes should be run in the background. This is usually achieved by adding
+`&` to the end of the command. For example, `sleep 10 &` will run the command in
+the background and allow the startup script to complete.
+
+If a backgrounded command (`&`) writes to stdout or stderr, the startup script
+will not complete until the command completes or closes the file descriptors.
+To avoid this, you can redirect the stdout and stderr to a file. For example,
+`sleep 10 >/dev/null 2>&1 &` will redirect the stdout and stderr to `/dev/null`
+(discard) and run the command in the background.
+
+PS. Notice how each step starts with `echo "..."` to provide feedback to the user
+about what is happening? This is especially useful when the startup script
+behavior is set to blocking because the user will be informed about why they're
+waiting to access their workspace.
+
+#### `startup_script_behavior`
+
+Use the Coder agent's `startup_script_behavior` to change the behavior between
+`blocking` and `non-blocking` (default). The blocking behavior is recommended
+for most use cases because it allows the startup script to complete before the
+user accesses the workspace. For example, let's say you want to check out a very
+large repo in the startup script. If the startup script is non-blocking, the
+user may log in via SSH or open the IDE before the repo is fully checked out.
+This can lead to a poor user experience.
+
+Whichever behavior is enabled, the user can still choose to override it by
+specifying the appropriate flags (or environment variables) in the CLI when
+connecting to the workspace. For example, `coder ssh --no-wait` will connect to
+the workspace without waiting for the startup script to complete.
+
+```hcl
+resource "coder_agent" "coder" {
+  os   = "linux"
+  arch = "amd64"
+  startup_script_behavior = "blocking"
+  startup_script = "echo 'Starting...'"
+```
+
 ### Start/stop
 
 [Learn about resource persistence in Coder](./resource-persistence.md)
@@ -372,6 +417,18 @@ practices:
   - 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)
 
+### Startup script in progress, incomplete workspace
+
+WIP
+
+### Startup script in progress, session before completion
+
+WIP
+
+### Startup script error
+
+WIP
+
 ### 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.
