Skip to content

docs(templates): document startup_script_behavior in-depth #7857

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jun 7, 2023
Merged

docs(templates): document startup_script_behavior in-depth #7857

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
50b4a64
docs(templates): Document `startup_script_behavior` in-depth
mafredri Jun 5, 2023
048a988
Improve unable to access section
mafredri Jun 6, 2023
9eb85f3
Markdown link
mafredri Jun 6, 2023
0eac1c3
Update docs/templates/index.md
mafredri Jun 6, 2023
6560e08
Update docs/templates/index.md
mafredri Jun 6, 2023
d59549f
Improvements based on PR comments
mafredri Jun 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Improvements based on PR comments
  • Loading branch information
@mafredri
mafredri committed Jun 6, 2023
commit d59549f79f1ed407ace9d3c1dc4624703e62cded
8 changes: 5 additions & 3 deletions docs/templates/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -198,9 +198,9 @@ coder dotfiles -y "$DOTFILES_URI"
}
```

The startup script can contain important steps that must be executed successfully so that the workspace is in a usable state, for this reason we recommend using `set -e` (exit on error) at the top and `|| true` (allow command to fail) to ensure the user is notified when something goes wrong. These are not shown in the example above because, while useful, they need to be used with care.
The startup script can contain important steps that must be executed successfully so that the workspace is in a usable state, for this reason we recommend using `set -e` (exit on error) at the top and `|| true` (allow command to fail) to ensure the user is notified when something goes wrong. These are not shown in the example above because, while useful, they need to be used with care. For more assurance, you can utilize [shellcheck](https://www.shellcheck.net) to find bugs in the script and employ [`set -euo pipefail`](https://wizardzines.com/comics/bash-errors/) to exit on error, unset variables, and fail on pipe errors.

We also 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.
We also recommend that startup scripts do not run forever. Long-running processes, like code-server, 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.

> **Note:** 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.

Expand Down Expand Up @@ -467,7 +467,9 @@ if [ $status -ne 0 ]; then
fi
```

This script tells us what command is being run and what the exit status is. If the exit status is non-zero, it means the command failed. Note that here we don't need `set -x` because we're manually echoing the commands which protects against sensitive information being shown in the log. We also don't need `set -e` because we're manually checking the exit status and exiting if it's non-zero.
> **Note:** We don't use `set -x` here because we're manually echoing the commands. This protects against sensitive information being shown in the log.

This script tells us what command is being run and what the exit status is. If the exit status is non-zero, it means the command failed and we exit the script. Since we are manually checking the exit status here, we don't need `set -e` at the top of the script to exit on error.

## Template permissions (enterprise)

Expand Down