diff --git a/.prettierrc.yaml b/.prettierrc.yaml
index 9ba1d2ca9d..7fe31e7338 100644
--- a/.prettierrc.yaml
+++ b/.prettierrc.yaml
@@ -2,6 +2,7 @@
# formatting for prettier-supported files. See `.editorconfig` and
# `site/.editorconfig`for whitespace formatting options.
printWidth: 80
+proseWrap: always
semi: false
trailingComma: all
useTabs: false
@@ -9,10 +10,9 @@ tabWidth: 2
overrides:
- files:
- README.md
+ - docs/api/**/*.md
+ - docs/cli/**/*.md
+ - .github/**/*.{yaml,yml,toml}
+ - scripts/**/*.{yaml,yml,toml}
options:
proseWrap: preserve
- - files:
- - "site/**/*.yaml"
- - "site/**/*.yml"
- options:
- proseWrap: always
diff --git a/README.md b/README.md
index 9443eb6b70..3f7d835125 100644
--- a/README.md
+++ b/README.md
@@ -74,7 +74,7 @@ You can run the install script with `--dry-run` to see the commands that will be
Once installed, you can start a production deployment1 with a single command:
-```console
+```shell
# Automatically sets up an external access URL on *.try.coder.app
coder server
diff --git a/SECURITY.md b/SECURITY.md
index 46986c9d3a..ee5ac8075e 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,7 +1,7 @@
# Coder Security
-Coder welcomes feedback from security researchers and the general public
-to help improve our security. If you believe you have discovered a vulnerability,
+Coder welcomes feedback from security researchers and the general public to help
+improve our security. If you believe you have discovered a vulnerability,
privacy issue, exposed data, or other security issues in any of our assets, we
want to hear from you. This policy outlines steps for reporting vulnerabilities
to us, what we expect, what you can expect from us.
@@ -10,64 +10,72 @@ You can see the pretty version [here](https://coder.com/security/policy)
# Why Coder's security matters
-If an attacker could fully compromise a Coder installation, they could spin
-up expensive workstations, steal valuable credentials, or steal proprietary
-source code. We take this risk very seriously and employ routine pen testing,
-vulnerability scanning, and code reviews. We also welcome the contributions
-from the community that helped make this product possible.
+If an attacker could fully compromise a Coder installation, they could spin up
+expensive workstations, steal valuable credentials, or steal proprietary source
+code. We take this risk very seriously and employ routine pen testing,
+vulnerability scanning, and code reviews. We also welcome the contributions from
+the community that helped make this product possible.
# Where should I report security issues?
-Please report security issues to security@coder.com, providing
-all relevant information. The more details you provide, the easier it will be
-for us to triage and fix the issue.
+Please report security issues to security@coder.com, providing all relevant
+information. The more details you provide, the easier it will be for us to
+triage and fix the issue.
# Out of Scope
-Our primary concern is around an abuse of the Coder application that allows
-an attacker to gain access to another users workspace, or spin up unwanted
+Our primary concern is around an abuse of the Coder application that allows an
+attacker to gain access to another users workspace, or spin up unwanted
workspaces.
- DOS/DDOS attacks affecting availability --> While we do support rate limiting
- of requests, we primarily leave this to the owner of the Coder installation. Our
- rationale is that a DOS attack only affecting availability is not a valuable
- target for attackers.
+ of requests, we primarily leave this to the owner of the Coder installation.
+ Our rationale is that a DOS attack only affecting availability is not a
+ valuable target for attackers.
- Abuse of a compromised user credential --> If a user credential is compromised
- outside of the Coder ecosystem, then we consider it beyond the scope of our application.
- However, if an unprivileged user could escalate their permissions or gain access
- to another workspace, that is a cause for concern.
+ outside of the Coder ecosystem, then we consider it beyond the scope of our
+ application. However, if an unprivileged user could escalate their permissions
+ or gain access to another workspace, that is a cause for concern.
- Vulnerabilities in third party systems --> Vulnerabilities discovered in
- out-of-scope systems should be reported to the appropriate vendor or applicable authority.
+ out-of-scope systems should be reported to the appropriate vendor or
+ applicable authority.
# Our Commitments
When working with us, according to this policy, you can expect us to:
-- Respond to your report promptly, and work with you to understand and validate your report;
-- Strive to keep you informed about the progress of a vulnerability as it is processed;
-- Work to remediate discovered vulnerabilities in a timely manner, within our operational constraints; and
-- Extend Safe Harbor for your vulnerability research that is related to this policy.
+- Respond to your report promptly, and work with you to understand and validate
+ your report;
+- Strive to keep you informed about the progress of a vulnerability as it is
+ processed;
+- Work to remediate discovered vulnerabilities in a timely manner, within our
+ operational constraints; and
+- Extend Safe Harbor for your vulnerability research that is related to this
+ policy.
# Our Expectations
-In participating in our vulnerability disclosure program in good faith, we ask that you:
+In participating in our vulnerability disclosure program in good faith, we ask
+that you:
-- Play by the rules, including following this policy and any other relevant agreements.
- If there is any inconsistency between this policy and any other applicable terms, the
- terms of this policy will prevail;
+- Play by the rules, including following this policy and any other relevant
+ agreements. If there is any inconsistency between this policy and any other
+ applicable terms, the terms of this policy will prevail;
- Report any vulnerability you’ve discovered promptly;
-- Avoid violating the privacy of others, disrupting our systems, destroying data, and/or
- harming user experience;
+- Avoid violating the privacy of others, disrupting our systems, destroying
+ data, and/or harming user experience;
- Use only the Official Channels to discuss vulnerability information with us;
-- Provide us a reasonable amount of time (at least 90 days from the initial report) to
- resolve the issue before you disclose it publicly;
-- Perform testing only on in-scope systems, and respect systems and activities which
- are out-of-scope;
-- If a vulnerability provides unintended access to data: Limit the amount of data you
- access to the minimum required for effectively demonstrating a Proof of Concept; and
- cease testing and submit a report immediately if you encounter any user data during testing,
- such as Personally Identifiable Information (PII), Personal Healthcare Information (PHI),
- credit card data, or proprietary information;
-- You should only interact with test accounts you own or with explicit permission from
+- Provide us a reasonable amount of time (at least 90 days from the initial
+ report) to resolve the issue before you disclose it publicly;
+- Perform testing only on in-scope systems, and respect systems and activities
+ which are out-of-scope;
+- If a vulnerability provides unintended access to data: Limit the amount of
+ data you access to the minimum required for effectively demonstrating a Proof
+ of Concept; and cease testing and submit a report immediately if you encounter
+ any user data during testing, such as Personally Identifiable Information
+ (PII), Personal Healthcare Information (PHI), credit card data, or proprietary
+ information;
+- You should only interact with test accounts you own or with explicit
+ permission from
- the account holder; and
- Do not engage in extortion.
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 291f4e1444..710152a9f3 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -2,7 +2,11 @@
## Requirements
-We recommend using the [Nix](https://nix.dev/) package manager as it makes any pain related to maintaining dependency versions [just disappear](https://twitter.com/mitchellh/status/1491102567296040961). Once nix [has been installed](https://nixos.org/download.html) the development environment can be _manually instantiated_ through the `nix-shell` command:
+We recommend using the [Nix](https://nix.dev/) package manager as it makes any
+pain related to maintaining dependency versions
+[just disappear](https://twitter.com/mitchellh/status/1491102567296040961). Once
+nix [has been installed](https://nixos.org/download.html) the development
+environment can be _manually instantiated_ through the `nix-shell` command:
```shell
cd ~/code/coder
@@ -17,7 +21,10 @@ copying path '/nix/store/v2gvj8whv241nj4lzha3flq8pnllcmvv-ignore-5.2.0.tgz' from
...
```
-If [direnv](https://direnv.net/) is installed and the [hooks are configured](https://direnv.net/docs/hook.html) then the development environment can be _automatically instantiated_ by creating the following `.envrc`, thus removing the need to run `nix-shell` by hand!
+If [direnv](https://direnv.net/) is installed and the
+[hooks are configured](https://direnv.net/docs/hook.html) then the development
+environment can be _automatically instantiated_ by creating the following
+`.envrc`, thus removing the need to run `nix-shell` by hand!
```shell
cd ~/code/coder
@@ -25,7 +32,9 @@ echo "use nix" >.envrc
direnv allow
```
-Now, whenever you enter the project folder, [`direnv`](https://direnv.net/docs/hook.html) will prepare the environment for you:
+Now, whenever you enter the project folder,
+[`direnv`](https://direnv.net/docs/hook.html) will prepare the environment for
+you:
```shell
cd ~/code/coder
@@ -37,7 +46,8 @@ direnv: export +AR +AS +CC +CONFIG_SHELL +CXX +HOST_PATH +IN_NIX_SHELL +LD +NIX_
🎉
```
-Alternatively if you do not want to use nix then you'll need to install the need the following tools by hand:
+Alternatively if you do not want to use nix then you'll need to install the need
+the following tools by hand:
- Go 1.18+
- on macOS, run `brew install go`
@@ -76,35 +86,46 @@ Use the following `make` commands and scripts in development:
- Run `./scripts/develop.sh`
- Access `http://localhost:8080`
-- The default user is `admin@coder.com` and the default password is `SomeSecurePassword!`
+- The default user is `admin@coder.com` and the default password is
+ `SomeSecurePassword!`
### Deploying a PR
-You can test your changes by creating a PR deployment. There are two ways to do this:
+You can test your changes by creating a PR deployment. There are two ways to do
+this:
1. By running `./scripts/deploy-pr.sh`
-2. By manually triggering the [`pr-deploy.yaml`](https://github.com/coder/coder/actions/workflows/pr-deploy.yaml) GitHub Action workflow
- ![Deploy PR manually](./images/deploy-pr-manually.png)
+2. By manually triggering the
+ [`pr-deploy.yaml`](https://github.com/coder/coder/actions/workflows/pr-deploy.yaml)
+ GitHub Action workflow ![Deploy PR manually](./images/deploy-pr-manually.png)
#### Available options
- `-d` or `--deploy`, force deploys the PR by deleting the existing deployment.
-- `-b` or `--build`, force builds the Docker image. (generally not needed as we are intelligently checking if the image needs to be built)
-- `-e EXPERIMENT1,EXPERIMENT2` or `--experiments EXPERIMENT1,EXPERIMENT2`, will enable the specified experiments. (defaults to `*`)
-- `-n` or `--dry-run` will display the context without deployment. e.g., branch name and PR number, etc.
+- `-b` or `--build`, force builds the Docker image. (generally not needed as we
+ are intelligently checking if the image needs to be built)
+- `-e EXPERIMENT1,EXPERIMENT2` or `--experiments EXPERIMENT1,EXPERIMENT2`, will
+ enable the specified experiments. (defaults to `*`)
+- `-n` or `--dry-run` will display the context without deployment. e.g., branch
+ name and PR number, etc.
- `-y` or `--yes`, will skip the CLI confirmation prompt.
-> Note: PR deployment will be re-deployed automatically when the PR is updated. It will use the last values automatically for redeployment.
+> Note: PR deployment will be re-deployed automatically when the PR is updated.
+> It will use the last values automatically for redeployment.
-> You need to be a member or collaborator of the of [coder](github.com/coder) GitHub organization to be able to deploy a PR.
+> You need to be a member or collaborator of the of [coder](github.com/coder)
+> GitHub organization to be able to deploy a PR.
-Once the deployment is finished, a unique link and credentials will be posted in the [#pr-deployments](https://codercom.slack.com/archives/C05DNE982E8) Slack channel.
+Once the deployment is finished, a unique link and credentials will be posted in
+the [#pr-deployments](https://codercom.slack.com/archives/C05DNE982E8) Slack
+channel.
### Adding database migrations and fixtures
#### Database migrations
-Database migrations are managed with [`migrate`](https://github.com/golang-migrate/migrate).
+Database migrations are managed with
+[`migrate`](https://github.com/golang-migrate/migrate).
To add new migrations, use the following command:
@@ -125,11 +146,15 @@ much data as possible.
There are two types of fixtures that are used to test that migrations don't
break existing Coder deployments:
-- Partial fixtures [`migrations/testdata/fixtures`](../coderd/database/migrations/testdata/fixtures)
-- Full database dumps [`migrations/testdata/full_dumps`](../coderd/database/migrations/testdata/full_dumps)
+- Partial fixtures
+ [`migrations/testdata/fixtures`](../coderd/database/migrations/testdata/fixtures)
+- Full database dumps
+ [`migrations/testdata/full_dumps`](../coderd/database/migrations/testdata/full_dumps)
-Both types behave like database migrations (they also [`migrate`](https://github.com/golang-migrate/migrate)). Their behavior mirrors Coder migrations such that when migration
-number `000022` is applied, fixture `000022` is applied afterwards.
+Both types behave like database migrations (they also
+[`migrate`](https://github.com/golang-migrate/migrate)). Their behavior mirrors
+Coder migrations such that when migration number `000022` is applied, fixture
+`000022` is applied afterwards.
Partial fixtures are used to conveniently add data to newly created tables so
that we can ensure that this data is migrated without issue.
@@ -175,19 +200,20 @@ This helps in naming the dump (e.g. `000069` above).
### Documentation
-Our style guide for authoring documentation can be found [here](./contributing/documentation.md).
+Our style guide for authoring documentation can be found
+[here](./contributing/documentation.md).
### Backend
#### Use Go style
-Contributions must adhere to the guidelines outlined in [Effective
-Go](https://go.dev/doc/effective_go). We prefer linting rules over documenting
-styles (run ours with `make lint`); humans are error-prone!
+Contributions must adhere to the guidelines outlined in
+[Effective Go](https://go.dev/doc/effective_go). We prefer linting rules over
+documenting styles (run ours with `make lint`); humans are error-prone!
-Read [Go's Code Review Comments
-Wiki](https://github.com/golang/go/wiki/CodeReviewComments) for information on
-common comments made during reviews of Go code.
+Read
+[Go's Code Review Comments Wiki](https://github.com/golang/go/wiki/CodeReviewComments)
+for information on common comments made during reviews of Go code.
#### Avoid unused packages
@@ -202,8 +228,8 @@ Our frontend guide can be found [here](./contributing/frontend.md).
## Reviews
-> The following information has been borrowed from [Go's review
-> philosophy](https://go.dev/doc/contribute#reviews).
+> The following information has been borrowed from
+> [Go's review philosophy](https://go.dev/doc/contribute#reviews).
Coder values thorough reviews. For each review comment that you receive, please
"close" it by implementing the suggestion or providing an explanation on why the
@@ -220,27 +246,45 @@ be applied selectively or to discourage anyone from contributing.
## Releases
-Coder releases are initiated via [`./scripts/release.sh`](../scripts/release.sh) and automated via GitHub Actions. Specifically, the [`release.yaml`](../.github/workflows/release.yaml) workflow. They are created based on the current [`main`](https://github.com/coder/coder/tree/main) branch.
+Coder releases are initiated via [`./scripts/release.sh`](../scripts/release.sh)
+and automated via GitHub Actions. Specifically, the
+[`release.yaml`](../.github/workflows/release.yaml) workflow. They are created
+based on the current [`main`](https://github.com/coder/coder/tree/main) branch.
-The release notes for a release are automatically generated from commit titles and metadata from PRs that are merged into `main`.
+The release notes for a release are automatically generated from commit titles
+and metadata from PRs that are merged into `main`.
### Creating a release
-The creation of a release is initiated via [`./scripts/release.sh`](../scripts/release.sh). This script will show a preview of the release that will be created, and if you choose to continue, create and push the tag which will trigger the creation of the release via GitHub Actions.
+The creation of a release is initiated via
+[`./scripts/release.sh`](../scripts/release.sh). This script will show a preview
+of the release that will be created, and if you choose to continue, create and
+push the tag which will trigger the creation of the release via GitHub Actions.
See `./scripts/release.sh --help` for more information.
### Creating a release (via workflow dispatch)
-Typically the workflow dispatch is only used to test (dry-run) a release, meaning no actual release will take place. The workflow can be dispatched manually from [Actions: Release](https://github.com/coder/coder/actions/workflows/release.yaml). Simply press "Run workflow" and choose dry-run.
+Typically the workflow dispatch is only used to test (dry-run) a release,
+meaning no actual release will take place. The workflow can be dispatched
+manually from
+[Actions: Release](https://github.com/coder/coder/actions/workflows/release.yaml).
+Simply press "Run workflow" and choose dry-run.
-If a release has failed after the tag has been created and pushed, it can be retried by again, pressing "Run workflow", changing "Use workflow from" from "Branch: main" to "Tag: vX.X.X" and not selecting dry-run.
+If a release has failed after the tag has been created and pushed, it can be
+retried by again, pressing "Run workflow", changing "Use workflow from" from
+"Branch: main" to "Tag: vX.X.X" and not selecting dry-run.
### Commit messages
-Commit messages should follow the [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) specification.
+Commit messages should follow the
+[Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
+specification.
-Allowed commit types (`feat`, `fix`, etc.) are listed in [conventional-commit-types](https://github.com/commitizen/conventional-commit-types/blob/c3a9be4c73e47f2e8197de775f41d981701407fb/index.json). Note that these types are also used to automatically sort and organize the release notes.
+Allowed commit types (`feat`, `fix`, etc.) are listed in
+[conventional-commit-types](https://github.com/commitizen/conventional-commit-types/blob/c3a9be4c73e47f2e8197de775f41d981701407fb/index.json).
+Note that these types are also used to automatically sort and organize the
+release notes.
A good commit message title uses the imperative, present tense and is ~50
characters long (no more than 72).
@@ -250,21 +294,34 @@ Examples:
- Good: `feat(api): add feature X`
- Bad: `feat(api): added feature X` (past tense)
-A good rule of thumb for writing good commit messages is to recite: [If applied, this commit will ...](https://reflectoring.io/meaningful-commit-messages/).
+A good rule of thumb for writing good commit messages is to recite:
+[If applied, this commit will ...](https://reflectoring.io/meaningful-commit-messages/).
-**Note:** We lint PR titles to ensure they follow the Conventional Commits specification, however, it's still possible to merge PRs on GitHub with a badly formatted title. Take care when merging single-commit PRs as GitHub may prefer to use the original commit title instead of the PR title.
+**Note:** We lint PR titles to ensure they follow the Conventional Commits
+specification, however, it's still possible to merge PRs on GitHub with a badly
+formatted title. Take care when merging single-commit PRs as GitHub may prefer
+to use the original commit title instead of the PR title.
### Breaking changes
Breaking changes can be triggered in two ways:
-- Add `!` to the commit message title, e.g. `feat(api)!: remove deprecated endpoint /test`
-- Add the [`release/breaking`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Arelease%2Fbreaking) label to a PR that has, or will be, merged into `main`.
+- Add `!` to the commit message title, e.g.
+ `feat(api)!: remove deprecated endpoint /test`
+- Add the
+ [`release/breaking`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Arelease%2Fbreaking)
+ label to a PR that has, or will be, merged into `main`.
### Security
-The [`security`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Asecurity) label can be added to PRs that have, or will be, merged into `main`. Doing so will make sure the change stands out in the release notes.
+The
+[`security`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Asecurity)
+label can be added to PRs that have, or will be, merged into `main`. Doing so
+will make sure the change stands out in the release notes.
### Experimental
-The [`release/experimental`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Arelease%2Fexperimental) label can be used to move the note to the bottom of the release notes under a separate title.
+The
+[`release/experimental`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Arelease%2Fexperimental)
+label can be used to move the note to the bottom of the release notes under a
+separate title.
diff --git a/docs/about/architecture.md b/docs/about/architecture.md
index 45ef36b99b..9489ee7fc8 100644
--- a/docs/about/architecture.md
+++ b/docs/about/architecture.md
@@ -8,9 +8,9 @@ This document provides a high level overview of Coder's architecture.
## coderd
-coderd is the service created by running `coder server`. It is a thin
-API that connects workspaces, provisioners and users. coderd stores its state in
-Postgres and is the only service that communicates with Postgres.
+coderd is the service created by running `coder server`. It is a thin API that
+connects workspaces, provisioners and users. coderd stores its state in Postgres
+and is the only service that communicates with Postgres.
It offers:
@@ -22,16 +22,18 @@ It offers:
## provisionerd
-provisionerd is the execution context for infrastructure modifying providers.
-At the moment, the only provider is Terraform (running `terraform`).
+provisionerd is the execution context for infrastructure modifying providers. At
+the moment, the only provider is Terraform (running `terraform`).
-By default, the Coder server runs multiple provisioner daemons. [External provisioners](../admin/provisioners.md) can be added for security or scalability purposes.
+By default, the Coder server runs multiple provisioner daemons.
+[External provisioners](../admin/provisioners.md) can be added for security or
+scalability purposes.
## Agents
-An agent is the Coder service that runs within a user's remote workspace.
-It provides a consistent interface for coderd and clients to communicate
-with workspaces regardless of operating system, architecture, or cloud.
+An agent is the Coder service that runs within a user's remote workspace. It
+provides a consistent interface for coderd and clients to communicate with
+workspaces regardless of operating system, architecture, or cloud.
It offers the following services along with much more:
@@ -40,15 +42,20 @@ It offers the following services along with much more:
- Liveness checks
- `startup_script` automation
-Templates are responsible for [creating and running agents](../templates/index.md#coder-agent) within workspaces.
+Templates are responsible for
+[creating and running agents](../templates/index.md#coder-agent) within
+workspaces.
## Service Bundling
-While coderd and Postgres can be orchestrated independently,our default installation
-paths bundle them all together into one system service. It's perfectly fine to run a production deployment this way, but there are certain situations that necessitate decomposition:
+While coderd and Postgres can be orchestrated independently,our default
+installation paths bundle them all together into one system service. It's
+perfectly fine to run a production deployment this way, but there are certain
+situations that necessitate decomposition:
- Reducing global client latency (distribute coderd and centralize database)
-- Achieving greater availability and efficiency (horizontally scale individual services)
+- Achieving greater availability and efficiency (horizontally scale individual
+ services)
## Workspaces
diff --git a/docs/admin/app-logs.md b/docs/admin/app-logs.md
index 87efe05ae6..8235fda06e 100644
--- a/docs/admin/app-logs.md
+++ b/docs/admin/app-logs.md
@@ -1,21 +1,28 @@
# Application Logs
-In Coderd, application logs refer to the records of events, messages, and activities generated by the application during its execution.
-These logs provide valuable information about the application's behavior, performance, and any issues that may have occurred.
+In Coderd, application logs refer to the records of events, messages, and
+activities generated by the application during its execution. These logs provide
+valuable information about the application's behavior, performance, and any
+issues that may have occurred.
-Application logs include entries that capture events on different levels of severity:
+Application logs include entries that capture events on different levels of
+severity:
- Informational messages
- Warnings
- Errors
- Debugging information
-By analyzing application logs, system administrators can gain insights into the application's behavior, identify and diagnose problems, track performance metrics, and make informed decisions to improve the application's stability and efficiency.
+By analyzing application logs, system administrators can gain insights into the
+application's behavior, identify and diagnose problems, track performance
+metrics, and make informed decisions to improve the application's stability and
+efficiency.
## Error logs
-To ensure effective monitoring and timely response to critical events in the Coder application, it is recommended to configure log alerts
-that specifically watch for the following log entries:
+To ensure effective monitoring and timely response to critical events in the
+Coder application, it is recommended to configure log alerts that specifically
+watch for the following log entries:
| Log Level | Module | Log message | Potential issues |
| --------- | ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------- |
diff --git a/docs/admin/appearance.md b/docs/admin/appearance.md
index 5d061b3bb1..f80ffc8c1b 100644
--- a/docs/admin/appearance.md
+++ b/docs/admin/appearance.md
@@ -2,12 +2,15 @@
## Support Links
-Support links let admins adjust the user dropdown menu to include links referring to internal company resources. The menu section replaces the original menu positions: documentation, report a bug to GitHub, or join the Discord server.
+Support links let admins adjust the user dropdown menu to include links
+referring to internal company resources. The menu section replaces the original
+menu positions: documentation, report a bug to GitHub, or join the Discord
+server.
![support links](../images/admin/support-links.png)
-Custom links can be set in the deployment configuration using the `-c `
-flag to `coder server`.
+Custom links can be set in the deployment configuration using the
+`-c ` flag to `coder server`.
```yaml
supportLinks:
@@ -27,7 +30,8 @@ The link icons are optional, and limited to: `bug`, `chat`, and `docs`.
## Service Banners (enterprise)
-Service Banners let admins post important messages to all site users. Only Site Owners may set the service banner.
+Service Banners let admins post important messages to all site users. Only Site
+Owners may set the service banner.
![service banners](../images/admin/service-banners.png)
diff --git a/docs/admin/audit-logs.md b/docs/admin/audit-logs.md
index 143ff59344..3ad9395e35 100644
--- a/docs/admin/audit-logs.md
+++ b/docs/admin/audit-logs.md
@@ -1,7 +1,6 @@
# Audit Logs
-Audit Logs allows **Auditors** to monitor user operations in
-their deployment.
+Audit Logs allows **Auditors** to monitor user operations in their deployment.
## Tracked Events
@@ -27,34 +26,48 @@ We track the following resources:
## Filtering logs
-In the Coder UI you can filter your audit logs using the pre-defined filter or by using the Coder's filter query like the examples below:
+In the Coder UI you can filter your audit logs using the pre-defined filter or
+by using the Coder's filter query like the examples below:
- `resource_type:workspace action:delete` to find deleted workspaces
- `resource_type:template action:create` to find created templates
The supported filters are:
-- `resource_type` - The type of the resource. It can be a workspace, template, user, etc. You can [find here](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#ResourceType) all the resource types that are supported.
+- `resource_type` - The type of the resource. It can be a workspace, template,
+ user, etc. You can
+ [find here](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#ResourceType)
+ all the resource types that are supported.
- `resource_id` - The ID of the resource.
-- `resource_target` - The name of the resource. Can be used instead of `resource_id`.
-- `action`- The action applied to a resource. You can [find here](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#AuditAction) all the actions that are supported.
-- `username` - The username of the user who triggered the action. You can also use `me` as a convenient alias for the logged-in user.
+- `resource_target` - The name of the resource. Can be used instead of
+ `resource_id`.
+- `action`- The action applied to a resource. You can
+ [find here](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#AuditAction)
+ all the actions that are supported.
+- `username` - The username of the user who triggered the action. You can also
+ use `me` as a convenient alias for the logged-in user.
- `email` - The email of the user who triggered the action.
- `date_from` - The inclusive start date with format `YYYY-MM-DD`.
- `date_to` - The inclusive end date with format `YYYY-MM-DD`.
-- `build_reason` - To be used with `resource_type:workspace_build`, the [initiator](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#BuildReason) behind the build start or stop.
+- `build_reason` - To be used with `resource_type:workspace_build`, the
+ [initiator](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#BuildReason)
+ behind the build start or stop.
## Capturing/Exporting Audit Logs
-In addition to the user interface, there are multiple ways to consume or query audit trails.
+In addition to the user interface, there are multiple ways to consume or query
+audit trails.
## REST API
-Audit logs can be accessed through our REST API. You can find detailed information about this in our [endpoint documentation](../api/audit.md#get-audit-logs).
+Audit logs can be accessed through our REST API. You can find detailed
+information about this in our
+[endpoint documentation](../api/audit.md#get-audit-logs).
## Service Logs
-Audit trails are also dispatched as service logs and can be captured and categorized using any log management tool such as [Splunk](https://splunk.com).
+Audit trails are also dispatched as service logs and can be captured and
+categorized using any log management tool such as [Splunk](https://splunk.com).
Example of a [JSON formatted](../cli/server.md#--log-json) audit log entry:
@@ -93,10 +106,11 @@ Example of a [JSON formatted](../cli/server.md#--log-json) audit log entry:
Example of a [human readable](../cli/server.md#--log-human) audit log entry:
-```sh
+```console
2023-06-13 03:43:29.233 [info] coderd: audit_log ID=95f7c392-da3e-480c-a579-8909f145fbe2 Time="2023-06-13T03:43:29.230422Z" UserID=6c405053-27e3-484a-9ad7-bcb64e7bfde6 OrganizationID=00000000-0000-0000-0000-000000000000 Ip= UserAgent= ResourceType=workspace_build ResourceID=988ae133-5b73-41e3-a55e-e1e9d3ef0b66 ResourceTarget="" Action=start Diff="{}" StatusCode=200 AdditionalFields="{\"workspace_name\":\"linux-container\",\"build_number\":\"7\",\"build_reason\":\"initiator\",\"workspace_owner\":\"\"}" RequestID=9682b1b5-7b9f-4bf2-9a39-9463f8e41cd6 ResourceIcon=""
```
## Enabling this feature
-This feature is only available with an enterprise license. [Learn more](../enterprise.md)
+This feature is only available with an enterprise license.
+[Learn more](../enterprise.md)
diff --git a/docs/admin/auth.md b/docs/admin/auth.md
index 4a512bfc36..fb278cf09b 100644
--- a/docs/admin/auth.md
+++ b/docs/admin/auth.md
@@ -14,12 +14,19 @@ The following steps explain how to set up GitHub OAuth or OpenID Connect.
### Step 1: Configure the OAuth application in GitHub
-First, [register a GitHub OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/). GitHub will ask you for the following Coder parameters:
+First,
+[register a GitHub OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/).
+GitHub will ask you for the following Coder parameters:
-- **Homepage URL**: Set to your Coder deployments [`CODER_ACCESS_URL`](https://coder.com/docs/v2/latest/cli/server#--access-url) (e.g. `https://coder.domain.com`)
+- **Homepage URL**: Set to your Coder deployments
+ [`CODER_ACCESS_URL`](../cli/server.md#--access-url) (e.g.
+ `https://coder.domain.com`)
- **User Authorization Callback URL**: Set to `https://coder.domain.com`
-> Note: If you want to allow multiple coder deployments hosted on subdomains e.g. coder1.domain.com, coder2.domain.com, to be able to authenticate with the same GitHub OAuth app, then you can set **User Authorization Callback URL** to the `https://domain.com`
+> Note: If you want to allow multiple coder deployments hosted on subdomains
+> e.g. coder1.domain.com, coder2.domain.com, to be able to authenticate with the
+> same GitHub OAuth app, then you can set **User Authorization Callback URL** to
+> the `https://domain.com`
Note the Client ID and Client Secret generated by GitHub. You will use these
values in the next step.
@@ -29,17 +36,18 @@ values in the next step.
Navigate to your Coder host and run the following command to start up the Coder
server:
-```console
+```shell
coder server --oauth2-github-allow-signups=true --oauth2-github-allowed-orgs="your-org" --oauth2-github-client-id="8d1...e05" --oauth2-github-client-secret="57ebc9...02c24c"
```
-> For GitHub Enterprise support, specify the `--oauth2-github-enterprise-base-url` flag.
+> For GitHub Enterprise support, specify the
+> `--oauth2-github-enterprise-base-url` flag.
Alternatively, if you are running Coder as a system service, you can achieve the
same result as the command above by adding the following environment variables
to the `/etc/coder.d/coder.env` file:
-```console
+```env
CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05"
@@ -48,7 +56,7 @@ CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c"
**Note:** To allow everyone to signup using GitHub, set:
-```console
+```env
CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
```
@@ -76,7 +84,7 @@ coder:
To upgrade Coder, run:
-```console
+```shell
helm upgrade coder-v2/coder -n -f values.yaml
```
@@ -86,7 +94,8 @@ helm upgrade coder-v2/coder -n -f values.yaml
## OpenID Connect
-The following steps through how to integrate any OpenID Connect provider (Okta, Active Directory, etc.) to Coder.
+The following steps through how to integrate any OpenID Connect provider (Okta,
+Active Directory, etc.) to Coder.
### Step 1: Set Redirect URI with your OIDC provider
@@ -99,15 +108,15 @@ Your OIDC provider will ask you for the following parameter:
Navigate to your Coder host and run the following command to start up the Coder
server:
-```console
+```shell
coder server --oidc-issuer-url="https://issuer.corp.com" --oidc-email-domain="your-domain-1,your-domain-2" --oidc-client-id="533...des" --oidc-client-secret="G0CSP...7qSM"
```
-If you are running Coder as a system service, you can achieve the
-same result as the command above by adding the following environment variables
-to the `/etc/coder.d/coder.env` file:
+If you are running Coder as a system service, you can achieve the same result as
+the command above by adding the following environment variables to the
+`/etc/coder.d/coder.env` file:
-```console
+```env
CODER_OIDC_ISSUER_URL="https://issuer.corp.com"
CODER_OIDC_EMAIL_DOMAIN="your-domain-1,your-domain-2"
CODER_OIDC_CLIENT_ID="533...des"
@@ -134,46 +143,46 @@ coder:
To upgrade Coder, run:
-```console
+```shell
helm upgrade coder-v2/coder -n -f values.yaml
```
## OIDC Claims
-When a user logs in for the first time via OIDC, Coder will merge both
-the claims from the ID token and the claims obtained from hitting the
-upstream provider's `userinfo` endpoint, and use the resulting data
-as a basis for creating a new user or looking up an existing user.
+When a user logs in for the first time via OIDC, Coder will merge both the
+claims from the ID token and the claims obtained from hitting the upstream
+provider's `userinfo` endpoint, and use the resulting data as a basis for
+creating a new user or looking up an existing user.
-To troubleshoot claims, set `CODER_VERBOSE=true` and follow the logs
-while signing in via OIDC as a new user. Coder will log the claim fields
-returned by the upstream identity provider in a message containing the
-string `got oidc claims`, as well as the user info returned.
+To troubleshoot claims, set `CODER_VERBOSE=true` and follow the logs while
+signing in via OIDC as a new user. Coder will log the claim fields returned by
+the upstream identity provider in a message containing the string
+`got oidc claims`, as well as the user info returned.
-> **Note:** If you need to ensure that Coder only uses information from
-> the ID token and does not hit the UserInfo endpoint, you can set the
-> configuration option `CODER_OIDC_IGNORE_USERINFO=true`.
+> **Note:** If you need to ensure that Coder only uses information from the ID
+> token and does not hit the UserInfo endpoint, you can set the configuration
+> option `CODER_OIDC_IGNORE_USERINFO=true`.
### Email Addresses
-By default, Coder will look for the OIDC claim named `email` and use that
-value for the newly created user's email address.
+By default, Coder will look for the OIDC claim named `email` and use that value
+for the newly created user's email address.
If your upstream identity provider users a different claim, you can set
`CODER_OIDC_EMAIL_FIELD` to the desired claim.
-> **Note:** If this field is not present, Coder will attempt to use the
-> claim field configured for `username` as an email address. If this field
-> is not a valid email address, OIDC logins will fail.
+> **Note** If this field is not present, Coder will attempt to use the claim
+> field configured for `username` as an email address. If this field is not a
+> valid email address, OIDC logins will fail.
### Email Address Verification
-Coder requires all OIDC email addresses to be verified by default. If
-the `email_verified` claim is present in the token response from the identity
+Coder requires all OIDC email addresses to be verified by default. If the
+`email_verified` claim is present in the token response from the identity
provider, Coder will validate that its value is `true`. If needed, you can
disable this behavior with the following setting:
-```console
+```env
CODER_OIDC_IGNORE_EMAIL_VERIFIED=true
```
@@ -182,14 +191,14 @@ CODER_OIDC_IGNORE_EMAIL_VERIFIED=true
### Usernames
-When a new user logs in via OIDC, Coder will by default use the value
-of the claim field named `preferred_username` as the the username.
+When a new user logs in via OIDC, Coder will by default use the value of the
+claim field named `preferred_username` as the the username.
-If your upstream identity provider uses a different claim, you can
-set `CODER_OIDC_USERNAME_FIELD` to the desired claim.
+If your upstream identity provider uses a different claim, you can set
+`CODER_OIDC_USERNAME_FIELD` to the desired claim.
-> **Note:** If this claim is empty, the email address will be stripped of
-> the domain, and become the username (e.g. `example@coder.com` becomes `example`).
+> **Note:** If this claim is empty, the email address will be stripped of the
+> domain, and become the username (e.g. `example@coder.com` becomes `example`).
> To avoid conflicts, Coder may also append a random word to the resulting
> username.
@@ -198,36 +207,38 @@ set `CODER_OIDC_USERNAME_FIELD` to the desired claim.
If you'd like to change the OpenID Connect button text and/or icon, you can
configure them like so:
-```console
+```env
CODER_OIDC_SIGN_IN_TEXT="Sign in with Gitea"
CODER_OIDC_ICON_URL=https://gitea.io/images/gitea.png
```
## Disable Built-in Authentication
-To remove email and password login, set the following environment variable on your
-Coder deployment:
+To remove email and password login, set the following environment variable on
+your Coder deployment:
-```console
+```env
CODER_DISABLE_PASSWORD_AUTH=true
```
## SCIM (enterprise)
Coder supports user provisioning and deprovisioning via SCIM 2.0 with header
-authentication. Upon deactivation, users are [suspended](./users.md#suspend-a-user)
-and are not deleted. [Configure](./configure.md) your SCIM application with an
-auth key and supply it the Coder server.
+authentication. Upon deactivation, users are
+[suspended](./users.md#suspend-a-user) and are not deleted.
+[Configure](./configure.md) your SCIM application with an auth key and supply it
+the Coder server.
-```console
+```env
CODER_SCIM_API_KEY="your-api-key"
```
## TLS
-If your OpenID Connect provider requires client TLS certificates for authentication, you can configure them like so:
+If your OpenID Connect provider requires client TLS certificates for
+authentication, you can configure them like so:
-```console
+```env
CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
```
@@ -237,22 +248,31 @@ CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
If your OpenID Connect provider supports group claims, you can configure Coder
to synchronize groups in your auth provider to groups within Coder.
-To enable group sync, ensure that the `groups` claim is set by adding the correct scope to request. If group sync is
-enabled, the user's groups will be controlled by the OIDC provider. This means
-manual group additions/removals will be overwritten on the next login.
+To enable group sync, ensure that the `groups` claim is set by adding the
+correct scope to request. If group sync is enabled, the user's groups will be
+controlled by the OIDC provider. This means manual group additions/removals will
+be overwritten on the next login.
-```console
+```env
# as an environment variable
CODER_OIDC_SCOPES=openid,profile,email,groups
+```
+
+```shell
# as a flag
--oidc-scopes openid,profile,email,groups
```
-With the `groups` scope requested, we also need to map the `groups` claim name. Coder recommends using `groups` for the claim name. This step is necessary if your **scope's name** is something other than `groups`.
+With the `groups` scope requested, we also need to map the `groups` claim name.
+Coder recommends using `groups` for the claim name. This step is necessary if
+your **scope's name** is something other than `groups`.
-```console
+```env
# as an environment variable
CODER_OIDC_GROUP_FIELD=groups
+```
+
+```shell
# as a flag
--oidc-group-field groups
```
@@ -264,9 +284,12 @@ For cases when an OIDC provider only returns group IDs ([Azure AD][azure-gids])
or you want to have different group names in Coder than in your OIDC provider,
you can configure mapping between the two.
-```console
+```env
# as an environment variable
CODER_OIDC_GROUP_MAPPING='{"myOIDCGroupID": "myCoderGroupName"}'
+```
+
+```shell
# as a flag
--oidc-group-mapping '{"myOIDCGroupID": "myCoderGroupName"}'
```
@@ -286,7 +309,8 @@ OIDC provider will be added to the `myCoderGroupName` group in Coder.
> **Note:** Groups are only updated on login.
-[azure-gids]: https://github.com/MicrosoftDocs/azure-docs/issues/59766#issuecomment-664387195
+[azure-gids]:
+ https://github.com/MicrosoftDocs/azure-docs/issues/59766#issuecomment-664387195
### Troubleshooting
@@ -294,22 +318,34 @@ Some common issues when enabling group sync.
#### User not being assigned / Group does not exist
-If you want Coder to create groups that do not exist, you can set the following environment variable. If you enable this, your OIDC provider might be sending over many unnecessary groups. Use filtering options on the OIDC provider to limit the groups sent over to prevent creating excess groups.
+If you want Coder to create groups that do not exist, you can set the following
+environment variable. If you enable this, your OIDC provider might be sending
+over many unnecessary groups. Use filtering options on the OIDC provider to
+limit the groups sent over to prevent creating excess groups.
-```console
+```env
# as an environment variable
CODER_OIDC_GROUP_AUTO_CREATE=true
+```
+```shell
# as a flag
--oidc-group-auto-create=true
```
-A basic regex filtering option on the Coder side is available. This is applied **after** the group mapping (`CODER_OIDC_GROUP_MAPPING`), meaning if the group is remapped, the remapped value is tested in the regex. This is useful if you want to filter out groups that do not match a certain pattern. For example, if you want to only allow groups that start with `my-group-` to be created, you can set the following environment variable.
+A basic regex filtering option on the Coder side is available. This is applied
+**after** the group mapping (`CODER_OIDC_GROUP_MAPPING`), meaning if the group
+is remapped, the remapped value is tested in the regex. This is useful if you
+want to filter out groups that do not match a certain pattern. For example, if
+you want to only allow groups that start with `my-group-` to be created, you can
+set the following environment variable.
-```console
+```env
# as an environment variable
CODER_OIDC_GROUP_REGEX_FILTER="^my-group-.*$"
+```
+```shell
# as a flag
--oidc-group-regex-filter="^my-group-.*$"
```
@@ -322,28 +358,39 @@ If you see an error like the following, you may have an invalid scope.
The application '' asked for scope 'groups' that doesn't exist on the resource...
```
-This can happen because the identity provider has a different name for the scope. For example, Azure AD uses `GroupMember.Read.All` instead of `groups`. You can find the correct scope name in the IDP's documentation. Some IDP's allow configuring the name of this scope.
+This can happen because the identity provider has a different name for the
+scope. For example, Azure AD uses `GroupMember.Read.All` instead of `groups`.
+You can find the correct scope name in the IDP's documentation. Some IDP's allow
+configuring the name of this scope.
-The solution is to update the value of `CODER_OIDC_SCOPES` to the correct value for the identity provider.
+The solution is to update the value of `CODER_OIDC_SCOPES` to the correct value
+for the identity provider.
#### No `group` claim in the `got oidc claims` log
Steps to troubleshoot.
-1. Ensure the user is a part of a group in the IDP. If the user has 0 groups, no `groups` claim will be sent.
-2. Check if another claim appears to be the correct claim with a different name. A common name is `memberOf` instead of `groups`. If this is present, update `CODER_OIDC_GROUP_FIELD=memberOf`.
-3. Make sure the number of groups being sent is under the limit of the IDP. Some IDPs will return an error, while others will just omit the `groups` claim. A common solution is to create a filter on the identity provider that returns less than the limit for your IDP.
+1. Ensure the user is a part of a group in the IDP. If the user has 0 groups, no
+ `groups` claim will be sent.
+2. Check if another claim appears to be the correct claim with a different name.
+ A common name is `memberOf` instead of `groups`. If this is present, update
+ `CODER_OIDC_GROUP_FIELD=memberOf`.
+3. Make sure the number of groups being sent is under the limit of the IDP. Some
+ IDPs will return an error, while others will just omit the `groups` claim. A
+ common solution is to create a filter on the identity provider that returns
+ less than the limit for your IDP.
- [Azure AD limit is 200, and omits groups if exceeded.](https://learn.microsoft.com/en-us/azure/active-directory/hybrid/connect/how-to-connect-fed-group-claims#options-for-applications-to-consume-group-information)
- [Okta limit is 100, and returns an error if exceeded.](https://developer.okta.com/docs/reference/api/oidc/#scope-dependent-claims-not-always-returned)
## Role sync (enterprise)
If your OpenID Connect provider supports roles claims, you can configure Coder
-to synchronize roles in your auth provider to deployment-wide roles within Coder.
+to synchronize roles in your auth provider to deployment-wide roles within
+Coder.
Set the following in your Coder server [configuration](./configure.md).
-```console
+```env
# Depending on your identity provider configuration, you may need to explicitly request a "roles" scope
CODER_OIDC_SCOPES=openid,profile,email,roles
@@ -352,7 +399,8 @@ CODER_OIDC_USER_ROLE_FIELD=roles
CODER_OIDC_USER_ROLE_MAPPING='{"TemplateAuthor":["template-admin","user-admin"]}'
```
-> One role from your identity provider can be mapped to many roles in Coder (e.g. the example above maps to 2 roles in Coder.)
+> One role from your identity provider can be mapped to many roles in Coder
+> (e.g. the example above maps to 2 roles in Coder.)
## Provider-Specific Guides
@@ -362,17 +410,20 @@ Below are some details specific to individual OIDC providers.
> **Note:** Tested on ADFS 4.0, Windows Server 2019
-1. In your Federation Server, create a new application group for Coder. Follow the
- steps as described [here.](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/development/msal/adfs-msal-web-app-web-api#app-registration-in-ad-fs)
+1. In your Federation Server, create a new application group for Coder. Follow
+ the steps as described
+ [here.](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/development/msal/adfs-msal-web-app-web-api#app-registration-in-ad-fs)
- **Server Application**: Note the Client ID.
- **Configure Application Credentials**: Note the Client Secret.
- **Configure Web API**: Set the Client ID as the relying party identifier.
- - **Application Permissions**: Allow access to the claims `openid`, `email`, `profile`, and `allatclaims`.
-1. Visit your ADFS server's `/.well-known/openid-configuration` URL and note
- the value for `issuer`.
- > **Note:** This is usually of the form `https://adfs.corp/adfs/.well-known/openid-configuration`
-1. In Coder's configuration file (or Helm values as appropriate), set the following
- environment variables or their corresponding CLI arguments:
+ - **Application Permissions**: Allow access to the claims `openid`, `email`,
+ `profile`, and `allatclaims`.
+1. Visit your ADFS server's `/.well-known/openid-configuration` URL and note the
+ value for `issuer`.
+ > **Note:** This is usually of the form
+ > `https://adfs.corp/adfs/.well-known/openid-configuration`
+1. In Coder's configuration file (or Helm values as appropriate), set the
+ following environment variables or their corresponding CLI arguments:
- `CODER_OIDC_ISSUER_URL`: the `issuer` value from the previous step.
- `CODER_OIDC_CLIENT_ID`: the Client ID from step 1.
@@ -383,28 +434,44 @@ Below are some details specific to individual OIDC providers.
{"resource":"$CLIENT_ID"}
```
- where `$CLIENT_ID` is the Client ID from step 1 ([see here](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/overview/ad-fs-openid-connect-oauth-flows-scenarios#:~:text=scope%E2%80%AFopenid.-,resource,-optional)).
- This is required for the upstream OIDC provider to return the requested claims.
+ where `$CLIENT_ID` is the Client ID from step 1
+ ([see here](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/overview/ad-fs-openid-connect-oauth-flows-scenarios#:~:text=scope%E2%80%AFopenid.-,resource,-optional)).
+ This is required for the upstream OIDC provider to return the requested
+ claims.
- `CODER_OIDC_IGNORE_USERINFO`: Set to `true`.
-1. Configure [Issuance Transform Rules](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-rule-to-send-ldap-attributes-as-claims)
+1. Configure
+ [Issuance Transform Rules](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-rule-to-send-ldap-attributes-as-claims)
on your federation server to send the following claims:
- `preferred_username`: You can use e.g. "Display Name" as required.
- - `email`: You can use e.g. the LDAP attribute "E-Mail-Addresses" as required.
+ - `email`: You can use e.g. the LDAP attribute "E-Mail-Addresses" as
+ required.
- `email_verified`: Create a custom claim rule:
```console
=> issue(Type = "email_verified", Value = "true")
```
- - (Optional) If using Group Sync, send the required groups in the configured groups claim field. See [here](https://stackoverflow.com/a/55570286) for an example.
+ - (Optional) If using Group Sync, send the required groups in the configured
+ groups claim field. See [here](https://stackoverflow.com/a/55570286) for an
+ example.
### Keycloak
-The access_type parameter has two possible values: "online" and "offline." By default, the value is set to "offline". This means that when a user authenticates using OIDC, the application requests offline access to the user's resources, including the ability to refresh access tokens without requiring the user to reauthenticate.
+The access_type parameter has two possible values: "online" and "offline." By
+default, the value is set to "offline". This means that when a user
+authenticates using OIDC, the application requests offline access to the user's
+resources, including the ability to refresh access tokens without requiring the
+user to reauthenticate.
-To enable the `offline_access` scope, which allows for the refresh token functionality, you need to add it to the list of requested scopes during the authentication flow. Including the `offline_access` scope in the requested scopes ensures that the user is granted the necessary permissions to obtain refresh tokens.
+To enable the `offline_access` scope, which allows for the refresh token
+functionality, you need to add it to the list of requested scopes during the
+authentication flow. Including the `offline_access` scope in the requested
+scopes ensures that the user is granted the necessary permissions to obtain
+refresh tokens.
-By combining the `{"access_type":"offline"}` parameter in the OIDC Auth URL with the `offline_access` scope, you can achieve the desired behavior of obtaining refresh tokens for offline access to the user's resources.
+By combining the `{"access_type":"offline"}` parameter in the OIDC Auth URL with
+the `offline_access` scope, you can achieve the desired behavior of obtaining
+refresh tokens for offline access to the user's resources.
diff --git a/docs/admin/automation.md b/docs/admin/automation.md
index 18751755b4..c9fc788330 100644
--- a/docs/admin/automation.md
+++ b/docs/admin/automation.md
@@ -1,6 +1,8 @@
# Automation
-All actions possible through the Coder dashboard can also be automated as it utilizes the same public REST API. There are several ways to extend/automate Coder:
+All actions possible through the Coder dashboard can also be automated as it
+utilizes the same public REST API. There are several ways to extend/automate
+Coder:
- [CLI](../cli.md)
- [REST API](../api/)
@@ -10,13 +12,13 @@ All actions possible through the Coder dashboard can also be automated as it uti
Generate a token on your Coder deployment by visiting:
-```sh
+```shell
https://coder.example.com/settings/tokens
```
List your workspaces
-```sh
+```shell
# CLI
coder ls \
--url https://coder.example.com \
@@ -30,23 +32,34 @@ curl https://coder.example.com/api/v2/workspaces?q=owner:me \
## Documentation
-We publish an [API reference](../api/index.md) in our documentation. You can also enable a [Swagger endpoint](../cli/server.md#--swagger-enable) on your Coder deployment.
+We publish an [API reference](../api/index.md) in our documentation. You can
+also enable a [Swagger endpoint](../cli/server.md#--swagger-enable) on your
+Coder deployment.
## Use cases
-We strive to keep the following use cases up to date, but please note that changes to API queries and routes can occur. For the most recent queries and payloads, we recommend checking the CLI and API documentation.
+We strive to keep the following use cases up to date, but please note that
+changes to API queries and routes can occur. For the most recent queries and
+payloads, we recommend checking the CLI and API documentation.
### Templates
-- [Update templates in CI](../templates/change-management.md): Store all templates and git and update templates in CI/CD pipelines.
+- [Update templates in CI](../templates/change-management.md): Store all
+ templates and git and update templates in CI/CD pipelines.
### Workspace agents
-Workspace agents have a special token that can send logs, metrics, and workspace activity.
+Workspace agents have a special token that can send logs, metrics, and workspace
+activity.
-- [Custom workspace logs](../api/agents.md#patch-workspace-agent-logs): Expose messages prior to the Coder init script running (e.g. pulling image, VM starting, restoring snapshot). [coder-logstream-kube](https://github.com/coder/coder-logstream-kube) uses this to show Kubernetes events, such as image pulls or ResourceQuota restrictions.
+- [Custom workspace logs](../api/agents.md#patch-workspace-agent-logs): Expose
+ messages prior to the Coder init script running (e.g. pulling image, VM
+ starting, restoring snapshot).
+ [coder-logstream-kube](https://github.com/coder/coder-logstream-kube) uses
+ this to show Kubernetes events, such as image pulls or ResourceQuota
+ restrictions.
- ```sh
+ ```shell
curl -X PATCH https://coder.example.com/api/v2/workspaceagents/me/logs \
-H "Coder-Session-Token: $CODER_AGENT_TOKEN" \
-d "{
@@ -60,9 +73,11 @@ Workspace agents have a special token that can send logs, metrics, and workspace
}"
```
-- [Manually send workspace activity](../api/agents.md#submit-workspace-agent-stats): Keep a workspace "active," even if there is not an open connection (e.g. for a long-running machine learning job).
+- [Manually send workspace activity](../api/agents.md#submit-workspace-agent-stats):
+ Keep a workspace "active," even if there is not an open connection (e.g. for a
+ long-running machine learning job).
- ```sh
+ ```shell
#!/bin/bash
# Send workspace activity as long as the job is still running
diff --git a/docs/admin/configure.md b/docs/admin/configure.md
index 2240ef4ed5..17ce483cb2 100644
--- a/docs/admin/configure.md
+++ b/docs/admin/configure.md
@@ -1,23 +1,26 @@
-Coder server's primary configuration is done via environment variables. For a full list of the options, run `coder server --help` or see our [CLI documentation](../cli/server.md).
+Coder server's primary configuration is done via environment variables. For a
+full list of the options, run `coder server --help` or see our
+[CLI documentation](../cli/server.md).
## Access URL
-`CODER_ACCESS_URL` is required if you are not using the tunnel. Set this to the external URL
-that users and workspaces use to connect to Coder (e.g. ). This
-should not be localhost.
+`CODER_ACCESS_URL` is required if you are not using the tunnel. Set this to the
+external URL that users and workspaces use to connect to Coder (e.g.
+). This should not be localhost.
-> Access URL should be a external IP address or domain with DNS records pointing to Coder.
+> Access URL should be a external IP address or domain with DNS records pointing
+> to Coder.
### Tunnel
-If an access URL is not specified, Coder will create
-a publicly accessible URL to reverse proxy your deployment for simple setup.
+If an access URL is not specified, Coder will create a publicly accessible URL
+to reverse proxy your deployment for simple setup.
## Address
You can change which port(s) Coder listens on.
-```sh
+```shell
# Listen on port 80
export CODER_HTTP_ADDRESS=0.0.0.0:80
@@ -34,22 +37,27 @@ 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/index.md#coder-apps) on an absolute path. Set this to a wildcard
-subdomain that resolves to Coder (e.g. `*.coder.example.com`).
+`CODER_WILDCARD_ACCESS_URL` is necessary for
+[port forwarding](../networking/port-forwarding.md#dashboard) 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
1. Use a single certificate and key for both the root and wildcard domains.
2. Configure multiple certificates and keys via
- [`coder.tls.secretNames`](https://github.com/coder/coder/blob/main/helm/coder/values.yaml) in the Helm Chart, or
- [`--tls-cert-file`](../cli/server.md#--tls-cert-file) and [`--tls-key-file`](../cli/server.md#--tls-key-file) command
- line options (these both take a comma separated list of files; list certificates and their respective keys in the
- same order).
+ [`coder.tls.secretNames`](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
+ in the Helm Chart, or [`--tls-cert-file`](../cli/server.md#--tls-cert-file)
+ and [`--tls-key-file`](../cli/server.md#--tls-key-file) command line options
+ (these both take a comma separated list of files; list certificates and their
+ respective keys in the same order).
## TLS & Reverse Proxy
-The Coder server can directly use TLS certificates with `CODER_TLS_ENABLE` and accompanying configuration flags. However, Coder can also run behind a reverse-proxy to terminate TLS certificates from LetsEncrypt, for example.
+The Coder server can directly use TLS certificates with `CODER_TLS_ENABLE` and
+accompanying configuration flags. However, Coder can also run behind a
+reverse-proxy to terminate TLS certificates from LetsEncrypt, for example.
- [Apache](https://github.com/coder/coder/tree/main/examples/web-server/apache)
- [Caddy](https://github.com/coder/coder/tree/main/examples/web-server/caddy)
@@ -57,17 +65,19 @@ The Coder server can directly use TLS certificates with `CODER_TLS_ENABLE` and a
### Kubernetes TLS configuration
-Below are the steps to configure Coder to terminate TLS when running on Kubernetes.
-You must have the certificate `.key` and `.crt` files in your working directory prior to step 1.
+Below are the steps to configure Coder to terminate TLS when running on
+Kubernetes. You must have the certificate `.key` and `.crt` files in your
+working directory prior to step 1.
1. Create the TLS secret in your Kubernetes cluster
-```console
+```shell
kubectl create secret tls coder-tls -n --key="tls.key" --cert="tls.crt"
```
-> You can use a single certificate for the both the access URL and wildcard access URL.
-> The certificate CN must match the wildcard domain, such as `*.example.coder.com`.
+> You can use a single certificate for the both the access URL and wildcard
+> access URL. The certificate CN must match the wildcard domain, such as
+> `*.example.coder.com`.
1. Reference the TLS secret in your Coder Helm chart values
@@ -87,14 +97,16 @@ coder:
## PostgreSQL Database
-Coder uses a PostgreSQL database to store users, workspace metadata, and other deployment information.
-Use `CODER_PG_CONNECTION_URL` to set the database that Coder connects to. If unset, PostgreSQL binaries will be
-downloaded from Maven () and store all data in the config root.
+Coder uses a PostgreSQL database to store users, workspace metadata, and other
+deployment information. Use `CODER_PG_CONNECTION_URL` to set the database that
+Coder connects to. If unset, PostgreSQL binaries will be downloaded from Maven
+() and store all data in the config root.
> Postgres 13 is the minimum supported version.
If you are using the built-in PostgreSQL deployment and need to use `psql` (aka
-the PostgreSQL interactive terminal), output the connection URL with the following command:
+the PostgreSQL interactive terminal), output the connection URL with the
+following command:
```console
coder server postgres-builtin-url
@@ -103,21 +115,26 @@ psql "postgres://coder@localhost:49627/coder?sslmode=disable&password=feU...yI1"
### Migrating from the built-in database to an external database
-To migrate from the built-in database to an external database, follow these steps:
+To migrate from the built-in database to an external database, follow these
+steps:
1. Stop your Coder deployment.
2. Run `coder server postgres-builtin-serve` in a background terminal.
3. Run `coder server postgres-builtin-url` and copy its output command.
-4. Run `pg_dump > coder.sql` to dump the internal database to a file.
-5. Restore that content to an external database with `psql < coder.sql`.
-6. Start your Coder deployment with `CODER_PG_CONNECTION_URL=`.
+4. Run `pg_dump > coder.sql` to dump the internal
+ database to a file.
+5. Restore that content to an external database with
+ `psql < coder.sql`.
+6. Start your Coder deployment with
+ `CODER_PG_CONNECTION_URL=`.
## System packages
-If you've installed Coder via a [system package](../install/packages.md) Coder, you can
-configure the server by setting the following variables in `/etc/coder.d/coder.env`:
+If you've installed Coder via a [system package](../install/packages.md) Coder,
+you can configure the server by setting the following variables in
+`/etc/coder.d/coder.env`:
-```console
+```env
# String. Specifies the external URL (HTTP/S) to access Coder.
CODER_ACCESS_URL=https://coder.example.com
@@ -145,7 +162,7 @@ CODER_TLS_KEY_FILE=
To run Coder as a system service on the host:
-```console
+```shell
# Use systemd to start Coder now and on reboot
sudo systemctl enable --now coder
@@ -155,15 +172,15 @@ journalctl -u coder.service -b
To restart Coder after applying system changes:
-```console
+```shell
sudo systemctl restart coder
```
## Configuring Coder behind a proxy
-To configure Coder behind a corporate proxy, set the environment variables `HTTP_PROXY` and
-`HTTPS_PROXY`. Be sure to restart the server. Lowercase values (e.g. `http_proxy`) are also
-respected in this case.
+To configure Coder behind a corporate proxy, set the environment variables
+`HTTP_PROXY` and `HTTPS_PROXY`. Be sure to restart the server. Lowercase values
+(e.g. `http_proxy`) are also respected in this case.
## Up Next
diff --git a/docs/admin/git-providers.md b/docs/admin/git-providers.md
index 293c88ab3c..0cbd0e00c9 100644
--- a/docs/admin/git-providers.md
+++ b/docs/admin/git-providers.md
@@ -1,10 +1,13 @@
# Git Providers
-Coder integrates with git providers to automate away the need for developers to authenticate with repositories within their workspace.
+Coder integrates with git providers to automate away the need for developers to
+authenticate with repositories within their workspace.
## How it works
-When developers use `git` inside their workspace, they are prompted to authenticate. After that, Coder will store and refresh tokens for future operations.
+When developers use `git` inside their workspace, they are prompted to
+authenticate. After that, Coder will store and refresh tokens for future
+operations.
-Coder's provisioner process needs to authenticate with cloud provider APIs to provision
-workspaces. You can either pass credentials to the provisioner as parameters or execute Coder
-in an environment that is authenticated with the cloud provider.
+Coder's provisioner process needs to authenticate with cloud provider APIs to
+provision workspaces. You can either pass credentials to the provisioner as
+parameters or execute Coder in an environment that is authenticated with the
+cloud provider.
-We encourage the latter where supported. This approach simplifies the template, keeps cloud
-provider credentials out of Coder's database (making it a less valuable target for attackers),
-and is compatible with agent-based authentication schemes (that handle credential rotation
-and/or ensure the credentials are not written to disk).
+We encourage the latter where supported. This approach simplifies the template,
+keeps cloud provider credentials out of Coder's database (making it a less
+valuable target for attackers), and is compatible with agent-based
+authentication schemes (that handle credential rotation and/or ensure the
+credentials are not written to disk).
-Cloud providers for which the Terraform provider supports authenticated environments include
+Cloud providers for which the Terraform provider supports authenticated
+environments include
- [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs)
- [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
@@ -24,11 +27,11 @@ Cloud providers for which the Terraform provider supports authenticated environm
- [Kubernetes](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs)
Additional providers may be supported; check the
-[documentation of the Terraform provider](https://registry.terraform.io/browse/providers) for
-details.
+[documentation of the Terraform provider](https://registry.terraform.io/browse/providers)
+for details.
-The way these generally work is via the credentials being available to Coder either in some
-well-known location on disk (e.g. `~/.aws/credentials` for AWS on posix systems), or via
-environment variables. It is usually sufficient to authenticate using the CLI or SDK for the
-cloud provider before running Coder for this to work, but check the Terraform provider
-documentation for details.
+The way these generally work is via the credentials being available to Coder
+either in some well-known location on disk (e.g. `~/.aws/credentials` for AWS on
+posix systems), or via environment variables. It is usually sufficient to
+authenticate using the CLI or SDK for the cloud provider before running Coder
+for this to work, but check the Terraform provider documentation for details.
diff --git a/docs/templates/change-management.md b/docs/templates/change-management.md
index f2781d9ee0..6c4fecfa8d 100644
--- a/docs/templates/change-management.md
+++ b/docs/templates/change-management.md
@@ -1,6 +1,7 @@
# Template Change Management
-We recommend source controlling your templates as you would other code. [Install Coder](../install/) in CI/CD pipelines to push new template versions.
+We recommend source controlling your templates as you would other code.
+[Install Coder](../install/) in CI/CD pipelines to push new template versions.
```console
# Install the Coder CLI
@@ -26,7 +27,8 @@ coder templates push --yes $CODER_TEMPLATE_NAME \
--name=$CODER_TEMPLATE_VERSION # Version name is optional
```
-> Looking for an example? See how we push our development image
-> and template [via GitHub actions](https://github.com/coder/coder/blob/main/.github/workflows/dogfood.yaml).
+> Looking for an example? See how we push our development image and template
+> [via GitHub actions](https://github.com/coder/coder/blob/main/.github/workflows/dogfood.yaml).
-> To cap token lifetime on creation, [configure Coder server to set a shorter max token lifetime](../cli/server.md#--max-token-lifetime)
+> To cap token lifetime on creation,
+> [configure Coder server to set a shorter max token lifetime](../cli/server.md#--max-token-lifetime)
diff --git a/docs/templates/devcontainers.md b/docs/templates/devcontainers.md
index 3a92e79a90..10a107ca45 100644
--- a/docs/templates/devcontainers.md
+++ b/docs/templates/devcontainers.md
@@ -1,20 +1,32 @@
# Devcontainers (alpha)
-[Devcontainers](https://containers.dev) are an open source specification for defining development environments. [envbuilder](https://github.com/coder/envbuilder) is an open source project by Coder that runs devcontainers via Coder templates and your underlying infrastructure.
+[Devcontainers](https://containers.dev) are an open source specification for
+defining development environments.
+[envbuilder](https://github.com/coder/envbuilder) is an open source project by
+Coder that runs devcontainers via Coder templates and your underlying
+infrastructure.
-There are several benefits to adding a devcontainer-compatible template to Coder:
+There are several benefits to adding a devcontainer-compatible template to
+Coder:
-- Drop-in migration from Codespaces (or any existing repositories that use devcontainers)
+- Drop-in migration from Codespaces (or any existing repositories that use
+ devcontainers)
- Easier to start projects from Coder (new workspace, pick starter devcontainer)
-- Developer teams can "bring their own image." No need for platform teams to manage complex images, registries, and CI pipelines.
+- Developer teams can "bring their own image." No need for platform teams to
+ manage complex images, registries, and CI pipelines.
## How it works
-- Coder admins add a devcontainer-compatible template to Coder (envbuilder can run on Docker or Kubernetes)
+- Coder admins add a devcontainer-compatible template to Coder (envbuilder can
+ run on Docker or Kubernetes)
-- Developers enter their repository URL as a [parameter](./parameters.md) when they create their workspace. [envbuilder](https://github.com/coder/envbuilder) clones the repo and builds a container from the `devcontainer.json` specified in the repo.
+- Developers enter their repository URL as a [parameter](./parameters.md) when
+ they create their workspace. [envbuilder](https://github.com/coder/envbuilder)
+ clones the repo and builds a container from the `devcontainer.json` specified
+ in the repo.
-- Developers can edit the `devcontainer.json` in their workspace to rebuild to iterate on their development environments.
+- Developers can edit the `devcontainer.json` in their workspace to rebuild to
+ iterate on their development environments.
## Example templates
@@ -23,16 +35,24 @@ There are several benefits to adding a devcontainer-compatible template to Coder
![Devcontainer parameter screen](../images/templates/devcontainers.png)
-[Parameters](./parameters.md) can be used to prompt the user for a repo URL when they are creating a workspace.
+[Parameters](./parameters.md) can be used to prompt the user for a repo URL when
+they are creating a workspace.
## Authentication
-You may need to authenticate to your container registry (e.g. Artifactory) or git provider (e.g. GitLab) to use envbuilder. Refer to the [envbuilder documentation](https://github.com/coder/envbuilder/) for more information.
+You may need to authenticate to your container registry (e.g. Artifactory) or
+git provider (e.g. GitLab) to use envbuilder. Refer to the
+[envbuilder documentation](https://github.com/coder/envbuilder/) for more
+information.
## Caching
-To improve build times, devcontainers can be cached. Refer to the [envbuilder documentation](https://github.com/coder/envbuilder/) for more information.
+To improve build times, devcontainers can be cached. Refer to the
+[envbuilder documentation](https://github.com/coder/envbuilder/) for more
+information.
## Other features & known issues
-Envbuilder is still under active development. Refer to the [envbuilder GitHub repo](https://github.com/coder/envbuilder/) for more information and to submit feature requests.
+Envbuilder is still under active development. Refer to the
+[envbuilder GitHub repo](https://github.com/coder/envbuilder/) for more
+information and to submit feature requests.
diff --git a/docs/templates/docker-in-workspaces.md b/docs/templates/docker-in-workspaces.md
index 84198794bd..24357d771f 100644
--- a/docs/templates/docker-in-workspaces.md
+++ b/docs/templates/docker-in-workspaces.md
@@ -11,13 +11,21 @@ There are a few ways to run Docker within container-based Coder workspaces.
## Sysbox container runtime
-The [Sysbox](https://github.com/nestybox/sysbox) container runtime allows unprivileged users to run system-level applications, such as Docker, securely from the workspace containers. Sysbox requires a [compatible Linux distribution](https://github.com/nestybox/sysbox/blob/master/docs/distro-compat.md) to implement these security features. Sysbox can also be used to run systemd inside Coder workspaces. See [Systemd in Docker](#systemd-in-docker).
+The [Sysbox](https://github.com/nestybox/sysbox) container runtime allows
+unprivileged users to run system-level applications, such as Docker, securely
+from the workspace containers. Sysbox requires a
+[compatible Linux distribution](https://github.com/nestybox/sysbox/blob/master/docs/distro-compat.md)
+to implement these security features. Sysbox can also be used to run systemd
+inside Coder workspaces. See [Systemd in Docker](#systemd-in-docker).
-The Sysbox container runtime is not compatible with our [workspace process logging](./process-logging.md) feature. Envbox is compatible with process logging, however.
+The Sysbox container runtime is not compatible with our
+[workspace process logging](./process-logging.md) feature. Envbox is compatible
+with process logging, however.
### Use Sysbox in Docker-based templates
-After [installing Sysbox](https://github.com/nestybox/sysbox#installation) on the Coder host, modify your template to use the sysbox-runc runtime:
+After [installing Sysbox](https://github.com/nestybox/sysbox#installation) on
+the Coder host, modify your template to use the sysbox-runc runtime:
```hcl
resource "docker_container" "workspace" {
@@ -46,7 +54,10 @@ resource "coder_agent" "main" {
### Use Sysbox in Kubernetes-based templates
-After [installing Sysbox on Kubernetes](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/install-k8s.md), modify your template to use the sysbox-runc RuntimeClass. This requires the Kubernetes Terraform provider version 2.16.0 or greater.
+After
+[installing Sysbox on Kubernetes](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/install-k8s.md),
+modify your template to use the sysbox-runc RuntimeClass. This requires the
+Kubernetes Terraform provider version 2.16.0 or greater.
```hcl
terraform {
@@ -111,15 +122,20 @@ resource "kubernetes_pod" "dev" {
}
```
-> Sysbox CE (Community Edition) supports a maximum of 16 pods (workspaces) per node on Kubernetes. See the [Sysbox documentation](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/install-k8s.md#limitations) for more details.
+> Sysbox CE (Community Edition) supports a maximum of 16 pods (workspaces) per
+> node on Kubernetes. See the
+> [Sysbox documentation](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/install-k8s.md#limitations)
+> for more details.
## Envbox
-[Envbox](https://github.com/coder/envbox) is an image developed and maintained by Coder that bundles the sysbox runtime. It works
-by starting an outer container that manages the various sysbox daemons and spawns an unprivileged
-inner container that acts as the user's workspace. The inner container is able to run system-level
-software similar to a regular virtual machine (e.g. `systemd`, `dockerd`, etc). Envbox offers the
-following benefits over running sysbox directly on the nodes:
+[Envbox](https://github.com/coder/envbox) is an image developed and maintained
+by Coder that bundles the sysbox runtime. It works by starting an outer
+container that manages the various sysbox daemons and spawns an unprivileged
+inner container that acts as the user's workspace. The inner container is able
+to run system-level software similar to a regular virtual machine (e.g.
+`systemd`, `dockerd`, etc). Envbox offers the following benefits over running
+sysbox directly on the nodes:
- No custom runtime installation or management on your Kubernetes nodes.
- No limit to the number of pods that run envbox.
@@ -127,27 +143,37 @@ following benefits over running sysbox directly on the nodes:
Some drawbacks include:
- The outer container must be run as privileged
- - Note: the inner container is _not_ privileged. For more information on the security of sysbox
- containers see sysbox's [official documentation](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/security.md).
-- Initial workspace startup is slower than running `sysbox-runc` directly on the nodes. This is due
- to `envbox` having to pull the image to its own Docker cache on its initial startup. Once the image
- is cached in `envbox`, startup performance is similar.
+ - Note: the inner container is _not_ privileged. For more information on the
+ security of sysbox containers see sysbox's
+ [official documentation](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/security.md).
+- Initial workspace startup is slower than running `sysbox-runc` directly on the
+ nodes. This is due to `envbox` having to pull the image to its own Docker
+ cache on its initial startup. Once the image is cached in `envbox`, startup
+ performance is similar.
-Envbox requires the same kernel requirements as running sysbox directly on the nodes. Refer
-to sysbox's [compatibility matrix](https://github.com/nestybox/sysbox/blob/master/docs/distro-compat.md#sysbox-distro-compatibility) to ensure your nodes are compliant.
+Envbox requires the same kernel requirements as running sysbox directly on the
+nodes. Refer to sysbox's
+[compatibility matrix](https://github.com/nestybox/sysbox/blob/master/docs/distro-compat.md#sysbox-distro-compatibility)
+to ensure your nodes are compliant.
-To get started with `envbox` check out the [starter template](https://github.com/coder/coder/tree/main/examples/templates/envbox) or visit the [repo](https://github.com/coder/envbox).
+To get started with `envbox` check out the
+[starter template](https://github.com/coder/coder/tree/main/examples/templates/envbox)
+or visit the [repo](https://github.com/coder/envbox).
### Authenticating with a Private Registry
-Authenticating with a private container registry can be done by referencing the credentials
-via the `CODER_IMAGE_PULL_SECRET` environment variable. It is encouraged to populate this
-[environment variable](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#define-container-environment-variables-using-secret-data) by using a Kubernetes [secret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#registry-secret-existing-credentials).
+Authenticating with a private container registry can be done by referencing the
+credentials via the `CODER_IMAGE_PULL_SECRET` environment variable. It is
+encouraged to populate this
+[environment variable](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#define-container-environment-variables-using-secret-data)
+by using a Kubernetes
+[secret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#registry-secret-existing-credentials).
-Refer to your container registry documentation to understand how to best create this secret.
+Refer to your container registry documentation to understand how to best create
+this secret.
-The following shows a minimal example using a the JSON API key from a GCP service account to pull
-a private image:
+The following shows a minimal example using a the JSON API key from a GCP
+service account to pull a private image:
```bash
# Create the secret
@@ -172,17 +198,22 @@ env {
## Rootless podman
-[Podman](https://docs.podman.io/en/latest/) is Docker alternative that is compatible with OCI containers specification. which can run rootless inside Kubernetes pods. No custom RuntimeClass is required.
+[Podman](https://docs.podman.io/en/latest/) is Docker alternative that is
+compatible with OCI containers specification. which can run rootless inside
+Kubernetes pods. No custom RuntimeClass is required.
-Prior to completing the steps below, please review the following Podman documentation:
+Prior to completing the steps below, please review the following Podman
+documentation:
- [Basic setup and use of Podman in a rootless environment](https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md)
- [Shortcomings of Rootless Podman](https://github.com/containers/podman/blob/main/rootless.md#shortcomings-of-rootless-podman)
-1. Enable [smart-device-manager](https://gitlab.com/arm-research/smarter/smarter-device-manager#enabling-access) to securely expose a FUSE devices to pods.
+1. Enable
+ [smart-device-manager](https://gitlab.com/arm-research/smarter/smarter-device-manager#enabling-access)
+ to securely expose a FUSE devices to pods.
- ```sh
+ ```shell
cat < ⚠️ **Warning**: If you are using a managed Kubernetes distribution (e.g. AKS, EKS, GKE), be sure to set node labels via your cloud provider. Otherwise, your nodes may drop the labels and break podman functionality.
+ > ⚠️ **Warning**: If you are using a managed Kubernetes distribution (e.g.
+ > AKS, EKS, GKE), be sure to set node labels via your cloud provider.
+ > Otherwise, your nodes may drop the labels and break podman functionality.
-3. For systems running SELinux (typically Fedora-, CentOS-, and Red Hat-based systems), you may need to disable SELinux or set it to permissive mode.
+3. For systems running SELinux (typically Fedora-, CentOS-, and Red Hat-based
+ systems), you may need to disable SELinux or set it to permissive mode.
-4. Import our [kubernetes-with-podman](https://github.com/coder/coder/tree/main/examples/templates/kubernetes-with-podman) example template, or make your own.
+4. Import our
+ [kubernetes-with-podman](https://github.com/coder/coder/tree/main/examples/templates/kubernetes-with-podman)
+ example template, or make your own.
- ```sh
+ ```shell
echo "kubernetes-with-podman" | coder templates init
cd ./kubernetes-with-podman
coder templates create
```
- > For more information around the requirements of rootless podman pods, see: [How to run Podman inside of Kubernetes](https://www.redhat.com/sysadmin/podman-inside-kubernetes)
+ > For more information around the requirements of rootless podman pods, see:
+ > [How to run Podman inside of Kubernetes](https://www.redhat.com/sysadmin/podman-inside-kubernetes)
## Privileged sidecar container
-A [privileged container](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) can be added to your templates to add docker support. This may come in handy if your nodes cannot run Sysbox.
+A
+[privileged container](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)
+can be added to your templates to add docker support. This may come in handy if
+your nodes cannot run Sysbox.
-> ⚠️ **Warning**: This is insecure. Workspaces will be able to gain root access to the host machine.
+> ⚠️ **Warning**: This is insecure. Workspaces will be able to gain root access
+> to the host machine.
### Use a privileged sidecar container in Docker-based templates
@@ -347,10 +388,13 @@ resource "kubernetes_pod" "main" {
## Systemd in Docker
-Additionally, [Sysbox](https://github.com/nestybox/sysbox) can be used to give workspaces full `systemd` capabilities.
+Additionally, [Sysbox](https://github.com/nestybox/sysbox) can be used to give
+workspaces full `systemd` capabilities.
-After [installing Sysbox on Kubernetes](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/install-k8s.md),
-modify your template to use the sysbox-runc RuntimeClass. This requires the Kubernetes Terraform provider version 2.16.0 or greater.
+After
+[installing Sysbox on Kubernetes](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/install-k8s.md),
+modify your template to use the sysbox-runc RuntimeClass. This requires the
+Kubernetes Terraform provider version 2.16.0 or greater.
```hcl
terraform {
diff --git a/docs/templates/index.md b/docs/templates/index.md
index c9a3a455be..1cd7c5786f 100644
--- a/docs/templates/index.md
+++ b/docs/templates/index.md
@@ -4,9 +4,10 @@ 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.
+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
@@ -16,13 +17,13 @@ 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
+```shell
curl -fsSL https://coder.com/install.sh | sh
```
To see the sub-commands for managing templates, run:
-```console
+```shell
coder templates --help
```
@@ -31,7 +32,7 @@ coder templates --help
Before you can create templates, you must first login to your Coder deployment
with the CLI.
-```console
+```shell
coder login https://coder.example.com # aka the URL to your coder instance
```
@@ -41,7 +42,7 @@ 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
+```shell
coder --token login https://coder.example.com/ # aka the URL to your coder instance
```
@@ -49,7 +50,7 @@ coder --token login https://coder.example.com/ # aka the URL to y
Before users can create workspaces, you'll need at least one template in Coder.
-```sh
+```shell
# create a local directory to store templates
mkdir -p $HOME/coder/templates
cd $HOME/coder/templates
@@ -74,7 +75,7 @@ coder templates create
To control cost, specify a maximum time to live flag for a template in hours or
minutes.
-```sh
+```shell
coder templates create my-template --default-ttl 4h
```
@@ -83,28 +84,35 @@ coder templates create my-template --default-ttl 4h
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).
+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
+- 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.
+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).
+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.
+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
@@ -139,9 +147,10 @@ resource "kubernetes_pod" "pod1" {
}
```
-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
+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`.
@@ -151,14 +160,17 @@ 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.
-This allows users to access the workspace before the script completes.
-If you want to change this, see [`startup_script_behavior`](#startup_script_behavior) below.
+**Note:** By default, the startup script is executed in the background. This
+allows users to access the workspace before the script completes. If you want to
+change this, see [`startup_script_behavior`](#startup_script_behavior) below.
-Here are a few guidelines for writing a good startup script (more on these below):
+Here are a few guidelines for writing a good startup script (more on these
+below):
-1. Use `set -e` to exit the script if any command fails and `|| true` for commands that are allowed to fail
-2. Use `&` to start a process in the background, allowing the startup script to complete
+1. Use `set -e` to exit the script if any command fails and `|| true` for
+ commands that are allowed to fail
+2. Use `&` to start a process in the background, allowing the startup script to
+ complete
3. Inform the user about what's going on via `echo`
```hcl
@@ -198,17 +210,41 @@ 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. 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.
+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 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.
+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.
+> **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.
-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.
+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.
+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.
```hcl
resource "coder_agent" "coder" {
@@ -218,7 +254,10 @@ resource "coder_agent" "coder" {
startup_script = "echo 'Starting...'"
```
-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. The behavior can be overridden by one of the following means:
+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. The behavior can be overridden by one of the
+following means:
- Set an environment variable (for use with `ssh` or `coder ssh`):
- `export CODER_SSH_WAIT=yes` (blocking)
@@ -236,8 +275,9 @@ Whichever behavior is enabled, the user can still choose to override it by speci
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.
+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).
@@ -278,7 +318,7 @@ 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
+```hcl
resource "kubernetes_pod" "podName" {
spec {
container {
@@ -290,17 +330,23 @@ resource "kubernetes_pod" "podName" {
### 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.
+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.
+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.
+> **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
+```shell
coder templates edit --description "This is my template"
```
@@ -309,20 +355,20 @@ 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
+```shell
coder templates pull file.tar
```
Then, extract it by running:
-```sh
+```shell
tar -xf file.tar
```
Make the changes to your template then run this command from the root of the
template folder:
-```console
+```shell
coder templates push
```
@@ -331,14 +377,14 @@ 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.
+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
+```shell
coder templates delete
```
@@ -349,9 +395,9 @@ in the right-hand corner of the page to delete the template.
#### 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.
+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)
@@ -368,14 +414,17 @@ 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.
+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)
+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
+```hcl
resource "coder_agent" "main" {
# ...
env = {
@@ -393,12 +442,14 @@ 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)
+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)
+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
@@ -410,33 +461,78 @@ 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)
+- 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)
+ - 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](../admin/configure.md#tls--reverse-proxy)
### Startup script issues
-Depending on the contents of the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script), and whether or not the [startup script behavior](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script_behavior) is set to blocking or non-blocking, you may notice issues related to the startup script. In this section we will cover common scenarios and how to resolve them.
+Depending on the contents of the
+[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script),
+and whether or not the
+[startup script behavior](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script_behavior)
+is set to blocking or non-blocking, you may notice issues related to the startup
+script. In this section we will cover common scenarios and how to resolve them.
#### Unable to access workspace, startup script is still running
-If you're trying to access your workspace and are unable to because the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) is still running, it means the [startup script behavior](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script_behavior) option is set to blocking or you have enabled the `--wait=yes` option (for e.g. `coder ssh` or `coder config-ssh`). In such an event, you can always access the workspace by using the web terminal, or via SSH using the `--wait=no` option. If the startup script is running longer than it should, or never completing, you can try to [debug the startup script](#debugging-the-startup-script) to resolve the issue. Alternatively, you can try to force the startup script to exit by terminating processes started by it or terminating the startup script itself (on Linux, `ps` and `kill` are useful tools).
+If you're trying to access your workspace and are unable to because the
+[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)
+is still running, it means the
+[startup script behavior](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script_behavior)
+option is set to blocking or you have enabled the `--wait=yes` option (for e.g.
+`coder ssh` or `coder config-ssh`). In such an event, you can always access the
+workspace by using the web terminal, or via SSH using the `--wait=no` option. If
+the startup script is running longer than it should, or never completing, you
+can try to [debug the startup script](#debugging-the-startup-script) to resolve
+the issue. Alternatively, you can try to force the startup script to exit by
+terminating processes started by it or terminating the startup script itself (on
+Linux, `ps` and `kill` are useful tools).
-For tips on how to write a startup script that doesn't run forever, see the [`startup_script`](#startup_script) section. For more ways to override the startup script behavior, see the [`startup_script_behavior`](#startup_script_behavior) section.
+For tips on how to write a startup script that doesn't run forever, see the
+[`startup_script`](#startup_script) section. For more ways to override the
+startup script behavior, see the
+[`startup_script_behavior`](#startup_script_behavior) section.
-Template authors can also set the [startup script behavior](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script_behavior) option to non-blocking, which will allow users to access the workspace while the startup script is still running. Note that the workspace must be updated after changing this option.
+Template authors can also set the
+[startup script behavior](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script_behavior)
+option to non-blocking, which will allow users to access the workspace while the
+startup script is still running. Note that the workspace must be updated after
+changing this option.
#### Your workspace may be incomplete
-If you see a warning that your workspace may be incomplete, it means you should be aware that programs, files, or settings may be missing from your workspace. This can happen if 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 (see [startup script error](#startup-script-error)). No action is necessary, but you may want to [start a new shell session](#session-was-started-before-the-startup-script-finished-web-terminal) after it has completed or check the [startup script logs](#debugging-the-startup-script) to see if there are any issues.
+If you see a warning that your workspace may be incomplete, it means you should
+be aware that programs, files, or settings may be missing from your workspace.
+This can happen if 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 (see
+[startup script error](#startup-script-error)). No action is necessary, but you
+may want to
+[start a new shell session](#session-was-started-before-the-startup-script-finished-web-terminal)
+after it has completed or check the
+[startup script logs](#debugging-the-startup-script) to see if there are any
+issues.
#### Session was started before the startup script finished
-The web terminal may show this message if it was started before the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) finished, but the startup script has since finished. This message can safely be dismissed, however, be aware that your preferred shell or dotfiles may not yet be activated for this shell session. You can either start a new session or source your dotfiles manually. Note that starting a new session means that commands running in the terminal will be terminated and you may lose unsaved work.
+The web terminal may show this message if it was started before the
+[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)
+finished, but the startup script has since finished. This message can safely be
+dismissed, however, be aware that your preferred shell or dotfiles may not yet
+be activated for this shell session. You can either start a new session or
+source your dotfiles manually. Note that starting a new session means that
+commands running in the terminal will be terminated and you may lose unsaved
+work.
Examples for activating your preferred shell or sourcing your dotfiles:
@@ -445,7 +541,15 @@ Examples for activating your preferred shell or sourcing your dotfiles:
#### Startup script exited with an error
-When the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) exits with an error, it means the last command run by the script failed. When `set -e` is used, this means that any failing command will immediately exit the script and the remaining commands will not be executed. This also means that [your workspace may be incomplete](#your-workspace-may-be-incomplete). If you see this error, you can check the [startup script logs](#debugging-the-startup-script) to figure out what the issue is.
+When the
+[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)
+exits with an error, it means the last command run by the script failed. When
+`set -e` is used, this means that any failing command will immediately exit the
+script and the remaining commands will not be executed. This also means that
+[your workspace may be incomplete](#your-workspace-may-be-incomplete). If you
+see this error, you can check the
+[startup script logs](#debugging-the-startup-script) to figure out what the
+issue is.
Common causes for startup script errors:
@@ -455,11 +559,20 @@ Common causes for startup script errors:
#### Debugging the startup script
-The simplest way to debug the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) is to open the workspace in the Coder dashboard and click "Show startup log" (if not already visible). This will show all the output from the script. Another option is to view the log file inside the workspace (usually `/tmp/coder-startup-script.log`). If the logs don't indicate what's going on or going wrong, you can increase verbosity by adding `set -x` to the top of the startup script (note that this will show all commands run and may output sensitive information). Alternatively, you can add `echo` statements to show what's going on.
+The simplest way to debug the
+[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)
+is to open the workspace in the Coder dashboard and click "Show startup log" (if
+not already visible). This will show all the output from the script. Another
+option is to view the log file inside the workspace (usually
+`/tmp/coder-startup-script.log`). If the logs don't indicate what's going on or
+going wrong, you can increase verbosity by adding `set -x` to the top of the
+startup script (note that this will show all commands run and may output
+sensitive information). Alternatively, you can add `echo` statements to show
+what's going on.
Here's a short example of an informative startup script:
-```sh
+```shell
echo "Running startup script..."
echo "Run: long-running-command"
/path/to/long-running-command
@@ -471,9 +584,13 @@ if [ $status -ne 0 ]; then
fi
```
-> **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.
+> **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.
+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)
diff --git a/docs/templates/modules.md b/docs/templates/modules.md
index a2f5e6c425..070e1d06cd 100644
--- a/docs/templates/modules.md
+++ b/docs/templates/modules.md
@@ -1,8 +1,12 @@
# Template inheritance
-In instances where you want to reuse code across different Coder templates, such as common scripts or resource definitions, we suggest using [Terraform Modules](https://developer.hashicorp.com/terraform/language/modules).
+In instances where you want to reuse code across different Coder templates, such
+as common scripts or resource definitions, we suggest using
+[Terraform Modules](https://developer.hashicorp.com/terraform/language/modules).
-These modules can be stored externally from Coder, like in a Git repository or a Terraform registry. Below is an example of how to reference a module in your template:
+These modules can be stored externally from Coder, like in a Git repository or a
+Terraform registry. Below is an example of how to reference a module in your
+template:
```hcl
data "coder_workspace" "me" {}
@@ -25,36 +29,52 @@ resource "coder_agent" "dev" {
}
```
-> Learn more about [creating modules](https://developer.hashicorp.com/terraform/language/modules) and [module sources](https://developer.hashicorp.com/terraform/language/modules/sources) in the Terraform documentation.
+> Learn more about
+> [creating modules](https://developer.hashicorp.com/terraform/language/modules)
+> and
+> [module sources](https://developer.hashicorp.com/terraform/language/modules/sources)
+> in the Terraform documentation.
## Git authentication
-If you are importing a module from a private git repository, the Coder server [or provisioner](../admin/provisioners.md) needs git credentials. Since this token will only be used for cloning your repositories with modules, it is best to create a token with limited access to repositories and no extra permissions. In GitHub, you can generate a [fine-grained token](https://docs.github.com/en/rest/overview/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28) with read only access to repos.
+If you are importing a module from a private git repository, the Coder server
+[or provisioner](../admin/provisioners.md) needs git credentials. Since this
+token will only be used for cloning your repositories with modules, it is best
+to create a token with limited access to repositories and no extra permissions.
+In GitHub, you can generate a
+[fine-grained token](https://docs.github.com/en/rest/overview/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28)
+with read only access to repos.
-If you are running Coder on a VM, make sure you have `git` installed and the `coder` user has access to the following files
+If you are running Coder on a VM, make sure you have `git` installed and the
+`coder` user has access to the following files
-```sh
+```toml
# /home/coder/.gitconfig
[credential]
helper = store
```
-```sh
+```toml
# /home/coder/.git-credentials
# GitHub example:
https://your-github-username:your-github-pat@github.com
```
-If you are running Coder on Docker or Kubernetes, `git` is pre-installed in the Coder image. However, you still need to mount credentials. This can be done via a Docker volume mount or Kubernetes secrets.
+If you are running Coder on Docker or Kubernetes, `git` is pre-installed in the
+Coder image. However, you still need to mount credentials. This can be done via
+a Docker volume mount or Kubernetes secrets.
### Passing git credentials in Kubernetes
-First, create a `.gitconfig` and `.git-credentials` file on your local machine. You may want to do this in a temporary directory to avoid conflicting with your own git credentials.
+First, create a `.gitconfig` and `.git-credentials` file on your local machine.
+You may want to do this in a temporary directory to avoid conflicting with your
+own git credentials.
-Next, create the secret in Kubernetes. Be sure to do this in the same namespace that Coder is installed in.
+Next, create the secret in Kubernetes. Be sure to do this in the same namespace
+that Coder is installed in.
-```sh
+```shell
export NAMESPACE=coder
kubectl apply -f - <