synced/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2025-03-14 10:09:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): update docs for correct use of shell and console and enforce linewidth (#9245)

Browse Source
This commit is contained in:
Muhammad Atif Ali
2023-08-23 12:27:57 +03:00
committed by GitHub
parent ed2b1236c0
commit d37f6d80f7
96 changed files with 2838 additions and 1457 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
.prettierrc.yaml
View File

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

2
README.md
View File

@ -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 deployment<sup>1</sup> with a single command:
```console
```shell
# Automatically sets up an external access URL on *.try.coder.app
coder server

86
SECURITY.md
View File

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

139
docs/CONTRIBUTING.md
View File

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

33
docs/about/architecture.md
View File

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

19
docs/admin/app-logs.md
View File

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

12
docs/admin/appearance.md
View File

@ -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 <yamlFile>`
flag to `coder server`.
Custom links can be set in the deployment configuration using the
`-c <yamlFile>` 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)

40
docs/admin/audit-logs.md
View File

@ -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=<nil> UserAgent=<nil> 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)

239
docs/admin/auth.md
View File

@ -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 <release-name> coder-v2/coder -n <namespace> -f values.yaml
```
@ -86,7 +94,8 @@ helm upgrade <release-name> coder-v2/coder -n <namespace> -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 <release-name> coder-v2/coder -n <namespace> -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 '<oidc_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.

37
docs/admin/automation.md
View File

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

91
docs/admin/configure.md
View File

@ -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. <https://coder.example.com>). 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.
<https://coder.example.com>). 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 <coder-namespace> --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 (<https://repo1.maven.org/maven2>) 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
(<https://repo1.maven.org/maven2>) 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 <built-in-connection-string> > coder.sql` to dump the internal database to a file.
5. Restore that content to an external database with `psql <external-connection-string> < coder.sql`.
6. Start your Coder deployment with `CODER_PG_CONNECTION_URL=<external-connection-string>`.
4. Run `pg_dump <built-in-connection-string> > coder.sql` to dump the internal
database to a file.
5. Restore that content to an external database with
`psql <external-connection-string> < coder.sql`.
6. Start your Coder deployment with
`CODER_PG_CONNECTION_URL=<external-connection-string>`.
## 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

65
docs/admin/git-providers.md
View File

@ -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.
<video autoplay playsinline loop>
<source src="https://github.com/coder/coder/blob/main/site/static/gitauth.mp4?raw=true" type="video/mp4">
@ -13,18 +16,22 @@ Your browser does not support the video tag.
## Configuration
To add a git provider, you'll need to create an OAuth application. The following providers are supported:
To add a git provider, you'll need to create an OAuth application. The following
providers are supported:
- [GitHub](#github-app)
- [GitLab](https://docs.gitlab.com/ee/integration/oauth_provider.html)
- [BitBucket](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/)
- [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops)
Example callback URL: `https://coder.example.com/gitauth/primary-github/callback`. Use an arbitrary ID for your provider (e.g. `primary-github`).
Example callback URL:
`https://coder.example.com/gitauth/primary-github/callback`. Use an arbitrary ID
for your provider (e.g. `primary-github`).
Set the following environment variables to [configure the Coder server](./configure.md):
Set the following environment variables to
[configure the Coder server](./configure.md):
```console
```env
CODER_GITAUTH_0_ID="primary-github"
CODER_GITAUTH_0_TYPE=github|gitlab|azure-devops|bitbucket
CODER_GITAUTH_0_CLIENT_ID=xxxxxx
@ -33,11 +40,15 @@ CODER_GITAUTH_0_CLIENT_SECRET=xxxxxxx
### GitHub
1. [Create a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) to enable fine-grained access to specific repositories, or a subset of permissions for security.
1. [Create a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)
to enable fine-grained access to specific repositories, or a subset of
permissions for security.
![Register GitHub App](../images/admin/github-app-register.png)
2. Adjust the GitHub App permissions. You can use more or less permissions than are listed here, this is merely a suggestion that allows users to clone repositories:
2. Adjust the GitHub App permissions. You can use more or less permissions than
are listed here, this is merely a suggestion that allows users to clone
repositories:
![Adjust GitHub App Permissions](../images/admin/github-app-permissions.png)
@ -48,7 +59,8 @@ CODER_GITAUTH_0_CLIENT_SECRET=xxxxxxx
| Workflows | Read & Write | Grants access to update files in `.github/workflows/`. |
| Metadata | Read-only | Grants access to metadata written by GitHub Apps. |
3. Install the App for your organization. You may select a subset of repositories to grant access to.
3. Install the App for your organization. You may select a subset of
repositories to grant access to.
![Install GitHub App](../images/admin/github-app-install.png)
@ -56,7 +68,7 @@ CODER_GITAUTH_0_CLIENT_SECRET=xxxxxxx
GitHub Enterprise requires the following authentication and token URLs:
```console
```env
CODER_GITAUTH_0_VALIDATE_URL="https://github.example.com/login/oauth/access_token/info"
CODER_GITAUTH_0_AUTH_URL="https://github.example.com/login/oauth/authorize"
CODER_GITAUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token"
@ -66,7 +78,7 @@ CODER_GITAUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token"
Azure DevOps requires the following environment variables:
```console
```env
CODER_GITAUTH_0_ID="primary-azure-devops"
CODER_GITAUTH_0_TYPE=azure-devops
CODER_GITAUTH_0_CLIENT_ID=xxxxxx
@ -78,10 +90,10 @@ CODER_GITAUTH_0_TOKEN_URL="https://app.vssps.visualstudio.com/oauth2/token"
### Self-managed git providers
Custom authentication and token URLs should be
used for self-managed Git provider deployments.
Custom authentication and token URLs should be used for self-managed Git
provider deployments.
```console
```env
CODER_GITAUTH_0_AUTH_URL="https://github.example.com/oauth/authorize"
CODER_GITAUTH_0_TOKEN_URL="https://github.example.com/oauth/token"
CODER_GITAUTH_0_VALIDATE_URL="https://your-domain.com/oauth/token/info"
@ -91,7 +103,7 @@ CODER_GITAUTH_0_VALIDATE_URL="https://your-domain.com/oauth/token/info"
Optionally, you can request custom scopes:
```console
```env
CODER_GITAUTH_0_SCOPES="repo:read repo:write write:gpg_key"
```
@ -99,9 +111,10 @@ CODER_GITAUTH_0_SCOPES="repo:read repo:write write:gpg_key"
Multiple providers are an Enterprise feature. [Learn more](../enterprise.md).
A custom regex can be used to match a specific repository or organization to limit auth scope. Here's a sample config:
A custom regex can be used to match a specific repository or organization to
limit auth scope. Here's a sample config:
```console
```env
# Provider 1) github.com
CODER_GITAUTH_0_ID=primary-github
CODER_GITAUTH_0_TYPE=github
@ -120,20 +133,24 @@ CODER_GITAUTH_1_TOKEN_URL="https://github.example.com/login/oauth/access_token"
CODER_GITAUTH_1_VALIDATE_URL="https://github.example.com/login/oauth/access_token/info"
```
To support regex matching for paths (e.g. github.com/orgname), you'll need to add this to the [Coder agent startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script):
To support regex matching for paths (e.g. github.com/orgname), you'll need to
add this to the
[Coder agent startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script):
```console
```shell
git config --global credential.useHttpPath true
```
## Require git authentication in templates
If your template requires git authentication (e.g. running `git clone` in the [startup_script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)), you can require users authenticate via git prior to creating a workspace:
If your template requires git authentication (e.g. running `git clone` in the
[startup_script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)),
you can require users authenticate via git prior to creating a workspace:
![Git authentication in template](../images/admin/git-auth-template.png)
The following example will require users authenticate via GitHub and auto-clone a repo
into the `~/coder` directory.
The following example will require users authenticate via GitHub and auto-clone
a repo into the `~/coder` directory.
```hcl
data "coder_git_auth" "github" {
@ -156,4 +173,6 @@ EOF
}
```
See the [Terraform provider documentation](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/git_auth) for all available options.
See the
[Terraform provider documentation](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/git_auth)
for all available options.

7
docs/admin/groups.md
View File

@ -1,9 +1,12 @@
# Groups
Groups can be used with [template RBAC](./rbac.md) to give groups of users access to specific templates. They can be defined in Coder or [synced from your identity provider](./auth.md#group-sync-enterprise).
Groups can be used with [template RBAC](./rbac.md) to give groups of users
access to specific templates. They can be defined in Coder or
[synced from your identity provider](./auth.md#group-sync-enterprise).
![Groups](../images/groups.png)
## 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)

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

@ -1,35 +1,41 @@
# High Availability
High Availability (HA) mode solves for horizontal scalability and automatic failover
within a single region. When in HA mode, Coder continues using a single Postgres
endpoint. [GCP](https://cloud.google.com/sql/docs/postgres/high-availability), [AWS](https://docs.aws.amazon.com/prescriptive-guidance/latest/saas-multitenant-managed-postgresql/availability.html),
High Availability (HA) mode solves for horizontal scalability and automatic
failover within a single region. When in HA mode, Coder continues using a single
Postgres endpoint.
[GCP](https://cloud.google.com/sql/docs/postgres/high-availability),
[AWS](https://docs.aws.amazon.com/prescriptive-guidance/latest/saas-multitenant-managed-postgresql/availability.html),
and other cloud vendors offer fully-managed HA Postgres services that pair
nicely with Coder.
For Coder to operate correctly, Coderd instances should have low-latency connections
to each other so that they can effectively relay traffic between users and workspaces no
matter which Coderd instance users or workspaces connect to. We make a best-effort attempt
to warn the user when inter-Coderd latency is too high, but if requests start dropping, this
is one metric to investigate.
For Coder to operate correctly, Coderd instances should have low-latency
connections to each other so that they can effectively relay traffic between
users and workspaces no matter which Coderd instance users or workspaces connect
to. We make a best-effort attempt to warn the user when inter-Coderd latency is
too high, but if requests start dropping, this is one metric to investigate.
We also recommend that you deploy all Coderd instances such that they have low-latency
connections to Postgres. Coderd often makes several database round-trips while processing
a single API request, so prioritizing low-latency between Coderd and Postgres is more important
than low-latency between users and Coderd.
We also recommend that you deploy all Coderd instances such that they have
low-latency connections to Postgres. Coderd often makes several database
round-trips while processing a single API request, so prioritizing low-latency
between Coderd and Postgres is more important than low-latency between users and
Coderd.
Note that this latency requirement applies _only_ to Coder services. Coder will
operate correctly even with few seconds of latency on workspace <-> Coder and user <-> Coder
connections.
operate correctly even with few seconds of latency on workspace <-> Coder and
user <-> Coder connections.
## Setup
Coder automatically enters HA mode when multiple instances simultaneously connect
to the same Postgres endpoint.
Coder automatically enters HA mode when multiple instances simultaneously
connect to the same Postgres endpoint.
HA brings one configuration variable to set in each Coderd
node: `CODER_DERP_SERVER_RELAY_URL`. The HA nodes use these URLs to communicate
with each other. Inter-node communication is only required while using the
embedded relay (default). If you're using [custom relays](../networking/index.md#custom-relays), Coder ignores `CODER_DERP_SERVER_RELAY_URL` since Postgres is the sole rendezvous for the Coder nodes.
HA brings one configuration variable to set in each Coderd node:
`CODER_DERP_SERVER_RELAY_URL`. The HA nodes use these URLs to communicate with
each other. Inter-node communication is only required while using the embedded
relay (default). If you're using
[custom relays](../networking/index.md#custom-relays), Coder ignores
`CODER_DERP_SERVER_RELAY_URL` since Postgres is the sole rendezvous for the
Coder nodes.
`CODER_DERP_SERVER_RELAY_URL` will never be `CODER_ACCESS_URL` because
`CODER_ACCESS_URL` is a load balancer to all Coder nodes.

32
docs/admin/prometheus.md
View File

@ -1,16 +1,25 @@
# Prometheus
Coder exposes many metrics which can be consumed by a Prometheus server, and give insight into the current state of a live Coder deployment.
Coder exposes many metrics which can be consumed by a Prometheus server, and
give insight into the current state of a live Coder deployment.
If you don't have an Prometheus server installed, you can follow the Prometheus [Getting started](https://prometheus.io/docs/prometheus/latest/getting_started/) guide.
If you don't have an Prometheus server installed, you can follow the Prometheus
[Getting started](https://prometheus.io/docs/prometheus/latest/getting_started/)
guide.
## Enable Prometheus metrics
Coder server exports metrics via the HTTP endpoint, which can be enabled using either the environment variable `CODER_PROMETHEUS_ENABLE` or the flag `--prometheus-enable`.
Coder server exports metrics via the HTTP endpoint, which can be enabled using
either the environment variable `CODER_PROMETHEUS_ENABLE` or the flag
`--prometheus-enable`.
The Prometheus endpoint address is `http://localhost:2112/` by default. You can use either the environment variable `CODER_PROMETHEUS_ADDRESS` or the flag ` --prometheus-address <network-interface>:<port>` to select a different listen address.
The Prometheus endpoint address is `http://localhost:2112/` by default. You can
use either the environment variable `CODER_PROMETHEUS_ADDRESS` or the flag
`--prometheus-address <network-interface>:<port>` to select a different listen
address.
If `coder server --prometheus-enable` is started locally, you can preview the metrics endpoint in your browser or by using curl: <!-- markdown-link-check-disable -->http://localhost:2112/<!-- markdown-link-check-enable -->.
If `coder server --prometheus-enable` is started locally, you can preview the
metrics endpoint in your browser or by using curl:
```console
$ curl http://localhost:2112/
@ -22,14 +31,17 @@ coderd_api_active_users_duration_hour 0
### Kubernetes deployment
The Prometheus endpoint can be enabled in the [Helm chart's](https://github.com/coder/coder/tree/main/helm) `values.yml` by setting the environment variable `CODER_PROMETHEUS_ADDRESS` to `0.0.0.0:2112`.
The environment variable `CODER_PROMETHEUS_ENABLE` will be enabled automatically.
The Prometheus endpoint can be enabled in the
[Helm chart's](https://github.com/coder/coder/tree/main/helm) `values.yml` by
setting the environment variable `CODER_PROMETHEUS_ADDRESS` to `0.0.0.0:2112`.
The environment variable `CODER_PROMETHEUS_ENABLE` will be enabled
automatically.
### Prometheus configuration
To allow Prometheus to scrape the Coder metrics, you will need to create a `scape_config`
in your `prometheus.yml` file, or in the Prometheus Helm chart values. Below is an
example `scrape_config`:
To allow Prometheus to scrape the Coder metrics, you will need to create a
`scape_config` in your `prometheus.yml` file, or in the Prometheus Helm chart
values. Below is an example `scrape_config`:
```yaml
scrape_configs:

104
docs/admin/provisioners.md
View File

@ -1,42 +1,63 @@
# Provisioners
By default, the Coder server runs [built-in provisioner daemons](../cli/server.md#provisioner-daemons), which execute `terraform` during workspace and template builds. However, there are sometimes benefits to running external provisioner daemons:
By default, the Coder server runs
[built-in provisioner daemons](../cli/server.md#provisioner-daemons), which
execute `terraform` during workspace and template builds. However, there are
sometimes benefits to running external provisioner daemons:
- **Secure build environments:** Run build jobs in isolated containers, preventing malicious templates from gaining shell access to the Coder host.
- **Secure build environments:** Run build jobs in isolated containers,
preventing malicious templates from gaining shell access to the Coder host.
- **Isolate APIs:** Deploy provisioners in isolated environments (on-prem, AWS, Azure) instead of exposing APIs (Docker, Kubernetes, VMware) to the Coder server. See [Provider Authentication](../templates/authentication.md) for more details.
- **Isolate APIs:** Deploy provisioners in isolated environments (on-prem, AWS,
Azure) instead of exposing APIs (Docker, Kubernetes, VMware) to the Coder
server. See [Provider Authentication](../templates/authentication.md) for more
details.
- **Isolate secrets**: Keep Coder unaware of cloud secrets, manage/rotate secrets on provisoner servers.
- **Isolate secrets**: Keep Coder unaware of cloud secrets, manage/rotate
secrets on provisoner servers.
- **Reduce server load**: External provisioners reduce load and build queue times from the Coder server. See [Scaling Coder](./scale.md#concurrent-workspace-builds) for more details.
- **Reduce server load**: External provisioners reduce load and build queue
times from the Coder server. See
[Scaling Coder](./scale.md#concurrent-workspace-builds) for more details.
Each provisioner can run a single [concurrent workspace build](./scale.md#concurrent-workspace-builds). For example, running 30 provisioner containers will allow 30 users to start workspaces at the same time.
Each provisioner can run a single
[concurrent workspace build](./scale.md#concurrent-workspace-builds). For
example, running 30 provisioner containers will allow 30 users to start
workspaces at the same time.
Provisioners are started with the [coder provisionerd start](../cli/provisionerd_start.md) command.
Provisioners are started with the
[coder provisionerd start](../cli/provisionerd_start.md) command.
## Authentication
The provisioner daemon must authenticate with your Coder deployment.
Set a [provisioner daemon pre-shared key (PSK)](../cli/server.md#--provisioner-daemon-psk) on the Coder server and start the provisioner with
`coder provisionerd start --psk <your-psk>`. If you are [installing with Helm](../install/kubernetes#install-coder-with-helm),
see the [Helm example](#example-running-an-external-provisioner-with-helm) below.
Set a
[provisioner daemon pre-shared key (PSK)](../cli/server.md#--provisioner-daemon-psk)
on the Coder server and start the provisioner with
`coder provisionerd start --psk <your-psk>`. If you are
[installing with Helm](../install/kubernetes.md#install-coder-with-helm), see
the [Helm example](#example-running-an-external-provisioner-with-helm) below.
> Coder still supports authenticating the provisioner daemon with a [token](../cli.md#--token) from a user with the
> Template Admin or Owner role. This method is deprecated in favor of the PSK, which only has permission to access
> provisioner daemon APIs. We recommend migrating to the PSK as soon as practical.
> Coder still supports authenticating the provisioner daemon with a
> [token](../cli.md#--token) from a user with the Template Admin or Owner role.
> This method is deprecated in favor of the PSK, which only has permission to
> access provisioner daemon APIs. We recommend migrating to the PSK as soon as
> practical.
## Types of provisioners
- **Generic provisioners** can pick up any build job from templates without provisioner tags.
- **Generic provisioners** can pick up any build job from templates without
provisioner tags.
```sh
```shell
coder provisionerd start
```
- **Tagged provisioners** can be used to pick up build jobs from templates (and corresponding workspaces) with matching tags.
- **Tagged provisioners** can be used to pick up build jobs from templates (and
corresponding workspaces) with matching tags.
```sh
```shell
coder provisionerd start \
--tag environment=on_prem \
--tag data_center=chicago
@ -52,11 +73,16 @@ see the [Helm example](#example-running-an-external-provisioner-with-helm) below
--provisioner-tag data_center=chicago
```
> At this time, tagged provisioners can also pick jobs from untagged templates. This behavior is [subject to change](https://github.com/coder/coder/issues/6442).
> At this time, tagged provisioners can also pick jobs from untagged
> templates. This behavior is
> [subject to change](https://github.com/coder/coder/issues/6442).
- **User provisioners** can only pick up jobs from user-tagged templates. Unlike the other provisioner types, any Coder can run user provisioners, but they have no impact unless there is at least one template with the `scope=user` provisioner tag.
- **User provisioners** can only pick up jobs from user-tagged templates. Unlike
the other provisioner types, any Coder can run user provisioners, but they
have no impact unless there is at least one template with the `scope=user`
provisioner tag.
```sh
```shell
coder provisionerd start \
--tag scope=user
@ -68,10 +94,11 @@ see the [Helm example](#example-running-an-external-provisioner-with-helm) below
## Example: Running an external provisioner with Helm
Coder provides a Helm chart for running external provisioner daemons, which you will use in concert with the Helm chart
for deploying the Coder server.
Coder provides a Helm chart for running external provisioner daemons, which you
will use in concert with the Helm chart for deploying the Coder server.
1. Create a long, random pre-shared key (PSK) and store it in a Kubernetes secret
1. Create a long, random pre-shared key (PSK) and store it in a Kubernetes
secret
```shell
kubectl create secret generic coder-provisioner-psk --from-literal=psk=`head /dev/urandom | tr -dc A-Za-z0-9 | head -c 26`
@ -84,8 +111,8 @@ for deploying the Coder server.
pskSecretName: "coder-provisioner-psk"
```
1. Redeploy Coder with the new `values.yaml` to roll out the PSK. You can omit `--version <your version>` to also upgrade
Coder to the latest version.
1. Redeploy Coder with the new `values.yaml` to roll out the PSK. You can omit
`--version <your version>` to also upgrade Coder to the latest version.
```shell
helm upgrade coder coder-v2/coder \
@ -94,7 +121,8 @@ for deploying the Coder server.
--values values.yaml
```
1. Create a `provisioner-values.yaml` file for the provisioner daemons Helm chart. For example
1. Create a `provisioner-values.yaml` file for the provisioner daemons Helm
chart. For example
```yaml
coder:
@ -109,11 +137,14 @@ for deploying the Coder server.
kind: k8s
```
This example creates a deployment of 10 provisioner daemons (for 10 concurrent builds) with the listed tags. For
generic provisioners, remove the tags.
This example creates a deployment of 10 provisioner daemons (for 10
concurrent builds) with the listed tags. For generic provisioners, remove the
tags.
> Refer to the [values.yaml](https://github.com/coder/coder/blob/main/helm/provisioner/values.yaml) file for the
> coder-provisioner chart for information on what values can be specified.
> Refer to the
> [values.yaml](https://github.com/coder/coder/blob/main/helm/provisioner/values.yaml)
> file for the coder-provisioner chart for information on what values can be
> specified.
1. Install the provisioner daemon chart
@ -124,12 +155,13 @@ for deploying the Coder server.
--values provisioner-values.yaml
```
You can verify that your provisioner daemons have successfully connected to Coderd by looking for a debug log message that says
You can verify that your provisioner daemons have successfully connected to
Coderd by looking for a debug log message that says
`provisionerd: successfully connected to coderd` from each Pod.
## Example: Running an external provisioner on a VM
```sh
```shell
curl -L https://coder.com/install.sh | sh
export CODER_URL=https://coder.example.com
export CODER_SESSION_TOKEN=your_token
@ -138,7 +170,7 @@ coder provisionerd start
## Example: Running an external provisioner via Docker
```sh
```shell
docker run --rm -it \
-e CODER_URL=https://coder.example.com/ \
-e CODER_SESSION_TOKEN=your_token \
@ -149,8 +181,10 @@ docker run --rm -it \
## Disable built-in provisioners
As mentioned above, the Coder server will run built-in provisioners by default. This can be disabled with a server-wide [flag or environment variable](../cli/server.md#provisioner-daemons).
As mentioned above, the Coder server will run built-in provisioners by default.
This can be disabled with a server-wide
[flag or environment variable](../cli/server.md#provisioner-daemons).
```sh
```shell
coder server --provisioner-daemons=0
```

37
docs/admin/quotas.md
View File

@ -2,19 +2,19 @@
Quotas are a mechanism for controlling spend by associating costs with workspace
templates and assigning budgets to users. Users that exceed their budget will be
blocked from launching more workspaces until they either delete their other workspaces
or get their budget extended.
blocked from launching more workspaces until they either delete their other
workspaces or get their budget extended.
For example: A template is configured with a cost of 5 credits per day,
and the user is granted 15 credits, which can be consumed by both started and
stopped workspaces. This budget limits the user to 3 concurrent workspaces.
For example: A template is configured with a cost of 5 credits per day, and the
user is granted 15 credits, which can be consumed by both started and stopped
workspaces. This budget limits the user to 3 concurrent workspaces.
Quotas are licensed with [Groups](./groups.md).
## Definitions
- **Credits** is the fundamental unit representing cost in the quota system. This integer
can be arbitrary, or it can map to your preferred currency.
- **Credits** is the fundamental unit representing cost in the quota system.
This integer can be arbitrary, or it can map to your preferred currency.
- **Budget** is the per-user, enforced, upper limit to credit spend.
- **Allowance** is a grant of credits to the budget.
@ -22,10 +22,11 @@ Quotas are licensed with [Groups](./groups.md).
Templates describe their cost through the `daily_cost` attribute in
[`resource_metadata`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/metadata).
Since costs are associated with resources, an offline workspace may consume
less quota than an online workspace.
Since costs are associated with resources, an offline workspace may consume less
quota than an online workspace.
A common use case is separating costs for a persistent volume and ephemeral compute:
A common use case is separating costs for a persistent volume and ephemeral
compute:
```hcl
resource "docker_volume" "home_volume" {
@ -56,11 +57,11 @@ resource "coder_metadata" "workspace" {
```
When the workspace above is shut down, the `docker_container` and
`coder_metadata` both get deleted. This reduces the cost from 30 credits to
10 credits.
`coder_metadata` both get deleted. This reduces the cost from 30 credits to 10
credits.
Resources without a `daily_cost` value are considered to cost 0. If the cost
was removed on the `docker_volume` above, the template would consume 0 credits when
Resources without a `daily_cost` value are considered to cost 0. If the cost was
removed on the `docker_volume` above, the template would consume 0 credits when
it's offline. This technique is good for incentivizing users to shut down their
unused workspaces and freeing up compute in the cluster.
@ -92,10 +93,10 @@ By default, groups are assumed to have a default allowance of 0.
## Quota Enforcement
Coder enforces Quota on workspace start and stop operations. The workspace
build process dynamically calculates costs, so quota violation fails builds
as opposed to failing the build-triggering operation. For example, the Workspace
Create Form will never get held up by quota enforcement.
Coder enforces Quota on workspace start and stop operations. The workspace build
process dynamically calculates costs, so quota violation fails builds as opposed
to failing the build-triggering operation. For example, the Workspace Create
Form will never get held up by quota enforcement.
![build-log](../images/admin/quota-buildlog.png)

10
docs/admin/rbac.md
View File

@ -1,10 +1,13 @@
# Role Based Access Control (RBAC)
Use RBAC to define which users and [groups](./groups.md) can use specific templates in Coder. These can be defined in Coder or [synced from your identity provider](./auth.md)
Use RBAC to define which users and [groups](./groups.md) can use specific
templates in Coder. These can be defined in Coder or
[synced from your identity provider](./auth.md)
![rbac](../images/template-rbac.png)
The "Everyone" group makes a template accessible to all users. This can be removed to make a template private.
The "Everyone" group makes a template accessible to all users. This can be
removed to make a template private.
## Permissions
@ -15,4 +18,5 @@ You can set the following permissions:
## 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)

191
docs/admin/scale.md
View File

@ -1,14 +1,22 @@
We scale-test Coder with [a built-in utility](#scaletest-utility) that can be used in your environment for insights into how Coder scales with your infrastructure.
We scale-test Coder with [a built-in utility](#scaletest-utility) that can be
used in your environment for insights into how Coder scales with your
infrastructure.
## General concepts
Coder runs workspace operations in a queue. The number of concurrent builds will be limited to the number of provisioner daemons across all coderd replicas.
Coder runs workspace operations in a queue. The number of concurrent builds will
be limited to the number of provisioner daemons across all coderd replicas.
- **coderd**: Coder’s primary service. Learn more about [Coder’s architecture](../about/architecture.md)
- **coderd replicas**: Replicas (often via Kubernetes) for high availability, this is an [enterprise feature](../enterprise.md)
- **concurrent workspace builds**: Workspace operations (e.g. create/stop/delete/apply) across all users
- **concurrent connections**: Any connection to a workspace (e.g. SSH, web terminal, `coder_app`)
- **provisioner daemons**: Coder runs one workspace build per provisioner daemon. One coderd replica can host many daemons
- **coderd**: Coder’s primary service. Learn more about
[Coder’s architecture](../about/architecture.md)
- **coderd replicas**: Replicas (often via Kubernetes) for high availability,
this is an [enterprise feature](../enterprise.md)
- **concurrent workspace builds**: Workspace operations (e.g.
create/stop/delete/apply) across all users
- **concurrent connections**: Any connection to a workspace (e.g. SSH, web
terminal, `coder_app`)
- **provisioner daemons**: Coder runs one workspace build per provisioner
daemon. One coderd replica can host many daemons
- **scaletest**: Our scale-testing utility, built into the `coder` command line.
```text
@ -17,49 +25,86 @@ Coder runs workspace operations in a queue. The number of concurrent builds will
## Infrastructure recommendations
> Note: The below are guidelines for planning your infrastructure. Your mileage may vary depending on your templates, workflows, and users.
> Note: The below are guidelines for planning your infrastructure. Your mileage
> may vary depending on your templates, workflows, and users.
When planning your infrastructure, we recommend you consider the following:
1. CPU and memory requirements for `coderd`. We recommend allocating 1 CPU core and 2 GB RAM per `coderd` replica at minimum. See [Concurrent users](#concurrent-users) for more details.
1. CPU and memory requirements for [external provisioners](../admin/provisioners.md#running-external-provisioners), if required. We recommend allocating 1 CPU core and 1 GB RAM per 5 concurrent workspace builds to external provisioners. Note that this may vary depending on the template used. See [Concurrent workspace builds](#concurrent-workspace-builds) for more details. By default, `coderd` runs 3 integrated provisioners.
1. CPU and memory requirements for the database used by `coderd`. We recommend allocating an additional 1 CPU core to the database used by Coder for every 1000 active users.
1. CPU and memory requirements for workspaces created by Coder. This will vary depending on users' needs. However, the Coder agent itself requires at minimum 0.1 CPU cores and 256 MB to run inside a workspace.
1. CPU and memory requirements for `coderd`. We recommend allocating 1 CPU core
and 2 GB RAM per `coderd` replica at minimum. See
[Concurrent users](#concurrent-users) for more details.
1. CPU and memory requirements for
[external provisioners](../admin/provisioners.md#running-external-provisioners),
if required. We recommend allocating 1 CPU core and 1 GB RAM per 5 concurrent
workspace builds to external provisioners. Note that this may vary depending
on the template used. See
[Concurrent workspace builds](#concurrent-workspace-builds) for more details.
By default, `coderd` runs 3 integrated provisioners.
1. CPU and memory requirements for the database used by `coderd`. We recommend
allocating an additional 1 CPU core to the database used by Coder for every
1000 active users.
1. CPU and memory requirements for workspaces created by Coder. This will vary
depending on users' needs. However, the Coder agent itself requires at
minimum 0.1 CPU cores and 256 MB to run inside a workspace.
### Concurrent users
We recommend allocating 2 CPU cores and 4 GB RAM per `coderd` replica per 1000 active users.
We also recommend allocating an additional 1 CPU core to the database used by Coder for every 1000 active users.
Inactive users do not consume Coder resources, although workspaces configured to auto-start will consume resources when they are built.
We recommend allocating 2 CPU cores and 4 GB RAM per `coderd` replica per 1000
active users. We also recommend allocating an additional 1 CPU core to the
database used by Coder for every 1000 active users. Inactive users do not
consume Coder resources, although workspaces configured to auto-start will
consume resources when they are built.
Users' primary mode of accessing Coder will also affect resource requirements.
If users will be accessing workspaces primarily via Coder's HTTP interface, we recommend doubling the number of cores and RAM allocated per user.
For example, if you expect 1000 users accessing workspaces via the web, we recommend allocating 4 CPU cores and 8 GB RAM.
If users will be accessing workspaces primarily via Coder's HTTP interface, we
recommend doubling the number of cores and RAM allocated per user. For example,
if you expect 1000 users accessing workspaces via the web, we recommend
allocating 4 CPU cores and 8 GB RAM.
Users accessing workspaces via SSH will consume fewer resources, as SSH connections are not proxied through Coder.
Users accessing workspaces via SSH will consume fewer resources, as SSH
connections are not proxied through Coder.
### Concurrent workspace builds
Workspace builds are CPU-intensive, as it relies on Terraform. Various [Terraform providers](https://registry.terraform.io/browse/providers) have different resource requirements.
When tested with our [kubernetes](https://github.com/coder/coder/tree/main/examples/templates/kubernetes) template, `coderd` will consume roughly 0.25 cores per concurrent workspace build.
For effective provisioning, our helm chart prefers to schedule [one coderd replica per-node](https://github.com/coder/coder/blob/main/helm/coder/values.yaml#L188-L202).
Workspace builds are CPU-intensive, as it relies on Terraform. Various
[Terraform providers](https://registry.terraform.io/browse/providers) have
different resource requirements. When tested with our
[kubernetes](https://github.com/coder/coder/tree/main/examples/templates/kubernetes)
template, `coderd` will consume roughly 0.25 cores per concurrent workspace
build. For effective provisioning, our helm chart prefers to schedule
[one coderd replica per-node](https://github.com/coder/coder/blob/main/helm/coder/values.yaml#L188-L202).
We recommend:
- Running `coderd` on a dedicated set of nodes. This will prevent other workloads from interfering with workspace builds. You can use [node selectors](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector), or [taints and tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) to achieve this.
- Disabling autoscaling for `coderd` nodes. Autoscaling can cause interruptions for users, see [Autoscaling](#autoscaling) for more details.
- (Enterprise-only) Running external provisioners instead of Coder's built-in provisioners (`CODER_PROVISIONER_DAEMONS=0`) will separate the load caused by workspace provisioning on the `coderd` nodes. For more details, see [External provisioners](../admin/provisioners.md#running-external-provisioners).
- Alternatively, if increasing the number of integrated provisioner daemons in `coderd` (`CODER_PROVISIONER_DAEMONS>3`), allocate additional resources to `coderd` to compensate (approx. 0.25 cores and 256 MB per provisioner daemon).
- Running `coderd` on a dedicated set of nodes. This will prevent other
workloads from interfering with workspace builds. You can use
[node selectors](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector),
or
[taints and tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/)
to achieve this.
- Disabling autoscaling for `coderd` nodes. Autoscaling can cause interruptions
for users, see [Autoscaling](#autoscaling) for more details.
- (Enterprise-only) Running external provisioners instead of Coder's built-in
provisioners (`CODER_PROVISIONER_DAEMONS=0`) will separate the load caused by
workspace provisioning on the `coderd` nodes. For more details, see
[External provisioners](../admin/provisioners.md#running-external-provisioners).
- Alternatively, if increasing the number of integrated provisioner daemons in
`coderd` (`CODER_PROVISIONER_DAEMONS>3`), allocate additional resources to
`coderd` to compensate (approx. 0.25 cores and 256 MB per provisioner daemon).
For example, to support 120 concurrent workspace builds:
- Create a cluster/nodepool with 4 nodes, 8-core each (AWS: `t3.2xlarge` GCP: `e2-highcpu-8`)
- Run coderd with 4 replicas, 30 provisioner daemons each. (`CODER_PROVISIONER_DAEMONS=30`)
- Ensure Coder's [PostgreSQL server](./configure.md#postgresql-database) can use up to 2 cores and 4 GB RAM
- Create a cluster/nodepool with 4 nodes, 8-core each (AWS: `t3.2xlarge` GCP:
`e2-highcpu-8`)
- Run coderd with 4 replicas, 30 provisioner daemons each.
(`CODER_PROVISIONER_DAEMONS=30`)
- Ensure Coder's [PostgreSQL server](./configure.md#postgresql-database) can use
up to 2 cores and 4 GB RAM
## Recent scale tests
> Note: the below information is for reference purposes only, and are not intended to be used as guidelines for infrastructure sizing.
> Note: the below information is for reference purposes only, and are not
> intended to be used as guidelines for infrastructure sizing.
| Environment | Coder CPU | Coder RAM | Database | Users | Concurrent builds | Concurrent connections (Terminal/SSH) | Coder Version | Last tested |
| ---------------- | --------- | --------- | ---------------- | ----- | ----------------- | ------------------------------------- | ------------- | ------------ |
@ -69,17 +114,22 @@ For example, to support 120 concurrent workspace builds:
## Scale testing utility
Since Coder's performance is highly dependent on the templates and workflows you support, you may wish to use our internal scale testing utility against your own environments.
Since Coder's performance is highly dependent on the templates and workflows you
support, you may wish to use our internal scale testing utility against your own
environments.
> Note: This utility is intended for internal use only. It is not subject to any compatibility guarantees, and may cause interruptions for your users.
> To avoid potential outages and orphaned resources, we recommend running scale tests on a secondary "staging" environment.
> Run it against a production environment at your own risk.
> Note: This utility is intended for internal use only. It is not subject to any
> compatibility guarantees, and may cause interruptions for your users. To avoid
> potential outages and orphaned resources, we recommend running scale tests on
> a secondary "staging" environment. Run it against a production environment at
> your own risk.
### Workspace Creation
The following command will run our scale test against your own Coder deployment. You can also specify a template name and any parameter values.
The following command will run our scale test against your own Coder deployment.
You can also specify a template name and any parameter values.
```sh
```shell
coder exp scaletest create-workspaces \
--count 1000 \
--template "kubernetes" \
@ -99,16 +149,20 @@ The test does the following:
1. close connections, attempt to delete all workspaces
1. return results (e.g. `998 succeeded, 2 failed to connect`)
Concurrency is configurable. `concurrency 0` means the scaletest test will attempt to create & connect to all workspaces immediately.
Concurrency is configurable. `concurrency 0` means the scaletest test will
attempt to create & connect to all workspaces immediately.
If you wish to leave the workspaces running for a period of time, you can specify `--no-cleanup` to skip the cleanup step.
You are responsible for deleting these resources later.
If you wish to leave the workspaces running for a period of time, you can
specify `--no-cleanup` to skip the cleanup step. You are responsible for
deleting these resources later.
### Traffic Generation
Given an existing set of workspaces created previously with `create-workspaces`, the following command will generate traffic similar to that of Coder's web terminal against those workspaces.
Given an existing set of workspaces created previously with `create-workspaces`,
the following command will generate traffic similar to that of Coder's web
terminal against those workspaces.
```sh
```shell
coder exp scaletest workspace-traffic \
--byes-per-tick 128 \
--tick-interval 100ms \
@ -119,9 +173,10 @@ To generate SSH traffic, add the `--ssh` flag.
### Cleanup
The scaletest utility will attempt to clean up all workspaces it creates. If you wish to clean up all workspaces, you can run the following command:
The scaletest utility will attempt to clean up all workspaces it creates. If you
wish to clean up all workspaces, you can run the following command:
```sh
```shell
coder exp scaletest cleanup
```
@ -129,33 +184,45 @@ This will delete all workspaces and users with the prefix `scaletest-`.
## Autoscaling
We generally do not recommend using an autoscaler that modifies the number of coderd replicas. In particular, scale
down events can cause interruptions for a large number of users.
We generally do not recommend using an autoscaler that modifies the number of
coderd replicas. In particular, scale down events can cause interruptions for a
large number of users.
Coderd is different from a simple request-response HTTP service in that it services long-lived connections whenever it
proxies HTTP applications like IDEs or terminals that rely on websockets, or when it relays tunneled connections to
workspaces. Loss of a coderd replica will drop these long-lived connections and interrupt users. For example, if you
have 4 coderd replicas behind a load balancer, and an autoscaler decides to reduce it to 3, roughly 25% of the
connections will drop. An even larger proportion of users could be affected if they use applications that use more
than one websocket.
Coderd is different from a simple request-response HTTP service in that it
services long-lived connections whenever it proxies HTTP applications like IDEs
or terminals that rely on websockets, or when it relays tunneled connections to
workspaces. Loss of a coderd replica will drop these long-lived connections and
interrupt users. For example, if you have 4 coderd replicas behind a load
balancer, and an autoscaler decides to reduce it to 3, roughly 25% of the
connections will drop. An even larger proportion of users could be affected if
they use applications that use more than one websocket.
The severity of the interruption varies by application. Coder's web terminal, for example, will reconnect to the same
session and continue. So, this should not be interpreted as saying coderd replicas should never be taken down for any
The severity of the interruption varies by application. Coder's web terminal,
for example, will reconnect to the same session and continue. So, this should
not be interpreted as saying coderd replicas should never be taken down for any
reason.
We recommend you plan to run enough coderd replicas to comfortably meet your weekly high-water-mark load, and monitor
coderd peak CPU & memory utilization over the long term, reevaluating periodically. When scaling down (or performing
upgrades), schedule these outside normal working hours to minimize user interruptions.
We recommend you plan to run enough coderd replicas to comfortably meet your
weekly high-water-mark load, and monitor coderd peak CPU & memory utilization
over the long term, reevaluating periodically. When scaling down (or performing
upgrades), schedule these outside normal working hours to minimize user
interruptions.
### A note for Kubernetes users
When running on Kubernetes on cloud infrastructure (i.e. not bare metal), many operators choose to employ a _cluster_
autoscaler that adds and removes Kubernetes _nodes_ according to load. Coder can coexist with such cluster autoscalers,
but we recommend you take steps to prevent the autoscaler from evicting coderd pods, as an eviction will cause the same
interruptions as described above. For example, if you are using the [Kubernetes cluster
autoscaler](https://kubernetes.io/docs/reference/labels-annotations-taints/#cluster-autoscaler-kubernetes-io-safe-to-evict),
you may wish to set `cluster-autoscaler.kubernetes.io/safe-to-evict: "false"` as an annotation on the coderd deployment.
When running on Kubernetes on cloud infrastructure (i.e. not bare metal), many
operators choose to employ a _cluster_ autoscaler that adds and removes
Kubernetes _nodes_ according to load. Coder can coexist with such cluster
autoscalers, but we recommend you take steps to prevent the autoscaler from
evicting coderd pods, as an eviction will cause the same interruptions as
described above. For example, if you are using the
[Kubernetes cluster autoscaler](https://kubernetes.io/docs/reference/labels-annotations-taints/#cluster-autoscaler-kubernetes-io-safe-to-evict),
you may wish to set `cluster-autoscaler.kubernetes.io/safe-to-evict: "false"` as
an annotation on the coderd deployment.
## Troubleshooting
If a load test fails or if you are experiencing performance issues during day-to-day use, you can leverage Coder's [prometheus metrics](./prometheus.md) to identify bottlenecks during scale tests. Additionally, you can use your existing cloud monitoring stack to measure load, view server logs, etc.
If a load test fails or if you are experiencing performance issues during
day-to-day use, you can leverage Coder's [prometheus metrics](./prometheus.md)
to identify bottlenecks during scale tests. Additionally, you can use your
existing cloud monitoring stack to measure load, view server logs, etc.

27
docs/admin/telemetry.md
View File

@ -1,25 +1,38 @@
# Telemetry
Coder collects telemetry data from all free installations. Our users have the right to know what we collect, why we collect it, and how we use the data.
Coder collects telemetry data from all free installations. Our users have the
right to know what we collect, why we collect it, and how we use the data.
## What we collect
First of all, we do not collect any information that could threaten the security of your installation. For example, we do not collect parameters, environment variables, or passwords.
First of all, we do not collect any information that could threaten the security
of your installation. For example, we do not collect parameters, environment
variables, or passwords.
You can find a full list of the data we collect in the source code [here](https://github.com/coder/coder/blob/main/coderd/telemetry/telemetry.go).
You can find a full list of the data we collect in the source code
[here](https://github.com/coder/coder/blob/main/coderd/telemetry/telemetry.go).
Telemetry can be configured with the `CODER_TELEMETRY=x` environment variable.
For example, telemetry can be disabled with `CODER_TELEMETRY=false`.
`CODER_TELEMETRY=true` is our default level. It includes user email and IP addresses. This information is used in aggregate to understand where our users are and general demographic information. We may reach out to the deployment admin, but will never use these emails for outbound marketing.
`CODER_TELEMETRY=true` is our default level. It includes user email and IP
addresses. This information is used in aggregate to understand where our users
are and general demographic information. We may reach out to the deployment
admin, but will never use these emails for outbound marketing.
`CODER_TELEMETRY=false` disables telemetry altogether.
## How we use telemetry
We use telemetry to build product better and faster. Without telemetry, we don't know which features are most useful, we don't know where users are dropping off in our funnel, and we don't know if our roadmap is aligned with the demographics that really use Coder.
We use telemetry to build product better and faster. Without telemetry, we don't
know which features are most useful, we don't know where users are dropping off
in our funnel, and we don't know if our roadmap is aligned with the demographics
that really use Coder.
Typical SaaS companies collect far more than what we do with little transparency and configurability. It's hard to imagine our favorite products today existing without their backers having good intelligence.
Typical SaaS companies collect far more than what we do with little transparency
and configurability. It's hard to imagine our favorite products today existing
without their backers having good intelligence.
We've decided the only way we can make our product open-source _and_ build at a fast pace is by collecting usage data as well.
We've decided the only way we can make our product open-source _and_ build at a
fast pace is by collecting usage data as well.

25
docs/admin/upgrade.md
View File

@ -14,18 +14,18 @@ of [install](../install).
## Via install.sh
If you installed Coder using the `install.sh` script, re-run the below
command on the host:
If you installed Coder using the `install.sh` script, re-run the below command
on the host:
```console
```shell
curl -L https://coder.com/install.sh | sh
```
The script will unpack the new `coder` binary version over the one currently installed.
Next, you can restart Coder with the following commands (if running it as a system
service):
The script will unpack the new `coder` binary version over the one currently
installed. Next, you can restart Coder with the following commands (if running
it as a system service):
```console
```shell
systemctl daemon-reload
systemctl restart coder
```
@ -35,19 +35,22 @@ systemctl restart coder
If you installed using `docker-compose`, run the below command to upgrade the
Coder container:
```console
```shell
docker-compose pull coder && docker-compose up coder -d
```
## Via Kubernetes
See [Upgrading Coder via Helm](../install/kubernetes.md#upgrading-coder-via-helm).
See
[Upgrading Coder via Helm](../install/kubernetes.md#upgrading-coder-via-helm).
## Via Windows
Download the latest Windows installer or binary from [GitHub releases](https://github.com/coder/coder/releases/latest), or upgrade from Winget.
Download the latest Windows installer or binary from
[GitHub releases](https://github.com/coder/coder/releases/latest), or upgrade
from Winget.
```sh
```pwsh
winget install Coder.Coder
```

83
docs/admin/users.md
View File

@ -1,6 +1,7 @@
# Users
This article walks you through the user roles available in Coder and creating and managing users.
This article walks you through the user roles available in Coder and creating
and managing users.
## Roles
@ -17,36 +18,54 @@ Coder offers these user roles in the community edition:
| Execute and use **ALL** Workspaces | | | | ✅ |
| View all user operation [Audit Logs](./audit-logs.md) | ✅ | | | ✅ |
A user may have one or more roles. All users have an implicit Member role
that may use personal workspaces.
A user may have one or more roles. All users have an implicit Member role that
may use personal workspaces.
## Security notes
A malicious Template Admin could write a template that executes commands on the host (or `coder server` container), which potentially escalates their privileges or shuts down the Coder server. To avoid this, run [external provisioners](./provisioners.md).
A malicious Template Admin could write a template that executes commands on the
host (or `coder server` container), which potentially escalates their privileges
or shuts down the Coder server. To avoid this, run
[external provisioners](./provisioners.md).
In low-trust environments, we do not recommend giving users direct access to edit templates. Instead, use [CI/CD pipelines to update templates](../templates/change-management.md) with proper security scans and code reviews in place.
In low-trust environments, we do not recommend giving users direct access to
edit templates. Instead, use
[CI/CD pipelines to update templates](../templates/change-management.md) with
proper security scans and code reviews in place.
## User status
Coder user accounts can have different status types: active, dormant, and suspended.
Coder user accounts can have different status types: active, dormant, and
suspended.
### Active user
An _active_ user account in Coder is the default and desired state for all users. When a user's account is marked as _active_, they have complete access to the Coder platform
and can utilize all of its features and functionalities without any limitations. Active users can access workspaces, templates, and interact with Coder using CLI.
An _active_ user account in Coder is the default and desired state for all
users. When a user's account is marked as _active_, they have complete access to
the Coder platform and can utilize all of its features and functionalities
without any limitations. Active users can access workspaces, templates, and
interact with Coder using CLI.
### Dormant user
A user account is set to _dormant_ status when they have not yet logged in, or have not logged into the Coder platform for the past 90 days. Once the user logs in to the platform, the account status will switch to _active_.
A user account is set to _dormant_ status when they have not yet logged in, or
have not logged into the Coder platform for the past 90 days. Once the user logs
in to the platform, the account status will switch to _active_.
Dormant accounts do not count towards the total number of licensed seats in a Coder subscription, allowing organizations to optimize their license usage.
Dormant accounts do not count towards the total number of licensed seats in a
Coder subscription, allowing organizations to optimize their license usage.
### Suspended user
When a user's account is marked as _suspended_ in Coder, it means that the account has been temporarily deactivated, and the user is unable to access the platform.
When a user's account is marked as _suspended_ in Coder, it means that the
account has been temporarily deactivated, and the user is unable to access the
platform.
Only user administrators or owners have the necessary permissions to manage suspended accounts and decide whether to lift the suspension and allow the user back into the Coder environment.
This level of control ensures that administrators can enforce security measures and handle any compliance-related issues promptly.
Only user administrators or owners have the necessary permissions to manage
suspended accounts and decide whether to lift the suspension and allow the user
back into the Coder environment. This level of control ensures that
administrators can enforce security measures and handle any compliance-related
issues promptly.
## Create a user
@ -64,7 +83,7 @@ The new user will appear in the **Users** list. Use the toggle to change their
To create a user via the Coder CLI, run:
```console
```shell
coder users create
```
@ -98,7 +117,7 @@ To suspend a user via the web UI:
To suspend a user via the CLI, run:
```console
```shell
coder users suspend <username|user_id>
```
@ -117,7 +136,7 @@ To activate a user via the web UI:
To activate a user via the CLI, run:
```console
```shell
coder users activate <username|user_id>
```
@ -128,25 +147,27 @@ Confirm the user activation by typing **yes** and pressing **enter**.
To reset a user's via the web UI:
1. Go to **Users**.
2. Find the user whose password you want to reset, click the vertical ellipsis to the right,
and select **Reset password**.
2. Find the user whose password you want to reset, click the vertical ellipsis
to the right, and select **Reset password**.
3. Coder displays a temporary password that you can send to the user; copy the
password and click **Reset password**.
Coder will prompt the user to change their temporary password immediately after logging in.
Coder will prompt the user to change their temporary password immediately after
logging in.
You can also reset a password via the CLI:
```console
```shell
# run `coder reset-password <username> --help` for usage instructions
coder reset-password <username>
```
> Resetting a user's password, e.g., the initial `owner` role-based user, only works when run on the host running the Coder control plane.
> Resetting a user's password, e.g., the initial `owner` role-based user, only
> works when run on the host running the Coder control plane.
### Resetting a password on Kubernetes
```sh
```shell
kubectl exec -it deployment/coder /bin/bash -n coder
coder reset-password <username>
@ -154,14 +175,22 @@ coder reset-password <username>
## User filtering
In the Coder UI, you can filter your users using pre-defined filters or by utilizing the Coder's filter query. The examples provided below demonstrate how to use the Coder's filter query:
In the Coder UI, you can filter your users using pre-defined filters or by
utilizing the Coder's filter query. The examples provided below demonstrate how
to use the Coder's filter query:
- To find active users, use the filter `status:active`.
- To find admin users, use the filter `role:admin`.
- To find users have not been active since July 2023: `status:active last_seen_before:"2023-07-01T00:00:00Z"`
- To find users have not been active since July 2023:
`status:active last_seen_before:"2023-07-01T00:00:00Z"`
The following filters are supported:
- `status` - Indicates the status of the user. It can be either `active`, `dormant` or `suspended`.
- `role` - Represents the role of the user. You can refer to the [TemplateRole documentation](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#TemplateRole) for a list of supported user roles.
- `last_seen_before` and `last_seen_after` - The last time a used has used the platform (e.g. logging in, any API requests, connecting to workspaces). Uses the RFC3339Nano format.
- `status` - Indicates the status of the user. It can be either `active`,
`dormant` or `suspended`.
- `role` - Represents the role of the user. You can refer to the
[TemplateRole documentation](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#TemplateRole)
for a list of supported user roles.
- `last_seen_before` and `last_seen_after` - The last time a used has used the
platform (e.g. logging in, any API requests, connecting to workspaces). Uses
the RFC3339Nano format.

67
docs/admin/workspace-proxies.md
View File

@ -1,28 +1,47 @@
# Workspace Proxies
> Workspace proxies are in an [experimental state](../contributing/feature-stages.md#experimental-features) and the behavior is subject to change. Use [GitHub issues](https://github.com/coder/coder) to leave feedback. This experiment must be specifically enabled with the `--experiments="moons"` option on both coderd and the workspace proxy. If you have all experiements enabled, you have to add moons as well. `--experiments="*,moons"`
> Workspace proxies are in an
> [experimental state](../contributing/feature-stages.md#experimental-features)
> and the behavior is subject to change. Use
> [GitHub issues](https://github.com/coder/coder) to leave feedback. This
> experiment must be specifically enabled with the `--experiments="moons"`
> option on both coderd and the workspace proxy. If you have all experiements
> enabled, you have to add moons as well. `--experiments="*,moons"`
Workspace proxies provide low-latency experiences for geo-distributed teams.
Coder's networking does a best effort to make direct connections to a workspace. In situations where this is not possible, such as connections via the web terminal and [web IDEs](../ides/web-ides.md), workspace proxies are able to reduce the amount of distance the network traffic needs to travel.
Coder's networking does a best effort to make direct connections to a workspace.
In situations where this is not possible, such as connections via the web
terminal and [web IDEs](../ides/web-ides.md), workspace proxies are able to
reduce the amount of distance the network traffic needs to travel.
A workspace proxy is a relay connection a developer can choose to use when connecting with their workspace over SSH, a workspace app, port forwarding, etc. Dashboard connections and API calls (e.g. the workspaces list) are not served over workspace proxies.
A workspace proxy is a relay connection a developer can choose to use when
connecting with their workspace over SSH, a workspace app, port forwarding, etc.
Dashboard connections and API calls (e.g. the workspaces list) are not served
over workspace proxies.
![ProxyDiagram](../images/workspaceproxy/proxydiagram.png)
# Deploy a workspace proxy
Each workspace proxy should be a unique instance. At no point should 2 workspace proxy instances share the same authentication token. They only require port 443 to be open and are expected to have network connectivity to the coderd dashboard. Workspace proxies **do not** make any database connections.
Each workspace proxy should be a unique instance. At no point should 2 workspace
proxy instances share the same authentication token. They only require port 443
to be open and are expected to have network connectivity to the coderd
dashboard. Workspace proxies **do not** make any database connections.
Workspace proxies can be used in the browser by navigating to the user `Account -> Workspace Proxy`
Workspace proxies can be used in the browser by navigating to the user
`Account -> Workspace Proxy`
## Requirements
- The [Coder CLI](../cli.md) must be installed and authenticated as a user with the Owner role.
- The [Coder CLI](../cli.md) must be installed and authenticated as a user with
the Owner role.
## Step 1: Create the proxy
Create the workspace proxy and make sure to save the returned authentication token for said proxy. This is the token the workspace proxy will use to authenticate back to primary coderd.
Create the workspace proxy and make sure to save the returned authentication
token for said proxy. This is the token the workspace proxy will use to
authenticate back to primary coderd.
```bash
$ coder wsproxy create --name=newyork --display-name="USA East" --icon="/emojis/2194.png"
@ -40,7 +59,9 @@ newyork unregistered
## Step 2: Deploy the proxy
Deploying the workspace proxy will also register the proxy with coderd and make the workspace proxy usable. If the proxy deployment is successful, `coder wsproxy ls` will show an `ok` status code:
Deploying the workspace proxy will also register the proxy with coderd and make
the workspace proxy usable. If the proxy deployment is successful,
`coder wsproxy ls` will show an `ok` status code:
```
$ coder wsproxy ls
@ -53,13 +74,18 @@ sydney https://sydney.example.com ok
Other Status codes:
- `unregistered` : The workspace proxy was created, and not yet deployed
- `unreachable` : The workspace proxy was registered, but is not responding. Likely the proxy went offline.
- `unhealthy` : The workspace proxy is reachable, but has some issue that is preventing the proxy from being used. `coder wsproxy ls` should show the error message.
- `unreachable` : The workspace proxy was registered, but is not responding.
Likely the proxy went offline.
- `unhealthy` : The workspace proxy is reachable, but has some issue that is
preventing the proxy from being used. `coder wsproxy ls` should show the error
message.
- `ok` : The workspace proxy is healthy and working properly!
### Configuration
Workspace proxy configuration overlaps with a subset of the coderd configuration. To see the full list of configuration options: `coder wsproxy server --help`
Workspace proxy configuration overlaps with a subset of the coderd
configuration. To see the full list of configuration options:
`coder wsproxy server --help`
```bash
# Proxy specific configuration. These are REQUIRED
@ -87,7 +113,8 @@ CODER_TLS_KEY_FILE="<key_file_location>"
Make a `values-wsproxy.yaml` with the workspace proxy configuration:
> Notice the `workspaceProxy` configuration which is `false` by default in the coder Helm chart.
> Notice the `workspaceProxy` configuration which is `false` by default in the
> coder Helm chart.
```yaml
coder:
@ -121,7 +148,9 @@ Using Helm, install the workspace proxy chart
helm install coder coder-v2/coder --namespace <your workspace proxy namespace> -f ./values-wsproxy.yaml
```
Test that the workspace proxy is reachable with `curl -vvv`. If for some reason, the Coder dashboard still shows the workspace proxy is `UNHEALTHY`, scale down and up the deployment's replicas.
Test that the workspace proxy is reachable with `curl -vvv`. If for some reason,
the Coder dashboard still shows the workspace proxy is `UNHEALTHY`, scale down
and up the deployment's replicas.
### Running on a VM
@ -132,11 +161,14 @@ coder wsproxy server
### Running in Docker
Modify the default entrypoint to run a workspace proxy server instead of a regular Coder server.
Modify the default entrypoint to run a workspace proxy server instead of a
regular Coder server.
#### Docker Compose
Change the provided [`docker-compose.yml`](https://github.com/coder/coder/blob/main/docker-compose.yaml) file to include a custom entrypoint:
Change the provided
[`docker-compose.yml`](https://github.com/coder/coder/blob/main/docker-compose.yaml)
file to include a custom entrypoint:
```diff
image: ghcr.io/coder/coder:${CODER_VERSION:-latest}
@ -158,6 +190,9 @@ ENTRYPOINT ["/opt/coder", "wsproxy", "server"]
### Selecting a proxy
Users can select a workspace proxy at the top-right of the browser-based Coder dashboard. Workspace proxy preferences are cached by the web browser. If a proxy goes offline, the session will fall back to the primary proxy. This could take up to 60 seconds.
Users can select a workspace proxy at the top-right of the browser-based Coder
dashboard. Workspace proxy preferences are cached by the web browser. If a proxy
goes offline, the session will fall back to the primary proxy. This could take
up to 60 seconds.
![Workspace proxy picker](../images/admin/workspace-proxy-picker.png)

2
docs/api/authentication.md generated
View File

@ -2,7 +2,7 @@
Long-lived tokens can be generated to perform actions on behalf of your user account:
```console
```shell
coder tokens create
```

4
docs/api/index.md generated
View File

@ -4,13 +4,13 @@ Get started with the Coder API:
Generate a token on your Coder deployment by visiting:
```sh
```shell
https://coder.example.com/settings/tokens
```
List your workspaces
```sh
```shell
# CLI
curl https://coder.example.com/api/v2/workspaces?q=owner:me \
-H "Coder-Session-Token: <your-token>"

2
docs/changelogs/README.md
View File

@ -8,7 +8,7 @@ These changelogs are currently not kept in sync with GitHub releases. Use [GitHu
Run this command to generate release notes:
```sh
```shell
export CODER_IGNORE_MISSING_COMMIT_METADATA=1
export BRANCH=main
./scripts/release/generate_release_notes.sh \

42
docs/changelogs/v0.25.0.md
View File

@ -1,17 +1,27 @@
## Changelog
> **Warning**: This release has a known issue: #8351. Upgrade directly to v0.26.0 which includes a fix
> **Warning**: This release has a known issue: #8351. Upgrade directly to
> v0.26.0 which includes a fix
### Features
- The `coder stat` fetches workspace utilization metrics, even from within a container. Our example templates have been updated to use this to show CPU, memory, disk via [agent metadata](https://coder.com/docs/v2/latest/templates/agent-metadata) (#8005)
- Helm: `coder.command` can specify a different command for the Coder pod (#8116)
- Enterprise deployments can create templates without 'everyone' group access (#7982)
- The `coder stat` fetches workspace utilization metrics, even from within a
container. Our example templates have been updated to use this to show CPU,
memory, disk via
[agent metadata](https://coder.com/docs/v2/latest/templates/agent-metadata)
(#8005)
- Helm: `coder.command` can specify a different command for the Coder pod
(#8116)
- Enterprise deployments can create templates without 'everyone' group access
(#7982)
![Disable "everyone"](https://github.com/coder/coder/assets/22407953/1c31cb9b-be5c-4bef-abee-324856734215)
- Add login type 'none' to prevent password login. This can come in handy for machine accounts for CI/CD pipelines or other automation (#8009)
- Add login type 'none' to prevent password login. This can come in handy for
machine accounts for CI/CD pipelines or other automation (#8009)
- Healthcheck endpoint has a database section: `/api/v2/debug/health`
- Force DERP connections in CLI with `--disable-direct` flag (#8131)
- Disable all direct connections for a Coder deployment with [--block-direct-connections](https://coder.com/docs/v2/latest/cli/server#--block-direct-connections) (#7936)
- Disable all direct connections for a Coder deployment with
[--block-direct-connections](https://coder.com/docs/v2/latest/cli/server#--block-direct-connections)
(#7936)
- Search for workspaces based on last activity (#2658)
```text
last_seen_before:"2023-01-14T23:59:59Z" last_seen_after:"2023-01-08T00:00:00Z"
@ -20,8 +30,11 @@
<img width="1449" alt="Queue position" src="https://github.com/coder/coder/assets/22407953/44515a19-ddfb-4431-8c2a-203487c4efe8">
- Enable Terraform debug mode via deployment configuration (#8260)
- Add github device flow for authentication (#8232)
- Sort Coder parameters with [display_order](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter) property (#8227)
- Users can convert from username/password accounts to OIDC accounts in Account settings (#8105) (@Emyrk)
- Sort Coder parameters with
[display_order](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter)
property (#8227)
- Users can convert from username/password accounts to OIDC accounts in Account
settings (#8105) (@Emyrk)
![Convert account](https://github.com/coder/coder/assets/22407953/6ea28c1c-53d7-4eb5-8113-9a066739820c)
- Show service banner in SSH/TTY sessions (#8186)
- Helm chart now supports RBAC for deployments (#8233)
@ -29,7 +42,8 @@
### Bug fixes
- `coder logout` will not invalidate long-lived API tokens (#8275)
- Helm: use `/healthz` for liveness and readiness probes instead of `/api/v2/buildinfo` (#8035)
- Helm: use `/healthz` for liveness and readiness probes instead of
`/api/v2/buildinfo` (#8035)
- Close output writer before reader on Windows to unblock close (#8299)
- Resize terminal when dismissing warning (#8028)
- Fix footer year (#8036)
@ -57,9 +71,11 @@
- Add default dir for VS Code Desktop (#8184)
- Agent metadata is now GA (#8111) (@bpmct)
- Note SSH key location in workspaces (#8264)
- Update examples of IDEs: remove JetBrains Projector and add VS Code Server (#8310)
- Update examples of IDEs: remove JetBrains Projector and add VS Code Server
(#8310)
Compare: [`v0.24.1...v0.25.0`](https://github.com/coder/coder/compare/v0.24.1...v0.25.0)
Compare:
[`v0.24.1...v0.25.0`](https://github.com/coder/coder/compare/v0.24.1...v0.25.0)
## Container image
@ -67,4 +83,6 @@ Compare: [`v0.24.1...v0.25.0`](https://github.com/coder/coder/compare/v0.24.1...
## Install/upgrade
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or
[upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a
release asset below.

28
docs/changelogs/v0.26.0.md
View File

@ -2,7 +2,9 @@
### Important changes
- [Managed variables](https://coder.com/docs/v2/latest/templates/parameters#terraform-template-wide-variables) are enabled by default. The following block within templates is obsolete and can be removed from your templates:
- [Managed variables](https://coder.com/docs/v2/latest/templates/parameters#terraform-template-wide-variables)
are enabled by default. The following block within templates is obsolete and
can be removed from your templates:
```diff
provider "coder" {
@ -10,19 +12,26 @@
}
```
> The change does not affect your templates because this attribute was previously necessary to activate this additional feature.
> The change does not affect your templates because this attribute was
> previously necessary to activate this additional feature.
- Our scale test CLI is [experimental](https://coder.com/docs/v2/latest/contributing/feature-stages#experimental-features) to allow for rapid iteration. You can still interact with it via `coder exp scaletest` (#8339)
- Our scale test CLI is
[experimental](https://coder.com/docs/v2/latest/contributing/feature-stages#experimental-features)
to allow for rapid iteration. You can still interact with it via
`coder exp scaletest` (#8339)
### Features
- [coder dotfiles](https://coder.com/docs/v2/latest/cli/dotfiles) can checkout a specific branch
- [coder dotfiles](https://coder.com/docs/v2/latest/cli/dotfiles) can checkout a
specific branch
### Bug fixes
- Delay "Workspace build is pending" banner to avoid quick re-render when a workspace is created (#8309)
- Delay "Workspace build is pending" banner to avoid quick re-render when a
workspace is created (#8309)
- `coder stat` handles cgroups with no limits
- Remove concurrency to allow migrations when `coderd` runs on multiple replicas (#8353)
- Remove concurrency to allow migrations when `coderd` runs on multiple replicas
(#8353)
- Pass oauth configs to site (#8390)
- Improve error message for missing action in Audit log (#8335)
- Add missing fields to extract api key config (#8393)
@ -31,7 +40,8 @@
- Resolve nil pointer dereference on missing oauth config (#8352)
- Update fly.io example to remove deprecated parameters (#8194)
Compare: [`v0.25.0...0.26.0`](https://github.com/coder/coder/compare/v0.25.0...v0.26.0)
Compare:
[`v0.25.0...0.26.0`](https://github.com/coder/coder/compare/v0.25.0...v0.26.0)
## Container image
@ -39,4 +49,6 @@ Compare: [`v0.25.0...0.26.0`](https://github.com/coder/coder/compare/v0.25.0...v
## Install/upgrade
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or
[upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a
release asset below.

16
docs/changelogs/v0.26.1.md
View File

@ -2,13 +2,16 @@
### Features
- [Devcontainer templates](https://coder.com/docs/v2/latest/templates/devcontainers) for Coder (#8256)
- [Devcontainer templates](https://coder.com/docs/v2/latest/templates/devcontainers)
for Coder (#8256)
- The dashboard will warn users when a workspace is unhealthy (#8422)
- Audit logs `resource_target` search query allows you to search by resource name (#8423)
- Audit logs `resource_target` search query allows you to search by resource
name (#8423)
### Refactors
- [pgCoordinator](https://github.com/coder/coder/pull/8044) is generally available (#8419)
- [pgCoordinator](https://github.com/coder/coder/pull/8044) is generally
available (#8419)
### Bug fixes
@ -19,7 +22,8 @@
- Document workspace filter query param correctly (#8408)
- Use numeric comparison to check monotonicity (#8436)
Compare: [`v0.26.0...v0.26.1`](https://github.com/coder/coder/compare/v0.26.0...v0.26.1)
Compare:
[`v0.26.0...v0.26.1`](https://github.com/coder/coder/compare/v0.26.0...v0.26.1)
## Container image
@ -27,4 +31,6 @@ Compare: [`v0.26.0...v0.26.1`](https://github.com/coder/coder/compare/v0.26.0...
## Install/upgrade
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or
[upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a
release asset below.

60
docs/changelogs/v0.27.0.md
View File

@ -4,26 +4,34 @@
Agent logs can be pushed after a workspace has started (#8528)
> ⚠️ **Warning:** You will need to [update](https://coder.com/docs/v2/latest/install) your local Coder CLI v0.27 to connect via `coder ssh`.
> ⚠️ **Warning:** You will need to
> [update](https://coder.com/docs/v2/latest/install) your local Coder CLI v0.27
> to connect via `coder ssh`.
### Features
- [Empeheral parameters](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter#ephemeral) allow users to specify a value for a single build (#8415) (#8524)
- [Empeheral parameters](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter#ephemeral)
allow users to specify a value for a single build (#8415) (#8524)
![Ephemeral parameters](https://github.com/coder/coder/assets/22407953/89df0888-9abc-453a-ac54-f5d0e221b0b9)
> Upgrade to Coder Terraform Provider v0.11.1 to use ephemeral parameters in your templates
> Upgrade to Coder Terraform Provider v0.11.1 to use ephemeral parameters in
> your templates
- Create template, if it doesn't exist with `templates push --create` (#8454)
- Workspaces now appear `unhealthy` in the dashboard and CLI if one or more agents do not exist (#8541) (#8548)
- Workspaces now appear `unhealthy` in the dashboard and CLI if one or more
agents do not exist (#8541) (#8548)
![Workspace health](https://github.com/coder/coder/assets/22407953/edbb1d70-61b5-4b45-bfe8-51abdab417cc)
- Reverse port-forward with `coder ssh -R` (#8515)
- Helm: custom command arguments in Helm chart (#8567)
- Template version messages (#8435)
<img width="428" alt="252772262-087f1338-f1e2-49fb-81f2-358070a46484" src="https://github.com/coder/coder/assets/22407953/5f6e5e47-e61b-41f1-92fe-f624e92f8bd3">
- TTL and max TTL validation increased to 30 days (#8258)
- [Self-hosted docs](https://coder.com/docs/v2/latest/install/offline#offline-docs): Host your own copy of Coder's documentation in your own environment (#8527) (#8601)
- [Self-hosted docs](https://coder.com/docs/v2/latest/install/offline#offline-docs):
Host your own copy of Coder's documentation in your own environment (#8527)
(#8601)
- Add custom coder bin path for `config-ssh` (#8425)
- Admins can create workspaces for other users via the CLI (#8481)
- `coder_app` supports localhost apps running https (#8585)
- Base container image contains [jq](https://github.com/coder/coder/pull/8563) for parsing mounted JSON secrets
- Base container image contains [jq](https://github.com/coder/coder/pull/8563)
for parsing mounted JSON secrets
### Bug fixes
@ -31,7 +39,8 @@ Agent logs can be pushed after a workspace has started (#8528)
- `coder stat` fixes
- Read from alternate cgroup path (#8591)
- Improve detection of container environment (#8643)
- Unskip TestStatCPUCmd/JSON and explicitly set --host in test cmd invocation (#8558)
- Unskip TestStatCPUCmd/JSON and explicitly set --host in test cmd invocation
(#8558)
- Avoid initial license reconfig if feature isn't enabled (#8586)
- Audit log records delete workspace action properly (#8494)
- Audit logs are properly paginated (#8513)
@ -47,26 +56,34 @@ Agent logs can be pushed after a workspace has started (#8528)
Agent logs can be pushed after a workspace has started (#8528)
> ⚠️ **Warning:** You will need to [update](https://coder.com/docs/v2/latest/install) your local Coder CLI v0.27 to connect via `coder ssh`.
> ⚠️ **Warning:** You will need to
> [update](https://coder.com/docs/v2/latest/install) your local Coder CLI v0.27
> to connect via `coder ssh`.
### Features
- [Empeheral parameters](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter#ephemeral) allow users to specify a value for a single build (#8415) (#8524)
- [Empeheral parameters](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter#ephemeral)
allow users to specify a value for a single build (#8415) (#8524)
![Ephemeral parameters](https://github.com/coder/coder/assets/22407953/89df0888-9abc-453a-ac54-f5d0e221b0b9)
> Upgrade to Coder Terraform Provider v0.11.1 to use ephemeral parameters in your templates
> Upgrade to Coder Terraform Provider v0.11.1 to use ephemeral parameters in
> your templates
- Create template, if it doesn't exist with `templates push --create` (#8454)
- Workspaces now appear `unhealthy` in the dashboard and CLI if one or more agents do not exist (#8541) (#8548)
- Workspaces now appear `unhealthy` in the dashboard and CLI if one or more
agents do not exist (#8541) (#8548)
![Workspace health](https://github.com/coder/coder/assets/22407953/edbb1d70-61b5-4b45-bfe8-51abdab417cc)
- Reverse port-forward with `coder ssh -R` (#8515)
- Helm: custom command arguments in Helm chart (#8567)
- Template version messages (#8435)
<img width="428" alt="252772262-087f1338-f1e2-49fb-81f2-358070a46484" src="https://github.com/coder/coder/assets/22407953/5f6e5e47-e61b-41f1-92fe-f624e92f8bd3">
- TTL and max TTL validation increased to 30 days (#8258)
- [Self-hosted docs](https://coder.com/docs/v2/latest/install/offline#offline-docs): Host your own copy of Coder's documentation in your own environment (#8527) (#8601)
- [Self-hosted docs](https://coder.com/docs/v2/latest/install/offline#offline-docs):
Host your own copy of Coder's documentation in your own environment (#8527)
(#8601)
- Add custom coder bin path for `config-ssh` (#8425)
- Admins can create workspaces for other users via the CLI (#8481)
- `coder_app` supports localhost apps running https (#8585)
- Base container image contains [jq](https://github.com/coder/coder/pull/8563) for parsing mounted JSON secrets
- Base container image contains [jq](https://github.com/coder/coder/pull/8563)
for parsing mounted JSON secrets
### Bug fixes
@ -74,7 +91,8 @@ Agent logs can be pushed after a workspace has started (#8528)
- `coder stat` fixes
- Read from alternate cgroup path (#8591)
- Improve detection of container environment (#8643)
- Unskip TestStatCPUCmd/JSON and explicitly set --host in test cmd invocation (#8558)
- Unskip TestStatCPUCmd/JSON and explicitly set --host in test cmd invocation
(#8558)
- Avoid initial license reconfig if feature isn't enabled (#8586)
- Audit log records delete workspace action properly (#8494)
- Audit logs are properly paginated (#8513)
@ -88,7 +106,8 @@ Agent logs can be pushed after a workspace has started (#8528)
- Docs on using remote Docker hosts (#8479)
- Added kubernetes option to workspace proxies (#8533)
Compare: [`v0.26.1...v0.26.2`](https://github.com/coder/coder/compare/v0.26.1...v0.27.0)
Compare:
[`v0.26.1...v0.26.2`](https://github.com/coder/coder/compare/v0.26.1...v0.27.0)
## Container image
@ -96,13 +115,16 @@ Compare: [`v0.26.1...v0.26.2`](https://github.com/coder/coder/compare/v0.26.1...
## Install/upgrade
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or
[upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a
release asset below.
- Custom API use cases (custom agent logs, CI/CD pipelines) (#8445)
- Docs on using remote Docker hosts (#8479)
- Added kubernetes option to workspace proxies (#8533)
Compare: [`v0.26.1...v0.26.2`](https://github.com/coder/coder/compare/v0.26.1...v0.27.0)
Compare:
[`v0.26.1...v0.26.2`](https://github.com/coder/coder/compare/v0.26.1...v0.27.0)
## Container image
@ -110,4 +132,6 @@ Compare: [`v0.26.1...v0.26.2`](https://github.com/coder/coder/compare/v0.26.1...
## Install/upgrade
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or
[upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a
release asset below.

7
docs/changelogs/v0.27.1.md
View File

@ -12,7 +12,8 @@
- Add steps for postgres SSL cert config (#8648)
Compare: [`v0.27.0...v0.27.1`](https://github.com/coder/coder/compare/v0.27.0...v0.27.1)
Compare:
[`v0.27.0...v0.27.1`](https://github.com/coder/coder/compare/v0.27.0...v0.27.1)
## Container image
@ -20,4 +21,6 @@ Compare: [`v0.27.0...v0.27.1`](https://github.com/coder/coder/compare/v0.27.0...
## Install/upgrade
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or
[upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a
release asset below.

7
docs/changelogs/v0.27.3.md
View File

@ -6,7 +6,8 @@
- be2e6f443 fix(enterprise): ensure creating a SCIM user is idempotent (#8730)
Compare: [`v0.27.2...v0.27.3`](https://github.com/coder/coder/compare/v0.27.2...v0.27.3)
Compare:
[`v0.27.2...v0.27.3`](https://github.com/coder/coder/compare/v0.27.2...v0.27.3)
## Container image
@ -14,4 +15,6 @@ Compare: [`v0.27.2...v0.27.3`](https://github.com/coder/coder/compare/v0.27.2...
## Install/upgrade
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or
[upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a
release asset below.

130
docs/changelogs/v2.0.0.md
View File

@ -1,60 +1,106 @@
We are thrilled to release Coder v2.0.0. You can safely upgrade from any previous
[coder/coder](https://github.com/coder/coder) release,
but we feel like we have outgrown development (v0.x) releases:
We are thrilled to release Coder v2.0.0. You can safely upgrade from any
previous [coder/coder](https://github.com/coder/coder) release, but we feel like
we have outgrown development (v0.x) releases:
- 1600+ users develop on Coder every day
- A single 4-core Coder server can [happily support](https://coder.com/docs/v2/latest/admin/scale) 1000+ users and workspace connections
- We have a full suite of [paid features](https://coder.com/docs/v2/latest/enterprise) and enterprise customers deployed in production
- Users depend on our CLI to [automate Coder](https://coder.com/docs/v2/latest/admin/automation) in Ci/Cd pipelines and templates
- A single 4-core Coder server can
[happily support](https://coder.com/docs/v2/latest/admin/scale) 1000+ users
and workspace connections
- We have a full suite of
[paid features](https://coder.com/docs/v2/latest/enterprise) and enterprise
customers deployed in production
- Users depend on our CLI to
[automate Coder](https://coder.com/docs/v2/latest/admin/automation) in Ci/Cd
pipelines and templates
Why not v1.0? At the time of writing, our legacy product is currently on v1.34. While Coder v1 is being sunset, we still wanted to avoid versioning conflicts.
Why not v1.0? At the time of writing, our legacy product is currently on v1.34.
While Coder v1 is being sunset, we still wanted to avoid versioning conflicts.
What is not changing:
- Our feature roadmap: See what we have planned at https://coder.com/roadmap
- Your upgrade path: You can safely upgrade from previous coder/coder releases to v2.x releases!
- Our release cadence: We want features out as quickly as possible and feature flag any work that isn’t ready for production yet!
- Your upgrade path: You can safely upgrade from previous coder/coder releases
to v2.x releases!
- Our release cadence: We want features out as quickly as possible and feature
flag any work that isn’t ready for production yet!
What is changing:
- Our deprecation policy: Major features will be deprecated for at least 1 minor release before being removed. Any breaking changes to the REST API and SDK are done via minor releases and will be called out in our changelog.
- Regular scale testing: Follow along on our [ Google Sheets or Grafana dashboard ]
- Our deprecation policy: Major features will be deprecated for at least 1 minor
release before being removed. Any breaking changes to the REST API and SDK are
done via minor releases and will be called out in our changelog.
- Regular scale testing: Follow along on our [ Google Sheets or Grafana
dashboard ]
Questions? Feel free to ask in [our Discord](https://discord.gg/coder) or email ben@coder.com!
Questions? Feel free to ask in [our Discord](https://discord.gg/coder) or email
ben@coder.com!
## Changelog
### BREAKING CHANGES
- RBAC: The default [Member role](https://coder.com/docs/v2/latest/admin/users) can no longer see a list of all users in a Coder deployment. The Template Admin role and above can still use the `Users` page in dashboard and query users via the API (#8650) (@Emyrk)
- Kubernetes (Helm): The [default ServiceAccount](https://github.com/coder/coder/blob/8d0e8f45e0fb3802d777a396b4c027ab9788e1b8/helm/values.yaml#L67-L82) for Coder can provision `Deployments` on the cluster. (#8704) (@ericpaulsen)
- This can be disabled by a [Helm value](https://github.com/coder/coder/blob/8d0e8f45e0fb3802d777a396b4c027ab9788e1b8/helm/values.yaml#L78)
- Our [Kubernetes example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes) uses a `kubernetes_deployment` instead of `kubernetes_pod` since it works best with [log streaming](https://coder.com/docs/v2/latest/platforms/kubernetes/deployment-logs) in Coder.
- RBAC: The default [Member role](https://coder.com/docs/v2/latest/admin/users)
can no longer see a list of all users in a Coder deployment. The Template
Admin role and above can still use the `Users` page in dashboard and query
users via the API (#8650) (@Emyrk)
- Kubernetes (Helm): The
[default ServiceAccount](https://github.com/coder/coder/blob/8d0e8f45e0fb3802d777a396b4c027ab9788e1b8/helm/values.yaml#L67-L82)
for Coder can provision `Deployments` on the cluster. (#8704) (@ericpaulsen)
- This can be disabled by a
[Helm value](https://github.com/coder/coder/blob/8d0e8f45e0fb3802d777a396b4c027ab9788e1b8/helm/values.yaml#L78)
- Our
[Kubernetes example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes)
uses a `kubernetes_deployment` instead of `kubernetes_pod` since it works
best with
[log streaming](https://coder.com/docs/v2/latest/platforms/kubernetes/deployment-logs)
in Coder.
### Features
- Template insights: Admins can see daily active users, user latency, and popular IDEs (#8722) (@BrunoQuaresma)
- Template insights: Admins can see daily active users, user latency, and
popular IDEs (#8722) (@BrunoQuaresma)
![Template insights](https://user-images.githubusercontent.com/22407953/258239988-69641bd6-28da-4c60-9ae7-c0b1bba53859.png)
- [Kubernetes log streaming](https://coder.com/docs/v2/latest/platforms/kubernetes/deployment-logs): Stream Kubernetes event logs to the Coder agent logs to reveal Kuernetes-level issues such as ResourceQuota limitations, invalid images, etc.
- [Kubernetes log streaming](https://coder.com/docs/v2/latest/platforms/kubernetes/deployment-logs):
Stream Kubernetes event logs to the Coder agent logs to reveal Kuernetes-level
issues such as ResourceQuota limitations, invalid images, etc.
![Kubernetes quota](https://raw.githubusercontent.com/coder/coder/main/docs/platforms/kubernetes/coder-logstream-kube-logs-quota-exceeded.png)
- [OIDC Role Sync](https://coder.com/docs/v2/latest/admin/auth#group-sync-enterprise) (Enterprise): Sync roles from your OIDC provider to Coder roles (e.g. `Template Admin`) (#8595) (@Emyrk)
- Users can convert their accounts from username/password authentication to SSO by linking their account (#8742) (@Emyrk)
- [OIDC Role Sync](https://coder.com/docs/v2/latest/admin/auth#group-sync-enterprise)
(Enterprise): Sync roles from your OIDC provider to Coder roles (e.g.
`Template Admin`) (#8595) (@Emyrk)
- Users can convert their accounts from username/password authentication to SSO
by linking their account (#8742) (@Emyrk)
![Converting OIDC accounts](https://user-images.githubusercontent.com/22407953/257408767-5b136476-99d1-4052-aeec-fe2a42618e04.png)
- CLI: Added `--var` shorthand for `--variable` in `coder templates <create/push>` CLI (#8710) (@ammario)
- Accounts are marked as dormant after 90 days of inactivity and do not consume a license seat. When the user logs in again, their account status is reinstated. (#8644) (@mtojek)
- Groups can have a non-unique display name that takes priority in the dashboard (#8740) (@Emyrk)
- Dotfiles: Coder checks if dotfiles install script is executable (#8588) (@BRAVO68WEB)
- CLI: Added `--var` shorthand for `--variable` in `coder templates <create/push>` CLI (#8710) (@ammario)
- Sever logs: Added fine-grained [filtering](https://coder.com/docs/v2/latest/cli/server#-l---log-filter) with Regex (#8748) (@ammario)
- d3991fac2 feat(coderd): add parameter insights to template insights (#8656) (@mafredri)
- Agent metadata: In cases where Coder does not receive metadata in time, we render the previous "stale" value. Stale values are grey versus the typical green color. (#8745) (@BrunoQuaresma)
- [Open in Coder](https://coder.com/docs/v2/latest/templates/open-in-coder): Generate a link that automatically creates a workspace on behalf of the user, skipping the "Create Workspace" form (#8651) (@BrunoQuaresma)
![Open in Coder](https://user-images.githubusercontent.com/22407953/257410429-712de64d-ea2c-4520-8abf-0a9ba5a16e7a.png)- e85b88ca9 feat(site): add restart button when workspace is unhealthy (#8765) (@BrunoQuaresma)
- CLI: Added `--var` shorthand for `--variable` in
`coder templates <create/push>` CLI (#8710) (@ammario)
- Accounts are marked as dormant after 90 days of inactivity and do not consume
a license seat. When the user logs in again, their account status is
reinstated. (#8644) (@mtojek)
- Groups can have a non-unique display name that takes priority in the dashboard
(#8740) (@Emyrk)
- Dotfiles: Coder checks if dotfiles install script is executable (#8588)
(@BRAVO68WEB)
- CLI: Added `--var` shorthand for `--variable` in
`coder templates <create/push>` CLI (#8710) (@ammario)
- Sever logs: Added fine-grained
[filtering](https://coder.com/docs/v2/latest/cli/server#-l---log-filter) with
Regex (#8748) (@ammario)
- d3991fac2 feat(coderd): add parameter insights to template insights (#8656)
(@mafredri)
- Agent metadata: In cases where Coder does not receive metadata in time, we
render the previous "stale" value. Stale values are grey versus the typical
green color. (#8745) (@BrunoQuaresma)
- [Open in Coder](https://coder.com/docs/v2/latest/templates/open-in-coder):
Generate a link that automatically creates a workspace on behalf of the user,
skipping the "Create Workspace" form (#8651) (@BrunoQuaresma)
![Open in Coder](https://user-images.githubusercontent.com/22407953/257410429-712de64d-ea2c-4520-8abf-0a9ba5a16e7a.png)-
e85b88ca9 feat(site): add restart button when workspace is unhealthy (#8765)
(@BrunoQuaresma)
### Bug fixes
- Do not wait for devcontainer template volume claim bound (#8539) (@Tirzono)
- Prevent repetition of template IDs in `template_usage_by_day` (#8693) (@mtojek)
- Prevent repetition of template IDs in `template_usage_by_day` (#8693)
(@mtojek)
- Unify parameter validation errors (#8738) (@mtojek)
- Request trial after password is validated (#8750) (@kylecarbs)
- Fix `coder stat mem` calculation for cgroup v1 workspaces (#8762) (@sreya)
@ -62,15 +108,18 @@ Questions? Feel free to ask in [our Discord](https://discord.gg/coder) or email
- Fix tailnet netcheck issues (#8802) (@deansheather)
- Avoid infinite loop in agent derp-map (#8848) (@deansheather)
- Avoid agent runLoop exiting due to ws ping (#8852) (@deansheather)
- Add read call to derp-map endpoint to avoid ws ping timeout (#8859) (@deansheather)
- Add read call to derp-map endpoint to avoid ws ping timeout (#8859)
(@deansheather)
- Show current DERP name correctly in vscode (#8856) (@deansheather)
- Apply log-filter to debug logs only (#8751) (@ammario)
- Correctly print deprecated warnings (#8771) (@ammario)
- De-duplicate logs (#8686) (@ammario)
- Always dial agents with `WorkspaceAgentIP` (#8760) (@coadler)
- Ensure creating a SCIM user is idempotent (#8730) (@coadler)
- Send build parameters over the confirmation dialog on restart (#8660) (@BrunoQuaresma)
- Fix error 'Reduce of empty array with no initial value' (#8700) (@BrunoQuaresma)
- Send build parameters over the confirmation dialog on restart (#8660)
(@BrunoQuaresma)
- Fix error 'Reduce of empty array with no initial value' (#8700)
(@BrunoQuaresma)
- Fix latency values (#8749) (@BrunoQuaresma)
- Fix metadata value changing width all the time (#8780) (@BrunoQuaresma)
- Show error when user exists (#8864) (@BrunoQuaresma)
@ -80,14 +129,17 @@ Questions? Feel free to ask in [our Discord](https://discord.gg/coder) or email
### Documentation
- Explain JFrog integration 🐸 (#8682) (@ammario)
- Allow multiple Coder deployments to use single GitHub OAuth app (#8786) (@matifali)
- Allow multiple Coder deployments to use single GitHub OAuth app (#8786)
(@matifali)
- Remove Microsoft VS Code Server docs (#8845) (@ericpaulsen)
### Reverts
- Make [pgCoordinator](https://github.com/coder/coder/pull/8044) experimental again (#8797) (@coadler)
- Make [pgCoordinator](https://github.com/coder/coder/pull/8044) experimental
again (#8797) (@coadler)
Compare: [`v0.27.0...v2.0.0`](https://github.com/coder/coder/compare/v0.27.0...v2.0.0)
Compare:
[`v0.27.0...v2.0.0`](https://github.com/coder/coder/compare/v0.27.0...v2.0.0)
## Container image
@ -95,4 +147,6 @@ Compare: [`v0.27.0...v2.0.0`](https://github.com/coder/coder/compare/v0.27.0...v
## Install/upgrade
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or
[upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a
release asset below.

52
docs/changelogs/v2.0.2.md
View File

@ -2,19 +2,35 @@
### Features
- [External provisioners](https://coder.com/docs/v2/latest/admin/provisioners) updates
- Added [PSK authentication](https://coder.com/docs/v2/latest/admin/provisioners#authentication) method (#8877) (@spikecurtis)
- Provisioner daemons can be deployed [via Helm](https://github.com/coder/coder/tree/main/helm/provisioner) (#8939) (@spikecurtis)
- Added login type (OIDC, GitHub, or built-in, or none) to users page (#8912) (@Emyrk)
- Groups can be [automatically created](https://coder.com/docs/v2/latest/admin/auth#user-not-being-assigned--group-does-not-exist) from OIDC group sync (#8884) (@Emyrk)
- Parameter values can be specified via the [command line](https://coder.com/docs/v2/latest/cli/create#--parameter) during workspace creation/updates (#8898) (@mtojek)
- Added date range picker for the template insights page (#8976) (@BrunoQuaresma)
- We now publish preview [container images](https://github.com/coder/coder/pkgs/container/coder-preview) on every commit to `main`. Only use these images for testing. They are automatically deleted after 7 days.
- Coder is [officially listed JetBrains Gateway](https://coder.com/blog/self-hosted-remote-development-in-jetbrains-ides-now-available-to-coder-users).
- [External provisioners](https://coder.com/docs/v2/latest/admin/provisioners)
updates
- Added
[PSK authentication](https://coder.com/docs/v2/latest/admin/provisioners#authentication)
method (#8877) (@spikecurtis)
- Provisioner daemons can be deployed
[via Helm](https://github.com/coder/coder/tree/main/helm/provisioner)
(#8939) (@spikecurtis)
- Added login type (OIDC, GitHub, or built-in, or none) to users page (#8912)
(@Emyrk)
- Groups can be
[automatically created](https://coder.com/docs/v2/latest/admin/auth#user-not-being-assigned--group-does-not-exist)
from OIDC group sync (#8884) (@Emyrk)
- Parameter values can be specified via the
[command line](https://coder.com/docs/v2/latest/cli/create#--parameter) during
workspace creation/updates (#8898) (@mtojek)
- Added date range picker for the template insights page (#8976)
(@BrunoQuaresma)
- We now publish preview
[container images](https://github.com/coder/coder/pkgs/container/coder-preview)
on every commit to `main`. Only use these images for testing. They are
automatically deleted after 7 days.
- Coder is
[officially listed JetBrains Gateway](https://coder.com/blog/self-hosted-remote-development-in-jetbrains-ides-now-available-to-coder-users).
### Bug fixes
- Don't close other web terminal or `coder_app` sessions during a terminal close (#8917)
- Don't close other web terminal or `coder_app` sessions during a terminal close
(#8917)
- Properly refresh OIDC tokens (#8950) (@Emyrk)
- Added backoff to validate fresh git auth tokens (#8956) (@kylecarbs)
- Make preferred region the first in list (#9014) (@matifali)
@ -23,12 +39,16 @@
- Ensure SCIM create user can unsuspend (#8916)
- Set correct Prometheus port in Helm notes (#8888)
- Show user avatar on group page (#8997) (@BrunoQuaresma)
- Make deployment stats bar scrollable on smaller viewports (#8996) (@BrunoQuaresma)
- Make deployment stats bar scrollable on smaller viewports (#8996)
(@BrunoQuaresma)
- Add horizontal scroll to template viewer (#8998) (@BrunoQuaresma)
- Persist search parameters when user has to authenticate (#9005) (@BrunoQuaresma)
- Set default color and display error on appearance form (#9004) (@BrunoQuaresma)
- Persist search parameters when user has to authenticate (#9005)
(@BrunoQuaresma)
- Set default color and display error on appearance form (#9004)
(@BrunoQuaresma)
Compare: [`v2.0.1...v2.0.2`](https://github.com/coder/coder/compare/v2.0.1...v2.0.2)
Compare:
[`v2.0.1...v2.0.2`](https://github.com/coder/coder/compare/v2.0.1...v2.0.2)
## Container image
@ -36,4 +56,6 @@ Compare: [`v2.0.1...v2.0.2`](https://github.com/coder/coder/compare/v2.0.1...v2.
## Install/upgrade
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or
[upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a
release asset below.

47
docs/changelogs/v2.1.0.md
View File

@ -2,20 +2,36 @@
### Important changes
- We removed `jq` from our base image. In the unlikely case you use `jq` for fetching Coder's database secret or other values, you'll need to build your own Coder image. Click [here](https://gist.github.com/bpmct/05cfb671d1d468ae3be46e93173a02ea) to learn more. (#8979) (@ericpaulsen)
- We removed `jq` from our base image. In the unlikely case you use `jq` for
fetching Coder's database secret or other values, you'll need to build your
own Coder image. Click
[here](https://gist.github.com/bpmct/05cfb671d1d468ae3be46e93173a02ea) to
learn more. (#8979) (@ericpaulsen)
### Features
- You can manually add OIDC or GitHub users (#9000) (@Emyrk)
![Manual add user](https://user-images.githubusercontent.com/22407953/261455971-adf2707c-93a7-49c6-be5d-2ec177e224b9.png)
> Use this with the [CODER_OIDC_ALLOW_SIGNUPS](https://coder.com/docs/v2/latest/cli/server#--oidc-allow-signups) flag to manually onboard users before opening the floodgates to every user in your identity provider!
- CLI: The [--header-command](https://coder.com/docs/v2/latest/cli#--header-command) flag can leverage external services to provide dynamic headers to authenticate to a Coder deployment behind an application proxy or VPN (#9059) (@code-asher)
- OIDC: Add support for Azure OIDC PKI auth instead of client secret (#9054) (@Emyrk)
> Use this with the
> [CODER_OIDC_ALLOW_SIGNUPS](https://coder.com/docs/v2/latest/cli/server#--oidc-allow-signups)
> flag to manually onboard users before opening the floodgates to every user
> in your identity provider!
- CLI: The
[--header-command](https://coder.com/docs/v2/latest/cli#--header-command) flag
can leverage external services to provide dynamic headers to authenticate to a
Coder deployment behind an application proxy or VPN (#9059) (@code-asher)
- OIDC: Add support for Azure OIDC PKI auth instead of client secret (#9054)
(@Emyrk)
- Helm chart updates:
- Add terminationGracePeriodSeconds to provisioner chart (#9048) (@spikecurtis)
- Add terminationGracePeriodSeconds to provisioner chart (#9048)
(@spikecurtis)
- Add support for NodePort service type (#8993) (@ffais)
- Published [external provisioner chart](https://coder.com/docs/v2/latest/admin/provisioners#example-running-an-external-provisioner-with-helm) to release and docs (#9050) (@spikecurtis)
- Exposed everyone group through UI. You can now set [quotas](https://coder.com/docs/v2/latest/admin/quotas) for the `Everyone` group. (#9117) (@sreya)
- Published
[external provisioner chart](https://coder.com/docs/v2/latest/admin/provisioners#example-running-an-external-provisioner-with-helm)
to release and docs (#9050) (@spikecurtis)
- Exposed everyone group through UI. You can now set
[quotas](https://coder.com/docs/v2/latest/admin/quotas) for the `Everyone`
group. (#9117) (@sreya)
- Workspace build errors are shown as a tooltip (#9029) (@BrunoQuaresma)
- Add build log history to the build log page (#9150) (@BrunoQuaresma)
![Build log history](https://user-images.githubusercontent.com/22407953/261457020-3fbbb274-1e32-4116-affb-4a5ac271110b.png)
@ -25,8 +41,10 @@
- Correct GitHub oauth2 callback url (#9052) (@Emyrk)
- Remove duplication from language of query param error (#9069) (@kylecarbs)
- Remove unnecessary newlines from the end of cli output (#9068) (@kylecarbs)
- Change dashboard route `/settings/deployment` to `/deployment` (#9070) (@kylecarbs)
- Use screen for reconnecting terminal sessions on Linux if available (#8640) (@code-asher)
- Change dashboard route `/settings/deployment` to `/deployment` (#9070)
(@kylecarbs)
- Use screen for reconnecting terminal sessions on Linux if available (#8640)
(@code-asher)
- Catch missing output with reconnecting PTY (#9094) (@code-asher)
- Fix deadlock on tailnet close (#9079) (@spikecurtis)
- Rename group GET request (#9097) (@ericpaulsen)
@ -40,9 +58,12 @@
### Documentation
- Add [offline docs](https://www.jetbrains.com/help/idea/fully-offline-mode.html) for JetBrains Gateway (#9039) (@ericpaulsen)
- Add
[offline docs](https://www.jetbrains.com/help/idea/fully-offline-mode.html)
for JetBrains Gateway (#9039) (@ericpaulsen)
- Add `coder login` to CI docs (#9038) (@ericpaulsen)
- Expand [JFrog platform](https://coder.com/docs/v2/latest/platforms/jfrog) and example template (#9073) (@matifali)
- Expand [JFrog platform](https://coder.com/docs/v2/latest/platforms/jfrog) and
example template (#9073) (@matifali)
## Container image
@ -50,4 +71,6 @@
## Install/upgrade
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or
[upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a
release asset below.

28
docs/changelogs/v2.1.1.md
View File

@ -2,18 +2,27 @@
### Features
- Add `last_used` search params to workspaces. This can be used to find inactive workspaces (#9230) (@Emyrk)
- Add `last_used` search params to workspaces. This can be used to find inactive
workspaces (#9230) (@Emyrk)
![Last used](https://user-images.githubusercontent.com/22407953/262407146-06cded4e-684e-4cff-86b7-4388270e7d03.png)
> You can use `last_used_before` and `last_used_after` in the workspaces search with [RFC3339Nano](RFC3339Nano) datetimes
- Add `daily_cost`` to `coder ls` to show [quota](https://coder.com/docs/v2/latest/admin/quotas) consumption (#9200) (@ammario)
> You can use `last_used_before` and `last_used_after` in the workspaces
> search with [RFC3339Nano](RFC3339Nano) datetimes
- Add `daily_cost`` to `coder ls` to show
[quota](https://coder.com/docs/v2/latest/admin/quotas) consumption (#9200)
(@ammario)
- Added `coder_app` usage to template insights (#9138) (@mafredri)
![code-server usage](https://user-images.githubusercontent.com/22407953/262412524-180390de-b1a9-4d57-8473-c8774ec3fd6e.png)
- Added documentation for [workspace process logging](http://localhost:3000/docs/v2/latest/templates/process-logging). This enterprise feature can be used to log all system-level processes in workspaces. (#9002) (@deansheather)
- Added documentation for
[workspace process logging](http://localhost:3000/docs/v2/latest/templates/process-logging).
This enterprise feature can be used to log all system-level processes in
workspaces. (#9002) (@deansheather)
### Bug fixes
- Avoid temporary license banner when Coder is upgraded via Helm + button to refresh license entitlements (#9155) (@Emyrk)
- Parameters in the page "Create workspace" will show the display name as the primary field (#9158) (@aslilac)
- Avoid temporary license banner when Coder is upgraded via Helm + button to
refresh license entitlements (#9155) (@Emyrk)
- Parameters in the page "Create workspace" will show the display name as the
primary field (#9158) (@aslilac)
![Parameter order](https://user-images.githubusercontent.com/418348/261439836-e7e7d9bd-9204-42be-8d13-eae9a9afd17c.png)
- Fix race in PGCoord at startup (#9144) (@spikecurtis)
- Do not install strace on OSX (#9167) (@mtojek)
@ -26,7 +35,8 @@
- Remove prompt for immutable parameters on start and restart (#9173) (@mtojek)
- Server logs: apply filter to log message as well as name (#9232) (@ammario)
Compare: [`v2.1.0...v2.1.1`](https://github.com/coder/coder/compare/v2.1.0...v2.1.1)
Compare:
[`v2.1.0...v2.1.1`](https://github.com/coder/coder/compare/v2.1.0...v2.1.1)
## Container image
@ -34,4 +44,6 @@ Compare: [`v2.1.0...v2.1.1`](https://github.com/coder/coder/compare/v2.1.0...v2.
## Install/upgrade
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or
[upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a
release asset below.

9
docs/cli.md
View File

@ -94,7 +94,8 @@ Path to the global `coder` config directory.
| Type | <code>string-array</code> |
| Environment | <code>$CODER_HEADER</code> |
Additional HTTP headers added to all requests. Provide as key=value. Can be specified multiple times.
Additional HTTP headers added to all requests. Provide as key=value. Can be
specified multiple times.
### --header-command
@ -103,7 +104,8 @@ Additional HTTP headers added to all requests. Provide as key=value. Can be spec
| Type | <code>string</code> |
| Environment | <code>$CODER_HEADER_COMMAND</code> |
An external command that outputs additional HTTP headers added to all requests. The command must output each header as `key=value` on its own line.
An external command that outputs additional HTTP headers added to all requests.
The command must output each header as `key=value` on its own line.
### --no-feature-warning
@ -130,7 +132,8 @@ Suppress warning when client and server versions do not match.
| Type | <code>string</code> |
| Environment | <code>$CODER_SESSION_TOKEN</code> |
Specify an authentication token. For security reasons setting CODER_SESSION_TOKEN is preferred.
Specify an authentication token. For security reasons setting
CODER_SESSION_TOKEN is preferred.
### --url

31
docs/contributing/CODE_OF_CONDUCT.md
View File

@ -5,9 +5,9 @@
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, sex characteristics, gender identity and expression,
level of experience, education, socio-economic status, nationality, personal
appearance, race, religion, or sexual identity and orientation.
size, disability, ethnicity, sex characteristics, gender identity and
expression, level of experience, education, socio-economic status, nationality,
personal appearance, race, religion, or sexual identity and orientation.
## Our Standards
@ -37,11 +37,11 @@ Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.
Project maintainers have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, or to ban temporarily or permanently any
contributor for other behaviors that they deem inappropriate, threatening,
offensive, or harmful.
## Scope
@ -55,11 +55,11 @@ further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at opensource@coder.com. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.
reported by contacting the project team at opensource@coder.com. All complaints
will be reviewed and investigated and will result in a response that is deemed
necessary and appropriate to the circumstances. The project team is obligated to
maintain confidentiality with regard to the reporter of an incident. Further
details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
@ -67,8 +67,9 @@ members of the project's leadership.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 1.4, available at
https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
[homepage]: https://www.contributor-covenant.org

4
docs/contributing/SECURITY.md
View File

@ -1,4 +1,4 @@
# Security Policy
If you find a vulnerability, **DO NOT FILE AN ISSUE**.
Instead, send an email to security@coder.com.
If you find a vulnerability, **DO NOT FILE AN ISSUE**. Instead, send an email to
security@coder.com.

31
docs/contributing/documentation.md
View File

@ -10,12 +10,12 @@ This style guide is primarily for use with authoring documentation.
- Use plural nouns and pronouns (_they_, _their_, or _them_), especially when
the specific number is uncertain (i.e., "Set up your environments" even though
you don't know if the user will have one or many environments)
- When writing documentation titles, use the noun form, not the gerund form (e.g., "Environment
Management" instead of "Managing Environments")
- When writing documentation titles, use the noun form, not the gerund form
(e.g., "Environment Management" instead of "Managing Environments")
- Context matters when you decide whether to capitalize something or not. For
example, ["A Job creates one or more
Pods..."](https://kubernetes.io/docs/concepts/workloads/controllers/job/) is
correct when writing about Kubernetes. However, in other contexts, neither
example,
["A Job creates one or more Pods..."](https://kubernetes.io/docs/concepts/workloads/controllers/job/)
is correct when writing about Kubernetes. However, in other contexts, neither
_job_ nor _pods_ would be capitalized. Please follow the conventions set forth
by the relevant companies and open source communities.
@ -79,8 +79,8 @@ For code that you want users to enter via a command-line interface, use
### Punctuation
Do not use the ampersand (&) as a shorthand for _and_ unless you're referring to a
UI element or the name of something that uses _&_.
Do not use the ampersand (&) as a shorthand for _and_ unless you're referring to
a UI element or the name of something that uses _&_.
You can use the symbol `~` in place of the word _approximately_.
@ -91,13 +91,14 @@ and anything that has a name visible to the user, use bold font.
**Example:** On the **Environment Overview** page, click **Configure SSH**.
Don't use code font for UI elements unless it is rendered based on previously entered
text. For example, if you tell the user to provide the environment name as
`myEnvironment`, then use both bold and cold font when referring to the name.
Don't use code font for UI elements unless it is rendered based on previously
entered text. For example, if you tell the user to provide the environment name
as `myEnvironment`, then use both bold and cold font when referring to the name.
**Example**: Click **`myEnvironment`**.
When writing out instructions that involve UI elements, both of the following options are acceptable:
When writing out instructions that involve UI elements, both of the following
options are acceptable:
- Go to **Manage** > **Users**.
- In the **Manage** menu, click **Users**.
@ -111,13 +112,13 @@ Below summarizes the guidelines regarding how Coder terms should be used.
The only Coder-specific terms that should be capitalized are the names of
products (e.g., Coder).
The exception is **code-server**, which is always lowercase. If it appears at the
beginning of the sentence, rewrite the sentence to avoid this usage.
The exception is **code-server**, which is always lowercase. If it appears at
the beginning of the sentence, rewrite the sentence to avoid this usage.
### Uncapitalized terms
In general, we do not capitalize the names of features (unless the situation calls for it,
such as the word appearing at the beginning of a sentence):
In general, we do not capitalize the names of features (unless the situation
calls for it, such as the word appearing at the beginning of a sentence):
- account dormancy
- audit logs

14
docs/contributing/feature-stages.md
View File

@ -4,13 +4,18 @@ Some Coder features are released as Alpha or Experimental.
## Alpha features
Alpha features are enabled in all Coder deployments but the feature is subject to change, or even be removed. Breaking changes may not be documented in the changelog. In most cases, features will only stay in alpha for 1 month.
Alpha features are enabled in all Coder deployments but the feature is subject
to change, or even be removed. Breaking changes may not be documented in the
changelog. In most cases, features will only stay in alpha for 1 month.
We recommend using [GitHub issues](https://github.com/coder/coder/issues) to leave feedback and get support for alpha features.
We recommend using [GitHub issues](https://github.com/coder/coder/issues) to
leave feedback and get support for alpha features.
## Experimental features
These features are disabled by default, and not recommended for use in production as they may cause performance or stability issues. In most cases, features will only stay in experimental for 1-2 weeks of internal testing.
These features are disabled by default, and not recommended for use in
production as they may cause performance or stability issues. In most cases,
features will only stay in experimental for 1-2 weeks of internal testing.
```yaml
# Enable all experimental features
@ -22,4 +27,5 @@ coder server --experiments=feature1,feature2
# Alternatively, use the `CODER_EXPERIMENTS` environment variable.
```
For a list of all experiments, refer to the [codersdk reference](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#Experiment).
For a list of all experiments, refer to the
[codersdk reference](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#Experiment).

156
docs/contributing/frontend.md
View File

@ -1,36 +1,51 @@
# Frontend
This is a guide to help the Coder community and also Coder members contribute to our UI. It is ongoing work but we hope it provides some useful information to get started. If you have any questions or need help, please send us a message on our [Discord server](https://discord.com/invite/coder). We'll be happy to help you.
This is a guide to help the Coder community and also Coder members contribute to
our UI. It is ongoing work but we hope it provides some useful information to
get started. If you have any questions or need help, please send us a message on
our [Discord server](https://discord.com/invite/coder). We'll be happy to help
you.
## Running the UI
You can run the UI and access the dashboard in two ways:
- Build the UI pointing to an external Coder server: `CODER_HOST=https://mycoder.com pnpm dev` inside of the `site` folder. This is helpful when you are building something in the UI and already have the data on your deployed server.
- Build the entire Coder server + UI locally: `./scripts/develop.sh` in the root folder. It is useful when you have to contribute with features that are not deployed yet or when you have to work on both, frontend and backend.
- Build the UI pointing to an external Coder server:
`CODER_HOST=https://mycoder.com pnpm dev` inside of the `site` folder. This is
helpful when you are building something in the UI and already have the data on
your deployed server.
- Build the entire Coder server + UI locally: `./scripts/develop.sh` in the root
folder. It is useful when you have to contribute with features that are not
deployed yet or when you have to work on both, frontend and backend.
In both cases, you can access the dashboard on `http://localhost:8080`. If you are running the `./scripts/develop.sh` you can log in using the default credentials: `admin@coder.com` and `SomeSecurePassword!`.
In both cases, you can access the dashboard on `http://localhost:8080`. If you
are running the `./scripts/develop.sh` you can log in using the default
credentials: `admin@coder.com` and `SomeSecurePassword!`.
## Tech Stack
All our dependencies are described in `site/package.json` but here are the most important ones:
All our dependencies are described in `site/package.json` but here are the most
important ones:
- [React](https://reactjs.org/) as framework
- [Typescript](https://www.typescriptlang.org/) to keep our sanity
- [Vite](https://vitejs.dev/) to build the project
- [Material V5](https://mui.com/material-ui/getting-started/) for UI components
- [react-router](https://reactrouter.com/en/main) for routing
- [TanStack Query v4](https://tanstack.com/query/v4/docs/react/overview) for fetching data
- [TanStack Query v4](https://tanstack.com/query/v4/docs/react/overview) for
fetching data
- [XState](https://xstate.js.org/docs/) for handling complex state flows
- [axios](https://github.com/axios/axios) as fetching lib
- [Playwright](https://playwright.dev/) for E2E testing
- [Jest](https://jestjs.io/) for integration testing
- [Storybook](https://storybook.js.org/) and [Chromatic](https://www.chromatic.com/) for visual testing
- [Storybook](https://storybook.js.org/) and
[Chromatic](https://www.chromatic.com/) for visual testing
- [PNPM](https://pnpm.io/) as package manager
## Structure
All the code related to the UI is inside the `site` folder and we defined a few conventions to help people to navigate through it.
All the code related to the UI is inside the `site` folder and we defined a few
conventions to help people to navigate through it.
- **e2e** - E2E tests
- **src** - Source code
@ -43,38 +58,69 @@ All the code related to the UI is inside the `site` folder and we defined a few
- **pages** - Page components
- **testHelpers** - Helper functions to help with integration tests
- **util** - Helper functions that can be used across the application
- **xServices** - XState machines used to fetch data and handle complex scenarios
- **xServices** - XState machines used to fetch data and handle complex
scenarios
- **static** - UI static assets like images, fonts, icons, etc
## Routing
We use [react-router](https://reactrouter.com/en/main) as our routing engine and adding a new route is very easy. If the new route needs to be authenticated, put it under the `<RequireAuth>` route and if it needs to live inside of the dashboard, put it under the `<DashboardLayout>` route.
We use [react-router](https://reactrouter.com/en/main) as our routing engine and
adding a new route is very easy. If the new route needs to be authenticated, put
it under the `<RequireAuth>` route and if it needs to live inside of the
dashboard, put it under the `<DashboardLayout>` route.
The `RequireAuth` component handles all the authentication logic for the routes and the `DashboardLayout` wraps the route adding a navbar and passing down common dashboard data.
The `RequireAuth` component handles all the authentication logic for the routes
and the `DashboardLayout` wraps the route adding a navbar and passing down
common dashboard data.
## Pages
Pages are the top-level components of the app. The page component lives under the `src/pages` folder and each page should have its own folder so we can better group the views, tests, utility functions and so on. We use a structure where the page component is responsible for fetching all the data and passing it down to the view. We explain this decision a bit better in the next section.
Pages are the top-level components of the app. The page component lives under
the `src/pages` folder and each page should have its own folder so we can better
group the views, tests, utility functions and so on. We use a structure where
the page component is responsible for fetching all the data and passing it down
to the view. We explain this decision a bit better in the next section.
> ℹ️ Code that is only related to the page should live inside of the page folder but if at some point it is used in other pages or components, you should consider moving it to the `src` level in the `utils`, `hooks` or `components` folder.
> ℹ️ Code that is only related to the page should live inside of the page folder
> but if at some point it is used in other pages or components, you should
> consider moving it to the `src` level in the `utils`, `hooks` or `components`
> folder.
### States
A page usually has at least three states: **loading**, **ready** or **success**, and **error** so remember to always handle these scenarios while you are coding a page. We also encourage you to add visual testing for these three states using the `*.stories.ts` file.
A page usually has at least three states: **loading**, **ready** or **success**,
and **error** so remember to always handle these scenarios while you are coding
a page. We also encourage you to add visual testing for these three states using
the `*.stories.ts` file.
## Fetching data
We use [TanStack Query v4](https://tanstack.com/query/v4/docs/react/overview)(previously known as react-query) to fetch data from the API. We also use [XState](https://xstate.js.org/docs/) to handle complex flows with multiple states and transitions.
We use
[TanStack Query v4](https://tanstack.com/query/v4/docs/react/overview)(previously
known as react-query) to fetch data from the API. We also use
[XState](https://xstate.js.org/docs/) to handle complex flows with multiple
states and transitions.
> ℹ️ We recently changed how we are going to fetch data from the server so you will see a lot of fetches being made using XState machines but feel free to refactor it if you are already touching those files.
> ℹ️ We recently changed how we are going to fetch data from the server so you
> will see a lot of fetches being made using XState machines but feel free to
> refactor it if you are already touching those files.
### Where to fetch data
Finding the right place to fetch data in React apps is the one million dollar question but we decided to make it only in the page components and pass the props down to the views. This makes it easier to find where data is being loaded and easy to test using Storybook. So you will see components like `UsersPage` and `UsersPageView`.
Finding the right place to fetch data in React apps is the one million dollar
question but we decided to make it only in the page components and pass the
props down to the views. This makes it easier to find where data is being loaded
and easy to test using Storybook. So you will see components like `UsersPage`
and `UsersPageView`.
### API
We are using [axios](https://github.com/axios/axios) as our fetching library and writing the API functions in the `site/src/api/api.ts` files. We also have auto-generated types from our Go server on `site/src/api/typesGenerated.ts`. Usually, every endpoint has its own ` Request` and `Response` types but sometimes you need to pass extra parameters to make the call like the example below:
We are using [axios](https://github.com/axios/axios) as our fetching library and
writing the API functions in the `site/src/api/api.ts` files. We also have
auto-generated types from our Go server on `site/src/api/typesGenerated.ts`.
Usually, every endpoint has its own ` Request` and `Response` types but
sometimes you need to pass extra parameters to make the call like the example
below:
```ts
export const getAgentListeningPorts = async (
@ -87,7 +133,8 @@ export const getAgentListeningPorts = async (
}
```
Sometimes, a FE operation can have multiple API calls so it is ok to wrap it as a single function.
Sometimes, a FE operation can have multiple API calls so it is ok to wrap it as
a single function.
```ts
export const updateWorkspaceVersion = async (
@ -98,45 +145,73 @@ export const updateWorkspaceVersion = async (
}
```
If you need more granular errors or control, you may should consider keep them separated and use XState for that.
If you need more granular errors or control, you may should consider keep them
separated and use XState for that.
## Components
We are using [Material V4](https://v4.mui.com/) in our UI and we don't have any short-term plans to update or even replace it. It still provides good value for us and changing it would cost too much work which is not valuable right now but of course, it can change in the future.
We are using [Material V4](https://v4.mui.com/) in our UI and we don't have any
short-term plans to update or even replace it. It still provides good value for
us and changing it would cost too much work which is not valuable right now but
of course, it can change in the future.
### Structure
Each component gets its own folder. Make sure you add a test and Storybook stories for the component as well. By keeping these tidy, the codebase will remain easy to navigate, healthy and maintainable for all contributors.
Each component gets its own folder. Make sure you add a test and Storybook
stories for the component as well. By keeping these tidy, the codebase will
remain easy to navigate, healthy and maintainable for all contributors.
### Accessibility
We strive to keep our UI accessible. When using colors, avoid adding new elements with low color contrast. Always use labels on inputs, not just placeholders. These are important for screen-readers.
We strive to keep our UI accessible. When using colors, avoid adding new
elements with low color contrast. Always use labels on inputs, not just
placeholders. These are important for screen-readers.
### Should I create a new component?
As with most things in the world, it depends. If you are creating a new component to encapsulate some UI abstraction like `UsersTable` it is ok but you should always try to use the base components that are provided by the library or from the codebase so I recommend you to always do a quick search before creating a custom primitive component like dialogs, popovers, buttons, etc.
As with most things in the world, it depends. If you are creating a new
component to encapsulate some UI abstraction like `UsersTable` it is ok but you
should always try to use the base components that are provided by the library or
from the codebase so I recommend you to always do a quick search before creating
a custom primitive component like dialogs, popovers, buttons, etc.
## Testing
We use three types of testing in our app: **E2E**, **Integration** and **Visual Testing**.
We use three types of testing in our app: **E2E**, **Integration** and **Visual
Testing**.
### E2E (end-to-end)
Are useful to test complete flows like "Create a user", "Import template", etc. For this one, we use [Playwright](https://playwright.dev/). If you only need to test if the page is being rendered correctly, you should probably consider using the **Visual Testing** approach.
Are useful to test complete flows like "Create a user", "Import template", etc.
For this one, we use [Playwright](https://playwright.dev/). If you only need to
test if the page is being rendered correctly, you should probably consider using
the **Visual Testing** approach.
> ℹ️ For scenarios where you need to be authenticated, you can use `test.use({ storageState: getStatePath("authState") })`.
> ℹ️ For scenarios where you need to be authenticated, you can use
> `test.use({ storageState: getStatePath("authState") })`.
### Integration
Test user interactions like "Click in a button shows a dialog", "Submit the form sends the correct data", etc. For this, we use [Jest](https://jestjs.io/) and [react-testing-library](https://testing-library.com/docs/react-testing-library/intro/). If the test involves routing checks like redirects or maybe checking the info on another page, you should probably consider using the **E2E** approach.
Test user interactions like "Click in a button shows a dialog", "Submit the form
sends the correct data", etc. For this, we use [Jest](https://jestjs.io/) and
[react-testing-library](https://testing-library.com/docs/react-testing-library/intro/).
If the test involves routing checks like redirects or maybe checking the info on
another page, you should probably consider using the **E2E** approach.
### Visual testing
Test components without user interaction like testing if a page view is rendered correctly depending on some parameters, if the button is showing a spinner if the `loading` props are passing, etc. This should always be your first option since it is way easier to maintain. For this, we use [Storybook](https://storybook.js.org/) and [Chromatic](https://www.chromatic.com/).
Test components without user interaction like testing if a page view is rendered
correctly depending on some parameters, if the button is showing a spinner if
the `loading` props are passing, etc. This should always be your first option
since it is way easier to maintain. For this, we use
[Storybook](https://storybook.js.org/) and
[Chromatic](https://www.chromatic.com/).
### What should I test?
Choosing what to test is not always easy since there are a lot of flows and a lot of things can happen but these are a few indicators that can help you with that:
Choosing what to test is not always easy since there are a lot of flows and a
lot of things can happen but these are a few indicators that can help you with
that:
- Things that can block the user
- Reported bugs
@ -144,18 +219,27 @@ Choosing what to test is not always easy since there are a lot of flows and a lo
### Tests getting too slow
A few times you can notice tests can take a very long time to get done. Sometimes it is because the test itself is complex and runs a lot of stuff, and sometimes it is because of how we are querying things. In the next section, we are going to talk more about them.
A few times you can notice tests can take a very long time to get done.
Sometimes it is because the test itself is complex and runs a lot of stuff, and
sometimes it is because of how we are querying things. In the next section, we
are going to talk more about them.
#### Using `ByRole` queries
One thing we figured out that was slowing down our tests was the use of `ByRole` queries because of how it calculates the role attribute for every element on the `screen`. You can read more about it on the links below:
One thing we figured out that was slowing down our tests was the use of `ByRole`
queries because of how it calculates the role attribute for every element on the
`screen`. You can read more about it on the links below:
- https://stackoverflow.com/questions/69711888/react-testing-library-getbyrole-is-performing-extremely-slowly
- https://github.com/testing-library/dom-testing-library/issues/552#issuecomment-625172052
Even with `ByRole` having performance issues we still want to use it but for that, we have to scope the "querying" area by using the `within` command. So instead of using `screen.getByRole("button")` directly we could do `within(form).getByRole("button")`.
Even with `ByRole` having performance issues we still want to use it but for
that, we have to scope the "querying" area by using the `within` command. So
instead of using `screen.getByRole("button")` directly we could do
`within(form).getByRole("button")`.
❌ Not ideal. If the screen has a hundred or thousand elements it can be VERY slow.
❌ Not ideal. If the screen has a hundred or thousand elements it can be VERY
slow.
```tsx
user.click(screen.getByRole("button"))
@ -170,7 +254,9 @@ user.click(within(form).getByRole("button"))
#### `jest.spyOn` with the API is not working
For some unknown reason, we figured out the `jest.spyOn` is not able to mock the API function when they are passed directly into the services XState machine configuration.
For some unknown reason, we figured out the `jest.spyOn` is not able to mock the
API function when they are passed directly into the services XState machine
configuration.
❌ Does not work

17
docs/dotfiles.md
View File

@ -36,13 +36,13 @@ resource "coder_agent" "main" {
## Persistent Home
Sometimes you want to support personalization without
requiring dotfiles.
Sometimes you want to support personalization without requiring dotfiles.
In such cases:
- Mount a persistent volume to the `/home` directory
- Set the `startup_script` to call a `~/personalize` script that the user can edit
- Set the `startup_script` to call a `~/personalize` script that the user can
edit
```hcl
resource "coder_agent" "main" {
@ -63,7 +63,8 @@ sudo apt install -y neovim fish cargo
## Setup script support
User can setup their dotfiles by creating one of the following script files in their dotfiles repo:
User can setup their dotfiles by creating one of the following script files in
their dotfiles repo:
- `install.sh`
- `install`
@ -74,9 +75,13 @@ User can setup their dotfiles by creating one of the following script files in t
- `setup`
- `script/setup`
If any of the above files are found (in the specified order), Coder will try to execute the first match. After the first match is found, other files will be ignored.
If any of the above files are found (in the specified order), Coder will try to
execute the first match. After the first match is found, other files will be
ignored.
The setup script must be executable, otherwise the dotfiles setup will fail. If you encounter this issue, you can fix it by making the script executable using the following commands:
The setup script must be executable, otherwise the dotfiles setup will fail. If
you encounter this issue, you can fix it by making the script executable using
the following commands:
```shell
cd <path_to_dotfiles_repo>

6
docs/enterprise.md
View File

@ -1,8 +1,8 @@
# Enterprise Features
Coder is free to use and includes some features that are only accessible with a paid license.
[Contact Sales](https://coder.com/contact) for pricing or [get a free
trial](https://coder.com/trial).
Coder is free to use and includes some features that are only accessible with a
paid license. [Contact Sales](https://coder.com/contact) for pricing or
[get a free trial](https://coder.com/trial).
| Category | Feature | Open Source | Enterprise |
| --------------- | ------------------------------------------------------------------------------------ | :---------: | :--------: |

28
docs/ides.md
View File

@ -18,25 +18,30 @@ support should work:
## Visual Studio Code
Click `VS Code Desktop` in the dashboard to one-click enter a workspace. This automatically installs the [Coder Remote](https://github.com/coder/vscode-coder) extension, authenticates with Coder, and connects to the workspace.
Click `VS Code Desktop` in the dashboard to one-click enter a workspace. This
automatically installs the [Coder Remote](https://github.com/coder/vscode-coder)
extension, authenticates with Coder, and connects to the workspace.
![Demo](https://github.com/coder/vscode-coder/raw/main/demo.gif?raw=true)
You can set the default directory in which VS Code opens via the `dir` argument on
the `coder_agent` resource in your workspace template. See the [Terraform documentation
for more details](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#dir).
You can set the default directory in which VS Code opens via the `dir` argument
on the `coder_agent` resource in your workspace template. See the
[Terraform documentation for more details](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#dir).
> The `VS Code Desktop` button can be hidden by enabling [Browser-only connections](./networking/index.md#Browser-only).
> The `VS Code Desktop` button can be hidden by enabling
> [Browser-only connections](./networking/index.md#Browser-only).
### Manual Installation
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press
enter.
```text
ext install coder.coder-remote
```
Alternatively, manually install the VSIX from the [latest release](https://github.com/coder/vscode-coder/releases/latest).
Alternatively, manually install the VSIX from the
[latest release](https://github.com/coder/vscode-coder/releases/latest).
## SSH configuration
@ -45,7 +50,7 @@ Alternatively, manually install the VSIX from the [latest release](https://githu
To access Coder via SSH, run the following in the terminal:
```console
```shell
coder config-ssh
```
@ -74,8 +79,8 @@ Setting up Gateway also involves picking a project directory, so if you have not
already done so, you may wish to open a terminal on your Coder workspace and
check out a copy of the project you intend to work on.
After installing Gateway on your local system, [follow these steps to create a
Connection and connect to your Coder workspace.](./ides/gateway.md)
After installing Gateway on your local system,
[follow these steps to create a Connection and connect to your Coder workspace.](./ides/gateway.md)
| Version | Status | Notes |
| --------- | ------- | -------------------------------------------------------- |
@ -85,7 +90,8 @@ Connection and connect to your Coder workspace.](./ides/gateway.md)
## Web IDEs (Jupyter, code-server, JetBrains Projector)
Web IDEs (code-server, JetBrains Projector, VNC, etc.) are defined in the template. See [IDEs](./ides/web-ides.md).
Web IDEs (code-server, JetBrains Projector, VNC, etc.) are defined in the
template. See [IDEs](./ides/web-ides.md).
## Up next

82
docs/ides/emacs-tramp.md
View File

@ -1,6 +1,7 @@
# Emacs TRAMP
[Emacs TRAMP](https://www.emacswiki.org/emacs/TrampMode) is a method of running editing operations on a remote server.
[Emacs TRAMP](https://www.emacswiki.org/emacs/TrampMode) is a method of running
editing operations on a remote server.
## Connecting To A Workspace
@ -10,13 +11,17 @@ To connect to your workspace first run:
coder config-ssh
```
Then you can connect to your workspace by its name in the format: `coder.<WORKSPACE NAME>`.
Then you can connect to your workspace by its name in the format:
`coder.<WORKSPACE NAME>`.
In Emacs type `C-x d` and then input: `/-:coder.<WORKSPACE NAME>:` and hit enter. This will open up Dired on the workspace's home directory.
In Emacs type `C-x d` and then input: `/-:coder.<WORKSPACE NAME>:` and hit
enter. This will open up Dired on the workspace's home directory.
### Using SSH
By default Emacs TRAMP is setup to use SCP to access files on the Coder workspace instance. However you might want to use SSH if you have a jumpbox or some other complex network setup.
By default Emacs TRAMP is setup to use SCP to access files on the Coder
workspace instance. However you might want to use SSH if you have a jumpbox or
some other complex network setup.
To do so set the following in your Emacs `init.el` file:
@ -24,13 +29,17 @@ To do so set the following in your Emacs `init.el` file:
(setq tramp-default-method "ssh")
```
Then when you access the workspace instance via `/-:coder.<WORKSPACE NAME>` Emacs will use SSH. Setting `tramp-default-method` will also tell `ansi-term` mode the correct way to access the remote when directory tracking.
Then when you access the workspace instance via `/-:coder.<WORKSPACE NAME>`
Emacs will use SSH. Setting `tramp-default-method` will also tell `ansi-term`
mode the correct way to access the remote when directory tracking.
## Directory Tracking
### ansi-term
If you run your terminal in Emacs via `ansi-term` then you might run into a problem where while SSH-ed into a workspace Emacs will not change its `default-directory` to open files in the directory your shell is in.
If you run your terminal in Emacs via `ansi-term` then you might run into a
problem where while SSH-ed into a workspace Emacs will not change its
`default-directory` to open files in the directory your shell is in.
To fix this:
@ -49,7 +58,8 @@ To fix this:
}
```
2. Next in the shell profile file on the workspace (ex., `~/.bashrc` for Bash and `~/.zshrc` for Zsh) add the following:
2. Next in the shell profile file on the workspace (ex., `~/.bashrc` for Bash
and `~/.zshrc` for Zsh) add the following:
```bash
ansi_term_announce_host() {
@ -77,17 +87,24 @@ To fix this:
ansi_term_announce
```
Ansi Term expects the terminal running inside of it to send escape codes to inform Emacs of the hostname, user, and working directory. The above code sends these escape codes and associated data whenever the terminal logs in and whenever the directory changes.
Ansi Term expects the terminal running inside of it to send escape codes to
inform Emacs of the hostname, user, and working directory. The above code
sends these escape codes and associated data whenever the terminal logs in
and whenever the directory changes.
### eshell
The `eshell` mode will perform directory tracking by default, no additional configuration is needed.
The `eshell` mode will perform directory tracking by default, no additional
configuration is needed.
## Language Servers (Code Completion)
If you use [`lsp-mode`](https://emacs-lsp.github.io/lsp-mode) for code intelligence and completion some additional configuration is required.
If you use [`lsp-mode`](https://emacs-lsp.github.io/lsp-mode) for code
intelligence and completion some additional configuration is required.
In your Emacs `init.el` file you must register a LSP client and tell `lsp-mode` how to find it on the remote machine using the `lsp-register-client` function. For each LSP server you want to use in your workspace add the following:
In your Emacs `init.el` file you must register a LSP client and tell `lsp-mode`
how to find it on the remote machine using the `lsp-register-client` function.
For each LSP server you want to use in your workspace add the following:
```lisp
(lsp-register-client (make-lsp-client :new-connection (lsp-tramp-connection "<LSP SERVER BINARY>")
@ -96,13 +113,27 @@ In your Emacs `init.el` file you must register a LSP client and tell `lsp-mode`
:server-id '<LANGUAGE SERVER ID>))
```
This tells `lsp-mode` to look for a language server binary named `<LSP SERVER BINARY>` for use in `<LANGUAGE MODE>` on a machine named `coder.<WORKSPACE NAME>`. Be sure to replace the values between angle brackets:
This tells `lsp-mode` to look for a language server binary named
`<LSP SERVER BINARY>` for use in `<LANGUAGE MODE>` on a machine named
`coder.<WORKSPACE NAME>`. Be sure to replace the values between angle brackets:
- `<LSP SERVER BINARY>` : The name of the language server binary, without any path components. For example to use the Deno Javascript language server use the value `deno`.
- `<LANGUAGE MODE>`: The name of the Emacs major mode for which the language server should be used. For example to enable the language server for Javascript development use the value `web-mode`.
- `<LANGUAGE SERVER ID>`: This is just the name that `lsp-mode` will use to refer to this language server. If you are ever looking for output buffers or files they may have this name in them.
- `<LSP SERVER BINARY>` : The name of the language server binary, without any
path components. For example to use the Deno Javascript language server use
the value `deno`.
- `<LANGUAGE MODE>`: The name of the Emacs major mode for which the language
server should be used. For example to enable the language server for
Javascript development use the value `web-mode`.
- `<LANGUAGE SERVER ID>`: This is just the name that `lsp-mode` will use to
refer to this language server. If you are ever looking for output buffers or
files they may have this name in them.
Calling the `lsp-register-client` function will tell `lsp-mode` the name of the LSP server binary. However this binary must be accessible via the path. If the language server binary is not in the path you must modify `tramp-remote-path` so that `lsp-mode` knows in what directories to look for the LSP server. To do this use TRAMP's connection profiles functionality. These connection profiles let you customize variables depending on what machine you are connected to. Add the following to your `init.el`:
Calling the `lsp-register-client` function will tell `lsp-mode` the name of the
LSP server binary. However this binary must be accessible via the path. If the
language server binary is not in the path you must modify `tramp-remote-path` so
that `lsp-mode` knows in what directories to look for the LSP server. To do this
use TRAMP's connection profiles functionality. These connection profiles let you
customize variables depending on what machine you are connected to. Add the
following to your `init.el`:
```lisp
(connection-local-set-profile-variables 'remote-path-lsp-servers
@ -110,9 +141,20 @@ Calling the `lsp-register-client` function will tell `lsp-mode` the name of the
(connection-local-set-profiles '(:machine "coder.<WORKSPACE NAME>") 'remote-path-lsp-servers)
```
The `connection-local-set-profile-variables` function creates a new connection profile by the name `remote-path-lsp-servers`. The `connection-local-set-profiles` then indicates this `remote-path-lsp-servers` connection profile should be used when connecting to a server named `coder.<WORKSPACE NAME>`. Be sure to replace `<PATH TO ADD>` with the directory in which a LSP server is present.
The `connection-local-set-profile-variables` function creates a new connection
profile by the name `remote-path-lsp-servers`. The
`connection-local-set-profiles` then indicates this `remote-path-lsp-servers`
connection profile should be used when connecting to a server named
`coder.<WORKSPACE NAME>`. Be sure to replace `<PATH TO ADD>` with the directory
in which a LSP server is present.
TRAMP and `lsp-mode` are fickle friends, sometimes there is weird behavior. If you find that language servers are hanging in the `starting` state then [it might be helpful](https://github.com/emacs-lsp/lsp-mode/issues/2709#issuecomment-800868919) to set the `lsp-log-io` variable to `t`.
TRAMP and `lsp-mode` are fickle friends, sometimes there is weird behavior. If
you find that language servers are hanging in the `starting` state then
[it might be helpful](https://github.com/emacs-lsp/lsp-mode/issues/2709#issuecomment-800868919)
to set the `lsp-log-io` variable to `t`.
More details on configuring `lsp-mode` for TRAMP can be found [in the `lsp-mode` documentation](https://emacs-lsp.github.io/lsp-mode/page/remote/).
The [TRAMP `tramp-remote-path` documentation](https://www.gnu.org/software/emacs/manual/html_node/tramp/Remote-programs.html#Remote-programs) contains more examples and details of connection profiles.
More details on configuring `lsp-mode` for TRAMP can be found
[in the `lsp-mode` documentation](https://emacs-lsp.github.io/lsp-mode/page/remote/).
The
[TRAMP `tramp-remote-path` documentation](https://www.gnu.org/software/emacs/manual/html_node/tramp/Remote-programs.html#Remote-programs)
contains more examples and details of connection profiles.

33
docs/ides/gateway.md
View File

@ -1,17 +1,17 @@
# JetBrains Gateway
JetBrains Gateway is a compact desktop app that allows you to work remotely with
a JetBrains IDE without even downloading one. [See JetBrains' website to learn
about and Gateway.](https://www.jetbrains.com/remote-development/gateway/)
a JetBrains IDE without even downloading one.
[See JetBrains' website to learn about and Gateway.](https://www.jetbrains.com/remote-development/gateway/)
Gateway can connect to a Coder workspace by using Coder's Gateway plugin or
manually setting up an SSH connection.
## Using Coder's JetBrains Gateway Plugin
> If you experience problems, please [create a GitHub
> issue](https://github.com/coder/coder/issues) or share in [our Discord
> channel](https://discord.gg/coder).
> If you experience problems, please
> [create a GitHub issue](https://github.com/coder/coder/issues) or share in
> [our Discord channel](https://discord.gg/coder).
1. [Install Gateway](https://www.jetbrains.com/help/idea/jetbrains-gateway.html)
1. Open Gateway and click the Coder icon to install the Coder plugin.
@ -22,7 +22,8 @@ manually setting up an SSH connection.
![Gateway Connect to Coder](../images/gateway/plugin-connect-to-coder.png)
1. Enter your Coder deployment's Access Url and click "Connect" then paste the Session Token and click "OK"
1. Enter your Coder deployment's Access Url and click "Connect" then paste the
Session Token and click "OK"
![Gateway Session Token](../images/gateway/plugin-session-token.png)
@ -37,7 +38,8 @@ manually setting up an SSH connection.
![Gateway IDE List](../images/gateway/plugin-select-ide.png)
1. Select the JetBrains IDE for your project and the project directory then
click "Start IDE and connect" ![Gateway Select IDE](../images/gateway/plugin-ide-list.png)
click "Start IDE and connect"
![Gateway Select IDE](../images/gateway/plugin-ide-list.png)
![Gateway IDE Opened](../images/gateway/gateway-intellij-opened.png)
@ -99,7 +101,7 @@ Windows example:
macOS example:
```sh
```shell
keytool -import -alias coder -file cacert.pem -keystore /Applications/JetBrains\ Gateway.app/Contents/jbr/Contents/Home/lib/security/cacerts
```
@ -150,12 +152,13 @@ keytool -import -alias coder -file cacert.pem -keystore /Applications/JetBrains\
![Gateway Continue](../images/gateway/gateway-continue.png)
1. Select the JetBrains IDE for your project and the project directory. SSH into your server to create a directory or check out code if you haven't already.
1. Select the JetBrains IDE for your project and the project directory. SSH into
your server to create a directory or check out code if you haven't already.
![Gateway Choose IDE](../images/gateway/gateway-choose-ide.png)
> Note the JetBrains IDE is remotely installed into `~/.
cache/JetBrains/RemoteDev/dist`
> Note the JetBrains IDE is remotely installed into
> `~/. cache/JetBrains/RemoteDev/dist`
1. Click "Download and Start IDE" to connect.
@ -168,7 +171,7 @@ are air-gapped, and cannot reach jetbrains.com), run the following script in the
JetBrains IDE directory to point the default Gateway directory to the IDE
directory. This step must be done before configuring Gateway.
```sh
```shell
cd /opt/idea/bin
./remote-dev-server.sh registerBackendLocationForGateway
```
@ -176,12 +179,12 @@ cd /opt/idea/bin
> Gateway only works with paid versions of JetBrains IDEs so the script will not
> be located in the `bin` directory of JetBrains Community editions.
[Here is the JetBrains
article](https://www.jetbrains.com/help/idea/remote-development-troubleshooting.html#setup:~:text=Can%20I%20point%20Remote%20Development%20to%20an%20existing%20IDE%20on%20my%20remote%20server%3F%20Is%20it%20possible%20to%20install%20IDE%20manually%3F)
[Here is the JetBrains article](https://www.jetbrains.com/help/idea/remote-development-troubleshooting.html#setup:~:text=Can%20I%20point%20Remote%20Development%20to%20an%20existing%20IDE%20on%20my%20remote%20server%3F%20Is%20it%20possible%20to%20install%20IDE%20manually%3F)
explaining this IDE specification.
## JetBrains Gateway in an offline environment
In networks that restrict access to the internet, you will need to leverage the
JetBrains Client Installer to download and save the IDE clients locally. Please
see the [JetBrains documentation for more information](https://www.jetbrains.com/help/idea/fully-offline-mode.html).
see the
[JetBrains documentation for more information](https://www.jetbrains.com/help/idea/fully-offline-mode.html).

20
docs/ides/remote-desktops.md
View File

@ -1,6 +1,7 @@
# Remote Desktops
> Built-in remote desktop is on the roadmap ([#2106](https://github.com/coder/coder/issues/2106)).
> Built-in remote desktop is on the roadmap
> ([#2106](https://github.com/coder/coder/issues/2106)).
## VNC Desktop
@ -13,10 +14,13 @@ Workspace requirements:
- VNC server (e.g. [tigervnc](https://tigervnc.org/))
- VNC client (e.g. [novnc](https://novnc.com/info.html))
Installation instructions vary depending on your workspace's operating
system, platform, and build system.
Installation instructions vary depending on your workspace's operating system,
platform, and build system.
As a starting point, see the [desktop-container](https://github.com/bpmct/coder-templates/tree/main/desktop-container) community template. It builds and provisions a Dockerized workspace with the following software:
As a starting point, see the
[desktop-container](https://github.com/bpmct/coder-templates/tree/main/desktop-container)
community template. It builds and provisions a Dockerized workspace with the
following software:
- Ubuntu 20.04
- TigerVNC server
@ -25,9 +29,13 @@ As a starting point, see the [desktop-container](https://github.com/bpmct/coder-
## RDP Desktop
To use RDP with Coder, you'll need to install an [RDP client](https://docs.microsoft.com/en-us/windows-server/remote/remote-desktop-services/clients/remote-desktop-clients) on your local machine, and enable RDP on your workspace.
To use RDP with Coder, you'll need to install an
[RDP client](https://docs.microsoft.com/en-us/windows-server/remote/remote-desktop-services/clients/remote-desktop-clients)
on your local machine, and enable RDP on your workspace.
As a starting point, see the [gcp-windows-rdp](https://github.com/matifali/coder-templates/tree/main/gcp-windows-rdp) community template. It builds and provisions a Windows Server workspace on GCP.
As a starting point, see the
[gcp-windows-rdp](https://github.com/matifali/coder-templates/tree/main/gcp-windows-rdp)
community template. It builds and provisions a Windows Server workspace on GCP.
Use the following command to forward the RDP port to your local machine:

15
docs/ides/web-ides.md
View File

@ -11,8 +11,8 @@ It's common to also let developers to connect via web IDEs.
In Coder, web IDEs are defined as
[coder_app](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app)
resources in the template. With our generic model, any web application can
be used as a Coder application. For example:
resources in the template. With our generic model, any web application can be
used as a Coder application. For example:
```hcl
# Add button to open Portainer in the workspace dashboard
@ -36,7 +36,9 @@ resource "coder_app" "portainer" {
![code-server in a workspace](../images/code-server-ide.png)
[code-server](https://github.com/coder/coder) is our supported method of running VS Code in the web browser. A simple way to install code-server in Linux/macOS workspaces is via the Coder agent in your template:
[code-server](https://github.com/coder/coder) is our supported method of running
VS Code in the web browser. A simple way to install code-server in Linux/macOS
workspaces is via the Coder agent in your template:
```console
# edit your template
@ -62,7 +64,9 @@ resource "coder_agent" "main" {
}
```
For advanced use, we recommend installing code-server in your VM snapshot or container image. Here's a Dockerfile which leverages some special [code-server features](https://coder.com/docs/code-server/):
For advanced use, we recommend installing code-server in your VM snapshot or
container image. Here's a Dockerfile which leverages some special
[code-server features](https://coder.com/docs/code-server/):
```Dockerfile
FROM codercom/enterprise-base:ubuntu
@ -79,7 +83,8 @@ RUN code-server --install-extension eamodio.gitlens
# or use a process manager like supervisord
```
You'll also need to specify a `coder_app` resource related to the agent. This is how code-server is displayed on the workspace page.
You'll also need to specify a `coder_app` resource related to the agent. This is
how code-server is displayed on the workspace page.
```hcl
resource "coder_app" "code-server" {

21
docs/install/binary.md
View File

@ -1,15 +1,22 @@
Coder publishes self-contained .zip and .tar.gz archives in [GitHub releases](https://github.com/coder/coder/releases/latest). The archives bundle `coder` binary.
Coder publishes self-contained .zip and .tar.gz archives in
[GitHub releases](https://github.com/coder/coder/releases/latest). The archives
bundle `coder` binary.
1. Download the [release archive](https://github.com/coder/coder/releases/latest) appropriate for your operating system
1. Download the
[release archive](https://github.com/coder/coder/releases/latest) appropriate
for your operating system
1. Unzip the folder you just downloaded, and move the `coder` executable to a location that's on your `PATH`
1. Unzip the folder you just downloaded, and move the `coder` executable to a
location that's on your `PATH`
```console
# ex. macOS and Linux
mv coder /usr/local/bin
```
> Windows users: see [this guide](https://answers.microsoft.com/en-us/windows/forum/all/adding-path-variable/97300613-20cb-4d85-8d0e-cc9d3549ba23) for adding folders to `PATH`.
> Windows users: see
> [this guide](https://answers.microsoft.com/en-us/windows/forum/all/adding-path-variable/97300613-20cb-4d85-8d0e-cc9d3549ba23)
> for adding folders to `PATH`.
1. Start a Coder server
@ -21,9 +28,9 @@ Coder publishes self-contained .zip and .tar.gz archives in [GitHub releases](ht
coder server --postgres-url <url> --access-url <url>
```
> Set `CODER_ACCESS_URL` to the external URL that users and workspaces will use to
> connect to Coder. This is not required if you are using the tunnel. Learn more
> about Coder's [configuration options](../admin/configure.md).
> Set `CODER_ACCESS_URL` to the external URL that users and workspaces will
> use to connect to Coder. This is not required if you are using the tunnel.
> Learn more about Coder's [configuration options](../admin/configure.md).
1. Visit the Coder URL in the logs to set up your first account, or use the CLI.

30
docs/install/database.md
View File

@ -1,11 +1,12 @@
## Recommendation
For production deployments, we recommend using an external [PostgreSQL](https://www.postgresql.org/) database (version 13 or higher).
For production deployments, we recommend using an external
[PostgreSQL](https://www.postgresql.org/) database (version 13 or higher).
## Basic configuration
Before starting the Coder server, prepare the database server by creating a role and a database.
Remember that the role must have access to the created database.
Before starting the Coder server, prepare the database server by creating a role
and a database. Remember that the role must have access to the created database.
With `psql`:
@ -19,8 +20,9 @@ With `psql -U coder`:
CREATE DATABASE coder;
```
Coder configuration is defined via [environment variables](../admin/configure.md).
The database client requires the connection string provided via the `CODER_PG_CONNECTION_URL` variable.
Coder configuration is defined via
[environment variables](../admin/configure.md). The database client requires the
connection string provided via the `CODER_PG_CONNECTION_URL` variable.
```console
export CODER_PG_CONNECTION_URL="postgres://coder:secret42@localhost/coder?sslmode=disable"
@ -28,7 +30,9 @@ export CODER_PG_CONNECTION_URL="postgres://coder:secret42@localhost/coder?sslmod
## Custom schema
For installations with elevated security requirements, it's advised to use a separate [schema](https://www.postgresql.org/docs/current/ddl-schemas.html) instead of the public one.
For installations with elevated security requirements, it's advised to use a
separate [schema](https://www.postgresql.org/docs/current/ddl-schemas.html)
instead of the public one.
With `psql -U coder`:
@ -53,8 +57,10 @@ In this case the database client requires the modified connection string:
export CODER_PG_CONNECTION_URL="postgres://coder:secret42@localhost/coder?sslmode=disable&search_path=myschema"
```
The `search_path` parameter determines the order of schemas in which they are visited while looking for a specific table.
The first schema named in the search path is called the current schema. By default `search_path` defines the following schemas:
The `search_path` parameter determines the order of schemas in which they are
visited while looking for a specific table. The first schema named in the search
path is called the current schema. By default `search_path` defines the
following schemas:
```sql
SHOW search_path;
@ -64,7 +70,8 @@ search_path
"$user", public
```
Using the `search_path` in the connection string corresponds to the following `psql` command:
Using the `search_path` in the connection string corresponds to the following
`psql` command:
```sql
ALTER ROLE coder SET search_path = myschema;
@ -74,8 +81,9 @@ ALTER ROLE coder SET search_path = myschema;
### Coder server fails startup with "current_schema: converting NULL to string is unsupported"
Please make sure that the schema selected in the connection string `...&search_path=myschema` exists
and the role has granted permissions to access it. The schema should be present on this listing:
Please make sure that the schema selected in the connection string
`...&search_path=myschema` exists and the role has granted permissions to access
it. The schema should be present on this listing:
```console
psql -U coder -c '\dn'

48
docs/install/docker.md
View File

@ -1,15 +1,18 @@
You can install and run Coder using the official Docker images published on [GitHub Container Registry](https://github.com/coder/coder/pkgs/container/coder).
You can install and run Coder using the official Docker images published on
[GitHub Container Registry](https://github.com/coder/coder/pkgs/container/coder).
## Requirements
Docker is required. See the [official installation documentation](https://docs.docker.com/install/).
Docker is required. See the
[official installation documentation](https://docs.docker.com/install/).
> Note that the below steps are only supported on a Linux distribution. If on macOS, please [run Coder via the standalone binary](./binary.md).
> Note that the below steps are only supported on a Linux distribution. If on
> macOS, please [run Coder via the standalone binary](./binary.md).
## Run Coder with the built-in database (quick)
For proof-of-concept deployments, you can run a complete Coder instance with
the following command.
For proof-of-concept deployments, you can run a complete Coder instance with the
following command.
```console
export CODER_DATA=$HOME/.config/coderv2-docker
@ -27,8 +30,8 @@ ensure Coder has permissions to manage Docker via `docker.sock`. If the host
systems `/var/run/docker.sock` is not group writeable or does not belong to the
`docker` group, the above may not work as-is.</sup>
Coder configuration is defined via environment variables.
Learn more about Coder's [configuration options](../admin/configure.md).
Coder configuration is defined via environment variables. Learn more about
Coder's [configuration options](../admin/configure.md).
## Run Coder with access URL and external PostgreSQL (recommended)
@ -44,13 +47,14 @@ docker run --rm -it \
ghcr.io/coder/coder:latest
```
Coder configuration is defined via environment variables.
Learn more about Coder's [configuration options](../admin/configure.md).
Coder configuration is defined via environment variables. Learn more about
Coder's [configuration options](../admin/configure.md).
## Run Coder with docker-compose
Coder's publishes a [docker-compose example](https://github.com/coder/coder/blob/main/docker-compose.yaml) which includes
an PostgreSQL container and volume.
Coder's publishes a
[docker-compose example](https://github.com/coder/coder/blob/main/docker-compose.yaml)
which includes an PostgreSQL container and volume.
1. Install [Docker Compose](https://docs.docker.com/compose/install/)
@ -62,9 +66,11 @@ an PostgreSQL container and volume.
3. Start Coder with `docker-compose up`:
In order to use cloud-based templates (e.g. Kubernetes, AWS), you must have an external URL that users and workspaces will use to connect to Coder.
In order to use cloud-based templates (e.g. Kubernetes, AWS), you must have
an external URL that users and workspaces will use to connect to Coder.
For proof-of-concept deployments, you can use [Coder's tunnel](../admin/configure.md#tunnel):
For proof-of-concept deployments, you can use
[Coder's tunnel](../admin/configure.md#tunnel):
```console
cd coder
@ -72,7 +78,8 @@ an PostgreSQL container and volume.
docker-compose up
```
For production deployments, we recommend setting an [access URL](../admin/configure.md#access-url):
For production deployments, we recommend setting an
[access URL](../admin/configure.md#access-url):
```console
cd coder
@ -80,19 +87,24 @@ an PostgreSQL container and volume.
CODER_ACCESS_URL=https://coder.example.com docker-compose up
```
4. Visit the web ui via the configured url. You can add `/login` to the base url to create the first user via the ui.
4. Visit the web ui via the configured url. You can add `/login` to the base url
to create the first user via the ui.
5. Follow the on-screen instructions log in and create your first template and workspace
5. Follow the on-screen instructions log in and create your first template and
workspace
## Troubleshooting
### Docker-based workspace is stuck in "Connecting..."
Ensure you have an externally-reachable `CODER_ACCESS_URL` set. See [troubleshooting templates](../templates/index.md#troubleshooting-templates) for more steps.
Ensure you have an externally-reachable `CODER_ACCESS_URL` set. See
[troubleshooting templates](../templates/index.md#troubleshooting-templates) for
more steps.
### Permission denied while trying to connect to the Docker daemon socket
See Docker's official documentation to [Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)
See Docker's official documentation to
[Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)
## Next steps

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

@ -1,4 +1,6 @@
The easiest way to install Coder is to use our [install script](https://github.com/coder/coder/blob/main/install.sh) for Linux and macOS.
The easiest way to install Coder is to use our
[install script](https://github.com/coder/coder/blob/main/install.sh) for Linux
and macOS.
To install, run:
@ -12,15 +14,18 @@ You can preview what occurs during the install process:
curl -fsSL https://coder.com/install.sh | sh -s -- --dry-run
```
You can modify the installation process by including flags. Run the help command for reference:
You can modify the installation process by including flags. Run the help command
for reference:
```bash
curl -fsSL https://coder.com/install.sh | sh -s -- --help
```
After installing, use the in-terminal instructions to start the Coder server manually via `coder server` or as a system package.
After installing, use the in-terminal instructions to start the Coder server
manually via `coder server` or as a system package.
By default, the Coder server runs on `http://127.0.0.1:3000` and uses a [public tunnel](../admin/configure.md#tunnel) for workspace connections.
By default, the Coder server runs on `http://127.0.0.1:3000` and uses a
[public tunnel](../admin/configure.md#tunnel) for workspace connections.
## Next steps

81
docs/install/kubernetes.md
View File

@ -1,9 +1,11 @@
## Requirements
Before proceeding, please ensure that you have a Kubernetes cluster running K8s 1.19+ and have Helm 3.5+ installed.
Before proceeding, please ensure that you have a Kubernetes cluster running K8s
1.19+ and have Helm 3.5+ installed.
You'll also want to install the [latest version of Coder](https://github.com/coder/coder/releases/latest) locally in order
to log in and manage templates.
You'll also want to install the
[latest version of Coder](https://github.com/coder/coder/releases/latest)
locally in order to log in and manage templates.
## Install Coder with Helm
@ -21,12 +23,13 @@ to log in and manage templates.
[AWS](https://aws.amazon.com/rds/postgresql/),
[Azure](https://docs.microsoft.com/en-us/azure/postgresql/), or
[DigitalOcean](https://www.digitalocean.com/products/managed-databases-postgresql),
you can use the managed PostgreSQL offerings they provide. Make sure that
the PostgreSQL service is running and accessible from your cluster. It
should be in the same network, same project, etc.
you can use the managed PostgreSQL offerings they provide. Make sure that the
PostgreSQL service is running and accessible from your cluster. It should be
in the same network, same project, etc.
You can install Postgres manually on your cluster using the
[Bitnami PostgreSQL Helm chart](https://github.com/bitnami/charts/tree/master/bitnami/postgresql#readme). There are some
[Bitnami PostgreSQL Helm chart](https://github.com/bitnami/charts/tree/master/bitnami/postgresql#readme).
There are some
[helpful guides](https://phoenixnap.com/kb/postgresql-kubernetes) on the
internet that explain sensible configurations for this chart. Example:
@ -49,9 +52,8 @@ to log in and manage templates.
> Ensure you set up periodic backups so you don't lose data.
You can use
[Postgres operator](https://github.com/zalando/postgres-operator) to
manage PostgreSQL deployments on your Kubernetes cluster.
You can use [Postgres operator](https://github.com/zalando/postgres-operator)
to manage PostgreSQL deployments on your Kubernetes cluster.
1. Create a secret with the database URL:
@ -116,22 +118,22 @@ to log in and manage templates.
--values values.yaml
```
You can watch Coder start up by running `kubectl get pods -n coder`. Once Coder has
started, the `coder-*` pods should enter the `Running` state.
You can watch Coder start up by running `kubectl get pods -n coder`. Once
Coder has started, the `coder-*` pods should enter the `Running` state.
1. Log in to Coder
Use `kubectl get svc -n coder` to get the IP address of the
LoadBalancer. Visit this in the browser to set up your first account.
Use `kubectl get svc -n coder` to get the IP address of the LoadBalancer.
Visit this in the browser to set up your first account.
If you do not have a domain, you should set `CODER_ACCESS_URL`
to this URL in the Helm chart and upgrade Coder (see below).
This allows workspaces to connect to the proper Coder URL.
If you do not have a domain, you should set `CODER_ACCESS_URL` to this URL in
the Helm chart and upgrade Coder (see below). This allows workspaces to
connect to the proper Coder URL.
## Upgrading Coder via Helm
To upgrade Coder in the future or change values,
you can run the following command:
To upgrade Coder in the future or change values, you can run the following
command:
```console
helm repo update
@ -144,7 +146,9 @@ helm upgrade coder coder-v2/coder \
### AWS
If you are deploying Coder on AWS EKS and service is set to `LoadBalancer`, AWS will default to the Classic load balancer. The load balancer external IP will be stuck in a pending status unless sessionAffinity is set to None.
If you are deploying Coder on AWS EKS and service is set to `LoadBalancer`, AWS
will default to the Classic load balancer. The load balancer external IP will be
stuck in a pending status unless sessionAffinity is set to None.
```yaml
coder:
@ -153,7 +157,8 @@ coder:
sessionAffinity: None
```
AWS recommends a Network load balancer in lieu of the Classic load balancer. Use the following `values.yaml` settings to request a Network load balancer:
AWS recommends a Network load balancer in lieu of the Classic load balancer. Use
the following `values.yaml` settings to request a Network load balancer:
```yaml
coder:
@ -164,9 +169,9 @@ coder:
```
By default, Coder will set the `externalTrafficPolicy` to `Cluster` which will
mask client IP addresses in the Audit log. To preserve the source IP, you can either
set this value to `Local`, or pass through the client IP via the X-Forwarded-For
header. To configure the latter, set the following environment
mask client IP addresses in the Audit log. To preserve the source IP, you can
either set this value to `Local`, or pass through the client IP via the
X-Forwarded-For header. To configure the latter, set the following environment
variables:
```yaml
@ -180,17 +185,21 @@ coder:
### Azure
In certain enterprise environments, the [Azure Application Gateway](https://learn.microsoft.com/en-us/azure/application-gateway/ingress-controller-overview) was needed. The Application Gateway supports:
In certain enterprise environments, the
[Azure Application Gateway](https://learn.microsoft.com/en-us/azure/application-gateway/ingress-controller-overview)
was needed. The Application Gateway supports:
- Websocket traffic (required for workspace connections)
- TLS termination
## PostgreSQL Certificates
Your organization may require connecting to the database instance over SSL. To supply
Coder with the appropriate certificates, and have it connect over SSL, follow the steps below:
Your organization may require connecting to the database instance over SSL. To
supply Coder with the appropriate certificates, and have it connect over SSL,
follow the steps below:
1. Create the certificate as a secret in your Kubernetes cluster, if not already present:
1. Create the certificate as a secret in your Kubernetes cluster, if not already
present:
```console
$ kubectl create secret tls postgres-certs -n coder --key="postgres.key" --cert="postgres.crt"
@ -216,20 +225,24 @@ coder:
postgres://<user>:<password>@databasehost:<port>/<db-name>?sslmode=require&sslcert=$HOME/.postgresql/postgres.crt&sslkey=$HOME/.postgresql/postgres.key"
```
> More information on connecting to PostgreSQL databases using certificates can be found [here](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-CLIENTCERT).
> More information on connecting to PostgreSQL databases using certificates can
> be found
> [here](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-CLIENTCERT).
## Troubleshooting
You can view Coder's logs by getting the pod name from `kubectl get pods` and then running `kubectl logs <pod name>`. You can also
view these logs in your
You can view Coder's logs by getting the pod name from `kubectl get pods` and
then running `kubectl logs <pod name>`. You can also view these logs in your
Cloud's log management system if you are using managed Kubernetes.
### Kubernetes-based workspace is stuck in "Connecting..."
Ensure you have an externally-reachable `CODER_ACCESS_URL` set in your helm chart. If you do not have a domain set up,
this should be the IP address of Coder's LoadBalancer (`kubectl get svc -n coder`).
Ensure you have an externally-reachable `CODER_ACCESS_URL` set in your helm
chart. If you do not have a domain set up, this should be the IP address of
Coder's LoadBalancer (`kubectl get svc -n coder`).
See [troubleshooting templates](../templates/index.md#troubleshooting-templates) for more steps.
See [troubleshooting templates](../templates/index.md#troubleshooting-templates)
for more steps.
## Next steps

64
docs/install/offline.md
View File

@ -1,8 +1,10 @@
# Offline Deployments
All Coder features are supported in offline / behind firewalls / in air-gapped environments. However, some changes to your configuration are necessary.
All Coder features are supported in offline / behind firewalls / in air-gapped
environments. However, some changes to your configuration are necessary.
> This is a general comparison. Keep reading for a full tutorial running Coder offline with Kubernetes or Docker.
> This is a general comparison. Keep reading for a full tutorial running Coder
> offline with Kubernetes or Docker.
| | Public deployments | Offline deployments |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@ -16,16 +18,23 @@ All Coder features are supported in offline / behind firewalls / in air-gapped e
## Offline container images
The following instructions walk you through how to build a custom Coder server image for Docker or Kubernetes
The following instructions walk you through how to build a custom Coder server
image for Docker or Kubernetes
First, build and push a container image extending our official image with the following:
First, build and push a container image extending our official image with the
following:
- CLI config (.tfrc) for Terraform referring to [external mirror](https://www.terraform.io/cli/config/config-file#explicit-installation-method-configuration)
- CLI config (.tfrc) for Terraform referring to
[external mirror](https://www.terraform.io/cli/config/config-file#explicit-installation-method-configuration)
- [Terraform Providers](https://registry.terraform.io) for templates
- These could also be specified via a volume mount (Docker) or [network mirror](https://www.terraform.io/internals/provider-network-mirror-protocol). See below for details.
- These could also be specified via a volume mount (Docker) or
[network mirror](https://www.terraform.io/internals/provider-network-mirror-protocol).
See below for details.
> Note: Coder includes the latest [supported version](https://github.com/coder/coder/blob/main/provisioner/terraform/install.go#L23-L24) of Terraform in the official Docker images.
> If you need to bundle a different version of terraform, you can do so by customizing the image.
> Note: Coder includes the latest
> [supported version](https://github.com/coder/coder/blob/main/provisioner/terraform/install.go#L23-L24)
> of Terraform in the official Docker images. If you need to bundle a different
> version of terraform, you can do so by customizing the image.
Here's an example Dockerfile:
@ -104,7 +113,9 @@ ENV TF_CLI_CONFIG_FILE=/opt/terraform/config.tfrc
```
> If you are bundling Terraform providers into your Coder image, be sure the
> provider version matches any templates or [example templates](https://github.com/coder/coder/tree/main/examples/templates) you intend to use.
> provider version matches any templates or
> [example templates](https://github.com/coder/coder/tree/main/examples/templates)
> you intend to use.
```hcl
# filesystem-mirror-example.tfrc
@ -126,7 +137,10 @@ provider_installation {
## Run offline via Docker
Follow our [docker-compose](./docker.md#run-coder-with-docker-compose) documentation and modify the docker-compose file to specify your custom Coder image. Additionally, you can add a volume mount to add providers to the filesystem mirror without re-building the image.
Follow our [docker-compose](./docker.md#run-coder-with-docker-compose)
documentation and modify the docker-compose file to specify your custom Coder
image. Additionally, you can add a volume mount to add providers to the
filesystem mirror without re-building the image.
First, make a create an empty plugins directory:
@ -158,11 +172,17 @@ services:
# ...
```
> The [terraform providers mirror](https://www.terraform.io/cli/commands/providers/mirror) command can be used to download the required plugins for a Coder template. This can be uploaded into the `plugins` directory on your offline server.
> The
> [terraform providers mirror](https://www.terraform.io/cli/commands/providers/mirror)
> command can be used to download the required plugins for a Coder template.
> This can be uploaded into the `plugins` directory on your offline server.
## Run offline via Kubernetes
We publish the Helm chart for download on [GitHub Releases](https://github.com/coder/coder/releases/latest). Follow our [Kubernetes](./kubernetes.md) documentation and modify the Helm values to specify your custom Coder image.
We publish the Helm chart for download on
[GitHub Releases](https://github.com/coder/coder/releases/latest). Follow our
[Kubernetes](./kubernetes.md) documentation and modify the Helm values to
specify your custom Coder image.
```yaml
# values.yaml
@ -188,12 +208,20 @@ coder:
## Offline docs
Coder also provides offline documentation in case you want to host it on your own server. The docs are exported as static files that you can host on any web server, as demonstrated in the example below:
Coder also provides offline documentation in case you want to host it on your
own server. The docs are exported as static files that you can host on any web
server, as demonstrated in the example below:
1. Go to the release page. In this case, we want to use the [latest version](https://github.com/coder/coder/releases/latest).
2. Download the documentation files from the "Assets" section. It is named as `coder_docs_<version>.tgz`.
1. Go to the release page. In this case, we want to use the
[latest version](https://github.com/coder/coder/releases/latest).
2. Download the documentation files from the "Assets" section. It is named as
`coder_docs_<version>.tgz`.
3. Extract the file and move its contents to your server folder.
4. If you are using NodeJS, you can execute the following command: `cd docs && npx http-server .`
5. Set the [CODER_DOCS_URL](../cli/server#--docs-url) environment variable to use the URL of your hosted docs. This way, the Coder UI will reference the documentation from your specified URL.
4. If you are using NodeJS, you can execute the following command:
`cd docs && npx http-server .`
5. Set the [CODER_DOCS_URL](../cli/server.md#--docs-url) environment variable to
use the URL of your hosted docs. This way, the Coder UI will reference the
documentation from your specified URL.
With these steps, you'll have the Coder documentation hosted on your server and accessible for your team to use.
With these steps, you'll have the Coder documentation hosted on your server and
accessible for your team to use.

101
docs/install/openshift.md
View File

@ -2,10 +2,11 @@
Before proceeding, please ensure that you have an OpenShift cluster running K8s
1.19+ (OpenShift 4.7+) and have Helm 3.5+ installed. In addition, you'll need to
install the OpenShift CLI (`oc`) to authenticate to your cluster and create OpenShift
resources.
install the OpenShift CLI (`oc`) to authenticate to your cluster and create
OpenShift resources.
You'll also want to install the [latest version of Coder](https://github.com/coder/coder/releases/latest)
You'll also want to install the
[latest version of Coder](https://github.com/coder/coder/releases/latest)
locally in order to log in and manage templates.
## Install Coder with OpenShift
@ -26,11 +27,12 @@ oc new-project coder
### 2. Configure SecurityContext values
Depending upon your configured Security Context Constraints (SCC), you'll need to modify
some or all of the following `securityContext` values from the default values:
Depending upon your configured Security Context Constraints (SCC), you'll need
to modify some or all of the following `securityContext` values from the default
values:
The below values are modified from Coder defaults and allow the Coder deployment to run
under the SCC `restricted-v2`.
The below values are modified from Coder defaults and allow the Coder deployment
to run under the SCC `restricted-v2`.
> Note: `readOnlyRootFilesystem: true` is not technically required under
> `restricted-v2`, but is often mandated in OpenShift environments.
@ -45,8 +47,8 @@ coder:
seccompProfile: RuntimeDefault # Unchanged from default
```
- For `runAsUser` / `runAsGroup`, you can retrieve the correct values for project UID and project GID with the following
command:
- For `runAsUser` / `runAsGroup`, you can retrieve the correct values for
project UID and project GID with the following command:
```console
oc get project coder -o json | jq -r '.metadata.annotations'
@ -56,12 +58,12 @@ coder:
}
```
Alternatively, you can set these values to `null` to allow OpenShift to automatically select
the correct value for the project.
Alternatively, you can set these values to `null` to allow OpenShift to
automatically select the correct value for the project.
- For `readOnlyRootFilesystem`, consult the SCC under which Coder needs to run.
In the below example, the `restricted-v2` SCC does not require a read-only root filesystem,
while `restricted-custom` does:
In the below example, the `restricted-v2` SCC does not require a read-only
root filesystem, while `restricted-custom` does:
```console
oc get scc -o wide
@ -70,34 +72,34 @@ coder:
restricted-v2 false ["NET_BIND_SERVICE"] MustRunAs MustRunAsRange MustRunAs RunAsAny <no value> false ["configMap","downwardAPI","emptyDir","ephemeral","persistentVolumeClaim","projected","secret"]
```
If you are unsure, we recommend setting `readOnlyRootFilesystem` to `true` in an OpenShift
environment.
If you are unsure, we recommend setting `readOnlyRootFilesystem` to `true` in
an OpenShift environment.
- For `seccompProfile`: in some environments, you may need to set this to `null` to allow OpenShift
to pick its preferred value.
- For `seccompProfile`: in some environments, you may need to set this to `null`
to allow OpenShift to pick its preferred value.
### 3. Configure the Coder service, connection URLs, and cache values
To establish a connection to PostgreSQL, set the `CODER_PG_CONNECTION_URL` value.
[See our Helm documentation](./kubernetes.md) on configuring the PostgreSQL connection
URL as a secret. Additionally, if accessing Coder over a hostname, set the `CODER_ACCESS_URL`
value.
To establish a connection to PostgreSQL, set the `CODER_PG_CONNECTION_URL`
value. [See our Helm documentation](./kubernetes.md) on configuring the
PostgreSQL connection URL as a secret. Additionally, if accessing Coder over a
hostname, set the `CODER_ACCESS_URL` value.
By default, Coder creates the cache directory in `/home/coder/.cache`. Given the
OpenShift-provided UID and `readOnlyRootFS` security context constraint, the Coder
container does not have permission to write to this directory.
OpenShift-provided UID and `readOnlyRootFS` security context constraint, the
Coder container does not have permission to write to this directory.
To fix this, you can mount a temporary volume in the pod and set
the `CODER_CACHE_DIRECTORY` environment variable to that location.
In the below example, we mount this under `/tmp` and set the cache location to
`/tmp/coder`. This enables Coder to run with `readOnlyRootFilesystem: true`.
To fix this, you can mount a temporary volume in the pod and set the
`CODER_CACHE_DIRECTORY` environment variable to that location. In the below
example, we mount this under `/tmp` and set the cache location to `/tmp/coder`.
This enables Coder to run with `readOnlyRootFilesystem: true`.
> Note: Depending on the number of templates and provisioners you use, you may
> need to increase the size of the volume, as the `coder` pod will be automatically
> restarted when this volume fills up.
> need to increase the size of the volume, as the `coder` pod will be
> automatically restarted when this volume fills up.
Additionally, create the Coder service as a `ClusterIP`. In the next step,
you will create an OpenShift route that points to the service HTTP target port.
Additionally, create the Coder service as a `ClusterIP`. In the next step, you
will create an OpenShift route that points to the service HTTP target port.
```yaml
coder:
@ -128,8 +130,8 @@ coder:
readOnly: false
```
> Note: OpenShift provides a Developer Catalog offering you can use to
> install PostgreSQL into your cluster.
> Note: OpenShift provides a Developer Catalog offering you can use to install
> PostgreSQL into your cluster.
### 4. Create the OpenShift route
@ -165,8 +167,8 @@ oc apply -f route.yaml
### 5. Install Coder
You can now install Coder using the values you've set from the above steps. To do
so, run the series of `helm` commands below:
You can now install Coder using the values you've set from the above steps. To
do so, run the series of `helm` commands below:
```console
helm repo add coder-v2 https://helm.coder.com/v2
@ -176,8 +178,8 @@ helm install coder coder-v2/coder \
--values values.yaml
```
> Note: If the Helm installation fails with a Kubernetes RBAC error, check the permissions
> of your OpenShift user using the `oc auth can-i` command.
> Note: If the Helm installation fails with a Kubernetes RBAC error, check the
> permissions of your OpenShift user using the `oc auth can-i` command.
>
> The below permissions are the minimum required:
>
@ -212,9 +214,9 @@ helm install coder coder-v2/coder \
### 6. Create an OpenShift-compatible image
While the deployment is spinning up, we will need to create some images that
are compatible with OpenShift. These images can then be run without modifying
the Security Context Constraints (SCCs) in OpenShift.
While the deployment is spinning up, we will need to create some images that are
compatible with OpenShift. These images can then be run without modifying the
Security Context Constraints (SCCs) in OpenShift.
1. Determine the UID range for the project:
@ -230,15 +232,18 @@ the Security Context Constraints (SCCs) in OpenShift.
}
```
Note the `uid-range` and `supplemental-groups`. In this case, the project `coder`
has been allocated 10,000 UIDs and GIDs, both starting at `1000680000`.
Note the `uid-range` and `supplemental-groups`. In this case, the project
`coder` has been allocated 10,000 UIDs and GIDs, both starting at
`1000680000`.
In this example, we will pick both UID and GID `1000680000`.
1. Create a `BuildConfig` referencing the source image you want to customize.
This will automatically kick off a `Build` that will remain pending until step 3.
This will automatically kick off a `Build` that will remain pending until
step 3.
> For more information, please consult the [OpenShift Documentation](https://docs.openshift.com/container-platform/4.12/cicd/builds/understanding-buildconfigs.html).
> For more information, please consult the
> [OpenShift Documentation](https://docs.openshift.com/container-platform/4.12/cicd/builds/understanding-buildconfigs.html).
```console
oc create -f - <<EOF
@ -289,8 +294,8 @@ the Security Context Constraints (SCCs) in OpenShift.
oc create imagestream enterprise-base
```
The `Build` created in the previous step should now begin.
Once completed, you should see output similar to the following:
The `Build` created in the previous step should now begin. Once completed,
you should see output similar to the following:
```console
oc get imagestreamtag
@ -310,8 +315,8 @@ cd ./openshift-k8s
Edit `main.tf` and update the following fields of the Kubernetes pod resource:
- `spec.security_context`: remove this field.
- `spec.container.image`: update this field to the newly built image hosted
on the OpenShift image registry from the previous step.
- `spec.container.image`: update this field to the newly built image hosted on
the OpenShift image registry from the previous step.
- `spec.container.security_context`: remove this field.
Finally, create the template:

9
docs/install/packages.md
View File

@ -1,4 +1,5 @@
1. Download and install one of the following system packages from [GitHub releases](https://github.com/coder/coder/releases/latest):
1. Download and install one of the following system packages from
[GitHub releases](https://github.com/coder/coder/releases/latest):
- .deb (Debian, Ubuntu)
- .rpm (Fedora, CentOS, RHEL, SUSE)
@ -17,9 +18,9 @@
journalctl -u coder.service -b
```
> Set `CODER_ACCESS_URL` to the external URL that users and workspaces will use to
> connect to Coder. This is not required if you are using the tunnel. Learn more
> about Coder's [configuration options](../admin/configure.md).
> Set `CODER_ACCESS_URL` to the external URL that users and workspaces will
> use to connect to Coder. This is not required if you are using the tunnel.
> Learn more about Coder's [configuration options](../admin/configure.md).
1. Visit the Coder URL in the logs to set up your first account, or use the CLI:

8
docs/install/uninstall.md
View File

@ -30,7 +30,8 @@ Alpine:
sudo apk del coder
```
If you installed Coder manually or used the install script on an unsupported operating system, you can remove the binary directly:
If you installed Coder manually or used the install script on an unsupported
operating system, you can remove the binary directly:
```console
sudo rm /usr/local/bin/coder
@ -45,9 +46,8 @@ sudo rm /etc/coder.d/coder.env
## Coder settings and the optional built-in PostgreSQL database
> There is a `postgres` directory within the `coderv2` directory that has the
> database engine and database. If you want to reuse the database, consider
> not performing the following step or copying the directory to another
> location.
> database engine and database. If you want to reuse the database, consider not
> performing the following step or copying the directory to another location.
### macOS

14
docs/install/windows.md
View File

@ -1,8 +1,12 @@
# Windows
Use the Windows installer to download the CLI and add Coder to `PATH`. Alternatively, you can install Coder on Windows via a [standalone binary](./binary.md).
Use the Windows installer to download the CLI and add Coder to `PATH`.
Alternatively, you can install Coder on Windows via a
[standalone binary](./binary.md).
1. Download the Windows installer from [GitHub releases](https://github.com/coder/coder/releases/latest) or from `winget`
1. Download the Windows installer from
[GitHub releases](https://github.com/coder/coder/releases/latest) or from
`winget`
```powershell
winget install Coder.Coder
@ -22,9 +26,9 @@ Use the Windows installer to download the CLI and add Coder to `PATH`. Alternati
coder server --postgres-url <url> --access-url <url>
```
> Set `CODER_ACCESS_URL` to the external URL that users and workspaces will use to
> connect to Coder. This is not required if you are using the tunnel. Learn more
> about Coder's [configuration options](../admin/configure.md).
> Set `CODER_ACCESS_URL` to the external URL that users and workspaces will
> use to connect to Coder. This is not required if you are using the tunnel.
> Learn more about Coder's [configuration options](../admin/configure.md).
4. Visit the Coder URL in the logs to set up your first account, or use the CLI.

53
docs/networking/index.md
View File

@ -1,29 +1,30 @@
# Networking
Coder's network topology has three types of nodes:
workspaces, coder servers, and users.
Coder's network topology has three types of nodes: workspaces, coder servers,
and users.
The coder server must have an inbound address reachable by users and workspaces,
but otherwise, all topologies _just work_ with Coder.
When possible, we establish direct connections between users and workspaces.
Direct connections are as fast as connecting to the workspace outside of Coder.
When NAT traversal fails, connections are relayed through the coder server.
All user <-> workspace connections are end-to-end encrypted.
When NAT traversal fails, connections are relayed through the coder server. All
user <-> workspace connections are end-to-end encrypted.
[Tailscale's open source](https://tailscale.com) backs our networking logic.
## coder server
Workspaces connect to the coder server via the server's external address,
set via [`ACCESS_URL`](../admin/configure.md#access-url). There must not be a
NAT between workspaces and coder server.
Workspaces connect to the coder server via the server's external address, set
via [`ACCESS_URL`](../admin/configure.md#access-url). There must not be a NAT
between workspaces and coder server.
Users connect to the coder server's dashboard and API through its `ACCESS_URL`
as well. There must not be a NAT between users and the coder server.
Template admins can overwrite the site-wide access URL at the template level by
leveraging the `url` argument when [defining the Coder provider](https://registry.terraform.io/providers/coder/coder/latest/docs#url):
leveraging the `url` argument when
[defining the Coder provider](https://registry.terraform.io/providers/coder/coder/latest/docs#url):
```terraform
provider "coder" {
@ -31,16 +32,17 @@ provider "coder" {
}
```
This is useful when debugging connectivity issues between the workspace agent and
the Coder server.
This is useful when debugging connectivity issues between the workspace agent
and the Coder server.
## Web Apps
The coder servers relays dashboard-initiated connections between the user and
the workspace. Web terminal <-> workspace connections are an exception and may be direct.
the workspace. Web terminal <-> workspace connections are an exception and may
be direct.
In general, [port forwarded](./port-forwarding.md) web apps are
faster than dashboard-accessed web apps.
In general, [port forwarded](./port-forwarding.md) web apps are faster than
dashboard-accessed web apps.
## 🌎 Geo-distribution
@ -50,16 +52,20 @@ Direct connections are a straight line between the user and workspace, so there
is no special geo-distribution configuration. To speed up direct connections,
move the user and workspace closer together.
If a direct connection is not available (e.g. client or server is behind NAT), Coder
will use a relayed connection. By default, [Coder uses Google's public STUN server](../cli/server.md#--derp-server-stun-addresses), but
this can be disabled or changed for [offline deployments](../install/offline.md).
If a direct connection is not available (e.g. client or server is behind NAT),
Coder will use a relayed connection. By default,
[Coder uses Google's public STUN server](../cli/server.md#--derp-server-stun-addresses),
but this can be disabled or changed for
[offline deployments](../install/offline.md).
### Relayed connections
By default, your Coder server also runs a built-in DERP relay which can be used for both public and [offline deployments](../install/offline.md).
By default, your Coder server also runs a built-in DERP relay which can be used
for both public and [offline deployments](../install/offline.md).
However, Tailscale has graciously allowed us to use
[their global DERP relays](https://tailscale.com/kb/1118/custom-derp-servers/#what-are-derp-servers). You can launch `coder server` with Tailscale's DERPs like so:
[their global DERP relays](https://tailscale.com/kb/1118/custom-derp-servers/#what-are-derp-servers).
You can launch `coder server` with Tailscale's DERPs like so:
```bash
$ coder server --derp-config-url https://controlplane.tailscale.com/derpmap/default
@ -67,7 +73,9 @@ $ coder server --derp-config-url https://controlplane.tailscale.com/derpmap/defa
#### Custom Relays
If you want lower latency than what Tailscale offers or want additional DERP relays for offline deployments, you may run custom DERP servers. Refer to [Tailscale's documentation](https://tailscale.com/kb/1118/custom-derp-servers/#why-run-your-own-derp-server)
If you want lower latency than what Tailscale offers or want additional DERP
relays for offline deployments, you may run custom DERP servers. Refer to
[Tailscale's documentation](https://tailscale.com/kb/1118/custom-derp-servers/#why-run-your-own-derp-server)
to learn how to set them up.
After you have custom DERP servers, you can launch Coder with them like so:
@ -109,7 +117,8 @@ Some Coder deployments require that all access is through the browser to comply
with security policies. In these cases, pass the `--browser-only` flag to
`coder server` or set `CODER_BROWSER_ONLY=true`.
With browser-only connections, developers can only connect to their workspaces via the web terminal and [web IDEs](../ides/web-ides.md).
With browser-only connections, developers can only connect to their workspaces
via the web terminal and [web IDEs](../ides/web-ides.md).
## Troubleshooting
@ -128,8 +137,8 @@ pong from my-workspace proxied via DERP(Denver) in 90ms
2023-06-21 17:50:22.504 [debu] wgengine: wg: [v2] Device closed
```
The `coder speedtest <workspace>` command measures user <-> workspace throughput.
E.g.:
The `coder speedtest <workspace>` command measures user <-> workspace
throughput. E.g.:
```
$ coder speedtest dev

51
docs/networking/port-forwarding.md
View File

@ -1,8 +1,8 @@
# Port Forwarding
Port forwarding lets developers securely access processes on their Coder
workspace from a local machine. A common use case is testing web
applications in a browser.
workspace from a local machine. A common use case is testing web applications in
a browser.
There are three ways to forward ports in Coder:
@ -14,9 +14,9 @@ The `coder port-forward` command is generally more performant.
## The `coder port-forward` command
This command can be used to forward TCP or UDP ports from the remote
workspace so they can be accessed locally. Both the TCP and UDP command
line flags (`--tcp` and `--udp`) can be given once or multiple times.
This command can be used to forward TCP or UDP ports from the remote workspace
so they can be accessed locally. Both the TCP and UDP command line flags
(`--tcp` and `--udp`) can be given once or multiple times.
The supported syntax variations for the `--tcp` and `--udp` flag are:
@ -33,8 +33,8 @@ Forward the remote TCP port `8080` to local port `8000`:
coder port-forward myworkspace --tcp 8000:8080
```
Forward the remote TCP port `3000` and all ports from `9990` to `9999`
to their respective local ports.
Forward the remote TCP port `3000` and all ports from `9990` to `9999` to their
respective local ports.
```console
coder port-forward myworkspace --tcp 3000,9990-9999
@ -46,20 +46,27 @@ For more examples, see `coder port-forward --help`.
> To enable port forwarding via the dashboard, Coder must be configured with a
> [wildcard access URL](../admin/configure.md#wildcard-access-url). If an access
> URL is not specified, Coder will create [a publicly accessible URL](../admin/configure.md#tunnel)
> to reverse proxy the deployment, and port forwarding will work. There is a
> known limitation where if the port forwarding URL length is greater than 63
> characters, port forwarding will not work.
> URL is not specified, Coder will create
> [a publicly accessible URL](../admin/configure.md#tunnel) to reverse proxy the
> deployment, and port forwarding will work. There is a known limitation where
> if the port forwarding URL length is greater than 63 characters, port
> forwarding will not work.
### From an arbitrary port
One way to port forward in the dashboard is to use the "Port forward" button to specify an arbitrary port. Coder will also detect if processes are running, and will list them below the port picklist to click an open the running processes in the browser.
One way to port forward in the dashboard is to use the "Port forward" button to
specify an arbitrary port. Coder will also detect if processes are running, and
will list them below the port picklist to click an open the running processes in
the browser.
![Port forwarding in the UI](../images/port-forward-dashboard.png)
### From an coder_app resource
Another way to port forward is to configure a `coder_app` resource in the workspace's template. This approach shows a visual application icon in the dashboard. See the following `coder_app` example for a Node React app and note the `subdomain` and `share` settings:
Another way to port forward is to configure a `coder_app` resource in the
workspace's template. This approach shows a visual application icon in the
dashboard. See the following `coder_app` example for a Node React app and note
the `subdomain` and `share` settings:
```hcl
# node app
@ -80,7 +87,9 @@ resource "coder_app" "node-react-app" {
}
```
Valid `share` values include `owner` - private to the user, `authenticated` - accessible by any user authenticated to the Coder deployment, and `public` - accessible by users outside of the Coder deployment.
Valid `share` values include `owner` - private to the user, `authenticated` -
accessible by any user authenticated to the Coder deployment, and `public` -
accessible by users outside of the Coder deployment.
![Port forwarding from an app in the UI](../images/coderapp-port-forward.png)
@ -100,7 +109,12 @@ must include credentials (set `credentials: "include"` if using `fetch`) or the
requests cannot be authenticated and you will see an error resembling the
following:
> Access to fetch at 'https://coder.example.com/api/v2/applications/auth-redirect' from origin 'https://8000--dev--user--apps.coder.example.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.
> Access to fetch at
> 'https://coder.example.com/api/v2/applications/auth-redirect' from origin
> 'https://8000--dev--user--apps.coder.example.com' has been blocked by CORS
> policy: No 'Access-Control-Allow-Origin' header is present on the requested
> resource. If an opaque response serves your needs, set the request's mode to
> 'no-cors' to fetch the resource with CORS disabled.
#### Headers
@ -197,11 +211,12 @@ configurable by either admins or users.
## SSH
First, [configure SSH](../ides.md#ssh-configuration) on your
local machine. Then, use `ssh` to forward like so:
First, [configure SSH](../ides.md#ssh-configuration) on your local machine.
Then, use `ssh` to forward like so:
```console
ssh -L 8080:localhost:8000 coder.myworkspace
```
You can read more on SSH port forwarding [here](https://www.ssh.com/academy/ssh/tunneling/example).
You can read more on SSH port forwarding
[here](https://www.ssh.com/academy/ssh/tunneling/example).

51
docs/platforms/aws.md
View File

@ -1,6 +1,10 @@
# Amazon Web Services
This guide is designed to get you up and running with a Coder proof-of-concept VM on AWS EC2 using a [Coder-provided AMI](https://github.com/coder/packages). If you are familiar with EC2 however, you can use our [install script](../install/install.sh.md) to run Coder on any popular Linux distribution.
This guide is designed to get you up and running with a Coder proof-of-concept
VM on AWS EC2 using a [Coder-provided AMI](https://github.com/coder/packages).
If you are familiar with EC2 however, you can use our
[install script](../install/install.sh.md) to run Coder on any popular Linux
distribution.
## Requirements
@ -8,34 +12,48 @@ This guide assumes your AWS account has `AmazonEC2FullAccess` permissions.
## Launch a Coder instance from the from AWS Marketplace
We publish an Ubuntu 22.04 AMI with Coder and Docker pre-installed. Search for `Coder` in the EC2 "Launch an Instance" screen or [launch directly from the marketplace](https://aws.amazon.com/marketplace/pp/prodview-5gxjyur2vc7rg).
We publish an Ubuntu 22.04 AMI with Coder and Docker pre-installed. Search for
`Coder` in the EC2 "Launch an Instance" screen or
[launch directly from the marketplace](https://aws.amazon.com/marketplace/pp/prodview-5gxjyur2vc7rg).
![Coder on AWS Marketplace](../images/platforms/aws/marketplace.png)
Be sure to keep the default firewall (SecurityGroup) options checked so you can connect over HTTP, HTTPS, and SSH.
Be sure to keep the default firewall (SecurityGroup) options checked so you can
connect over HTTP, HTTPS, and SSH.
![AWS Security Groups](../images/platforms/aws/security-groups.png)
We recommend keeping the default instance type (`t2.xlarge`, 4 cores and 16 GB memory) if you plan on provisioning Docker containers as workspaces on this EC2 instance. Keep in mind this platforms is intended for proof-of-concept deployments and you should adjust your infrastructure when preparing for production use. See: [Scaling Coder](../admin/scale.md)
We recommend keeping the default instance type (`t2.xlarge`, 4 cores and 16 GB
memory) if you plan on provisioning Docker containers as workspaces on this EC2
instance. Keep in mind this platforms is intended for proof-of-concept
deployments and you should adjust your infrastructure when preparing for
production use. See: [Scaling Coder](../admin/scale.md)
Be sure to add a keypair so that you can connect over SSH to further [configure Coder](../admin/configure.md).
Be sure to add a keypair so that you can connect over SSH to further
[configure Coder](../admin/configure.md).
After launching the instance, wait 30 seconds and navigate to the public IPv4 address. You should be redirected to a public tunnel URL.
After launching the instance, wait 30 seconds and navigate to the public IPv4
address. You should be redirected to a public tunnel URL.
<video autoplay playsinline loop>
<source src="https://github.com/coder/coder/blob/main/docs/images/platforms/aws/launch.mp4?raw=true" type="video/mp4">
Your browser does not support the video tag.
</video>
That's all! Use the UI to create your first user, template, and workspace. We recommend starting with a Docker template since the instance has Docker pre-installed.
That's all! Use the UI to create your first user, template, and workspace. We
recommend starting with a Docker template since the instance has Docker
pre-installed.
![Coder Workspace and IDE in AWS EC2](../images/platforms/aws/workspace.png)
## Configuring Coder server
Coder is primarily configured by server-side flags and environment variables. Given you created or added key-pairs when launching the instance, you can [configure your Coder deployment](../admin/configure.md) by logging in via SSH or using the console:
Coder is primarily configured by server-side flags and environment variables.
Given you created or added key-pairs when launching the instance, you can
[configure your Coder deployment](../admin/configure.md) by logging in via SSH
or using the console:
```sh
```shell
ssh ubuntu@<ec2-public-IPv4>
sudo vim /etc/coder.d/coder.env # edit config
sudo service coder restart # restart Coder
@ -43,15 +61,22 @@ sudo service coder restart # restart Coder
## Give developers EC2 workspaces (optional)
Instead of running containers on the Coder instance, you can offer developers full EC2 instances with the [aws-linux](https://github.com/coder/coder/tree/main/examples/templates/aws-linux) template.
Instead of running containers on the Coder instance, you can offer developers
full EC2 instances with the
[aws-linux](https://github.com/coder/coder/tree/main/examples/templates/aws-linux)
template.
Before you add the AWS template from the dashboard or CLI, you'll need to modify the instance IAM role.
Before you add the AWS template from the dashboard or CLI, you'll need to modify
the instance IAM role.
![Modify IAM role](../images/platforms/aws/modify-iam.png)
You must create or select a role that has `EC2FullAccess` permissions or a limited [Coder-specific permissions policy](https://github.com/coder/coder/tree/main/examples/templates/aws-linux#required-permissions--policy).
You must create or select a role that has `EC2FullAccess` permissions or a
limited
[Coder-specific permissions policy](https://github.com/coder/coder/tree/main/examples/templates/aws-linux#required-permissions--policy).
From there, you can import the AWS starter template in the dashboard and begin creating VM-based workspaces.
From there, you can import the AWS starter template in the dashboard and begin
creating VM-based workspaces.
![Modify IAM role](../images/platforms/aws/aws-linux.png)

70
docs/platforms/azure.md
View File

@ -9,23 +9,33 @@ This guide assumes you have full administrator privileges on Azure.
## Create An Azure VM
From the Azure Portal, navigate to the Virtual Machines Dashboard. Click Create, and select creating a new Azure Virtual machine .
From the Azure Portal, navigate to the Virtual Machines Dashboard. Click Create,
and select creating a new Azure Virtual machine .
<img src="../images/platforms/azure/azure1.jpg">
This will bring you to the `Create a virtual machine` page. Select the subscription group of your choice, or create one if necessary.
This will bring you to the `Create a virtual machine` page. Select the
subscription group of your choice, or create one if necessary.
Next, name the VM something relevant to this project using the naming convention of your choice. Change the region to something more appropriate for your current location. For this tutorial, we will use the base selection of the Ubuntu Gen2 Image and keep the rest of the base settings for this image the same.
Next, name the VM something relevant to this project using the naming convention
of your choice. Change the region to something more appropriate for your current
location. For this tutorial, we will use the base selection of the Ubuntu Gen2
Image and keep the rest of the base settings for this image the same.
<img src="../images/platforms/azure/azure2.png">
<img src="../images/platforms/azure/azure3.png">
Up next, under `Inbound port rules` modify the Select `inbound ports` to also take in `HTTPS` and `HTTP`.
Up next, under `Inbound port rules` modify the Select `inbound ports` to also
take in `HTTPS` and `HTTP`.
<img src="../images/platforms/azure/azure4.png">
The set up for the image is complete at this stage. Click `Review and Create` - review the information and click `Create`. A popup will appear asking you to download the key pair for the server. Click `Download private key and create resource` and place it into a folder of your choice on your local system.
The set up for the image is complete at this stage. Click `Review and Create` -
review the information and click `Create`. A popup will appear asking you to
download the key pair for the server. Click
`Download private key and create resource` and place it into a folder of your
choice on your local system.
<img src="../images/platforms/azure/azure5.png">
@ -33,13 +43,20 @@ Click `Return to create a virtual machine`. Your VM will start up!
<img src="../images/platforms/azure/azure6.png">
Click `Go to resource` in the virtual machine and copy the public IP address. You will need it to SSH into the virtual machine via your local machine.
Click `Go to resource` in the virtual machine and copy the public IP address.
You will need it to SSH into the virtual machine via your local machine.
Follow [these instructions](https://learn.microsoft.com/en-us/azure/virtual-machines/linux-vm-connect?tabs=Linux) to SSH into the virtual machine. Once on the VM, you can run and install Coder using your method of choice. For the fastest install, we recommend running Coder as a system service.
Follow
[these instructions](https://learn.microsoft.com/en-us/azure/virtual-machines/linux-vm-connect?tabs=Linux)
to SSH into the virtual machine. Once on the VM, you can run and install Coder
using your method of choice. For the fastest install, we recommend running Coder
as a system service.
## Install Coder
For this instance, we will run Coder as a system service, however you can run Coder a multitude of different ways. You can learn more about those [here](https://coder.com/docs/coder-oss/latest/install).
For this instance, we will run Coder as a system service, however you can run
Coder a multitude of different ways. You can learn more about those
[here](https://coder.com/docs/coder-oss/latest/install).
In the Azure VM instance, run the following command to install Coder
@ -61,46 +78,61 @@ The following command will get you information about the Coder launch service
journalctl -u coder.service -b
```
This will return a series of logs related to running Coder as a system service. Embedded in the logs is the Coder Access URL.
This will return a series of logs related to running Coder as a system service.
Embedded in the logs is the Coder Access URL.
Copy the URL and run the following command to create the first user, either on your local machine or in the instance terminal.
Copy the URL and run the following command to create the first user, either on
your local machine or in the instance terminal.
```shell
coder login <url***.try.coder.app>
```
Fill out the prompts. Be sure to save use email and password as these are your admin username and password.
Fill out the prompts. Be sure to save use email and password as these are your
admin username and password.
You can now access Coder on your local machine with the relevant `***.try.coder.app` URL and logging in with the username and password.
You can now access Coder on your local machine with the relevant
`***.try.coder.app` URL and logging in with the username and password.
## Creating and Uploading Your First Template
First, run `coder template init` to create your first template. You’ll be given a list of possible templates to use. This tutorial will show you how to set up your Coder instance to create a Linux based machine on Azure.
First, run `coder template init` to create your first template. You’ll be given
a list of possible templates to use. This tutorial will show you how to set up
your Coder instance to create a Linux based machine on Azure.
<img src="../images/platforms/azure/azure9.png">
Press `enter` to select `Develop in Linux on Azure` template. This will return the following:
Press `enter` to select `Develop in Linux on Azure` template. This will return
the following:
<img src="../images/platforms/azure/azure10.png">
To get started using the Azure template, install the Azure CLI by following the instructions [here](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-linux?pivots=apt). Run `az login` and follow the instructions to configure the Azure command line.
To get started using the Azure template, install the Azure CLI by following the
instructions
[here](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-linux?pivots=apt).
Run `az login` and follow the instructions to configure the Azure command line.
Coder is running as a system service, which creates the system user `coder` for handling processes. The Coder user will require access to the Azure credentials to initialize the template.
Coder is running as a system service, which creates the system user `coder` for
handling processes. The Coder user will require access to the Azure credentials
to initialize the template.
Run the following commands to copy the Azure credentials and give the `coder` user access to them:
Run the following commands to copy the Azure credentials and give the `coder`
user access to them:
```shell
sudo cp -r ~/.azure /home/coder/.azure
sudo chown -R coder:coder /home/coder/.azure/
```
Navigate to the `./azure-linux` folder where you created your template and run the following command to put the template on your Coder instance.
Navigate to the `./azure-linux` folder where you created your template and run
the following command to put the template on your Coder instance.
```shell
coder templates create
```
Congrats! You can now navigate to your Coder dashboard and use this Linux on Azure template to create a new workspace!
Congrats! You can now navigate to your Coder dashboard and use this Linux on
Azure template to create a new workspace!
## Next Steps

37
docs/platforms/docker.md
View File

@ -6,8 +6,8 @@ Coder with Docker has the following advantages:
- Workspace images are easily configured
- Workspaces share resources for burst operations
> Note that the below steps are only supported on a Linux distribution.
> If on macOS, please [run Coder via the standalone binary](../install//binary.md).
> Note that the below steps are only supported on a Linux distribution. If on
> macOS, please [run Coder via the standalone binary](../install//binary.md).
## Requirements
@ -29,18 +29,23 @@ Coder with Docker has the following advantages:
ghcr.io/coder/coder:latest
```
> This will use Coder's tunnel and built-in database. See our [Docker documentation](../install/docker.md) for other configuration options such as running on localhost, using docker-compose, and external PostgreSQL.
> This will use Coder's tunnel and built-in database. See our
> [Docker documentation](../install/docker.md) for other configuration
> options such as running on localhost, using docker-compose, and external
> PostgreSQL.
1. In new terminal, [install Coder](../install/) in order to connect to your deployment through the CLI.
1. In new terminal, [install Coder](../install/) in order to connect to your
deployment through the CLI.
```console
curl -L https://coder.com/install.sh | sh
```
1. Run `coder login <access url>` and follow the
interactive instructions to create your user.
1. Run `coder login <access url>` and follow the interactive instructions to
create your user.
1. Pull the "Docker" example template using the interactive `coder templates init`:
1. Pull the "Docker" example template using the interactive
`coder templates init`:
```console
coder templates init
@ -49,8 +54,7 @@ Coder with Docker has the following advantages:
1. Push up the template with `coder templates create`
1. Open the dashboard in your browser to create your
first workspace:
1. Open the dashboard in your browser to create your first workspace:
<img src="../images/platforms/docker/login.png">
@ -74,18 +78,25 @@ Coder with Docker has the following advantages:
You can use a remote Docker host in 2 ways.
1. Over SSH. See [here](https://registry.terraform.io/providers/kreuzwerker/docker/latest/docs#remote-hosts) for details.
2. Over TCP. See [here](https://registry.terraform.io/providers/kreuzwerker/docker/latest/docs#certificate-information) for details.
1. Over SSH. See
[here](https://registry.terraform.io/providers/kreuzwerker/docker/latest/docs#remote-hosts)
for details.
2. Over TCP. See
[here](https://registry.terraform.io/providers/kreuzwerker/docker/latest/docs#certificate-information)
for details.
## Troubleshooting
### Docker-based workspace is stuck in "Connecting..."
Ensure you have an externally-reachable `CODER_ACCESS_URL` set. See [troubleshooting templates](../templates/index.md#Troubleshooting) for more steps.
Ensure you have an externally-reachable `CODER_ACCESS_URL` set. See
[troubleshooting templates](../templates/index.md#Troubleshooting) for more
steps.
### Permission denied while trying to connect to the Docker daemon socket
See Docker's official documentation to [Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user).
See Docker's official documentation to
[Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user).
## Next Steps

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

@ -1,22 +1,31 @@
# Google Cloud Platform
In this guide, you will learn how to deploy the Coder control plane instance and your first template.
In this guide, you will learn how to deploy the Coder control plane instance and
your first template.
## Requirements
This guide assumes you have `roles/compute.instanceAdmin.v1` access to your Google Cloud Platform project.
This guide assumes you have `roles/compute.instanceAdmin.v1` access to your
Google Cloud Platform project.
## Setting Up your VM
If this is the first time you’re creating a VM on this project, you will need to enable the `Compute Engine API`. On the Compute Engine API page, click `enable` and wait for the service to finish connecting.
If this is the first time you’re creating a VM on this project, you will need to
enable the `Compute Engine API`. On the Compute Engine API page, click `enable`
and wait for the service to finish connecting.
<img src="../images/platforms/google-cloud-platform/gcp0.png">
This will pull up the `Create an Instance` page - name the instance something relevant to this project, following your naming convention of choice. In addition, select a region and zone that is close to your physical location. For this instance, we will use the base suggested image.
This will pull up the `Create an Instance` page - name the instance something
relevant to this project, following your naming convention of choice. In
addition, select a region and zone that is close to your physical location. For
this instance, we will use the base suggested image.
<img src="../images/platforms/google-cloud-platform/gcp1.png">
Under `Identity and API Access`, click `Allow full access to all Cloud APIs`. Scroll down to `Firewall` and click `Allow HTTPS traffic` and `Allow HTTP traffic`.
Under `Identity and API Access`, click `Allow full access to all Cloud APIs`.
Scroll down to `Firewall` and click `Allow HTTPS traffic` and
`Allow HTTP traffic`.
<img src="../images/platforms/google-cloud-platform/gcp2.png">
@ -26,7 +35,8 @@ Congrats you’ve created your VM instance!
## SSH-ing into the VM
On the Compute Engine Dashboard, click on the VM for this project. Under `Details`, click `SSH` and select `Open in browser window`.
On the Compute Engine Dashboard, click on the VM for this project. Under
`Details`, click `SSH` and select `Open in browser window`.
<img src="../images/platforms/google-cloud-platform/gcp3.png">
@ -42,9 +52,12 @@ curl -fsSL https://coder.com/install.sh | sh
## Run Coder
For this tutorial, we will run Coder as a `systemd` service. You can run Coder in [a multitude of different ways](https://coder.com/docs/coder-oss/latest/install).
For this tutorial, we will run Coder as a `systemd` service. You can run Coder
in
[a multitude of different ways](https://coder.com/docs/coder-oss/latest/install).
First, edit the `coder.env` file to enable `CODER_TUNNEL` by setting the value to true with the following command:
First, edit the `coder.env` file to enable `CODER_TUNNEL` by setting the value
to true with the following command:
```console
sudo vim /etc/coder.d/coder.env
@ -58,7 +71,8 @@ Exit vim and run the following command to start Coder as a system service:
sudo systemctl enable --now coder
```
The following command shows the Coder service's logs, including the Access URL. The Access URL will be used to access the Coder control plane.
The following command shows the Coder service's logs, including the Access URL.
The Access URL will be used to access the Coder control plane.
```console
journalctl -u coder.service -b
@ -66,7 +80,8 @@ journalctl -u coder.service -b
<img src="../images/platforms/google-cloud-platform/gcp5.png">
In this instance, Coder can be accessed at the URL `https://fcca2f3bfc9d2e3bf1b9feb50e723448.pit-1.try.coder.app`.
In this instance, Coder can be accessed at the URL
`https://fcca2f3bfc9d2e3bf1b9feb50e723448.pit-1.try.coder.app`.
Copy the URL and run the following command to create the workspace admin:
@ -74,11 +89,16 @@ Copy the URL and run the following command to create the workspace admin:
coder login <url***.try.coder.app>
```
Fill out the prompts and be sure to save use email and password. This is your admin login. Now, you can now access Coder from your local machine by navigating to the `***.try.coder.app` URL and logging in with that same username and password.
Fill out the prompts and be sure to save use email and password. This is your
admin login. Now, you can now access Coder from your local machine by navigating
to the `***.try.coder.app` URL and logging in with that same username and
password.
## Creating and Uploading your First Template
First, run `coder template init` to create your first template. You’ll be given a list of prefabricated templates. This tutorial shows you how to create a Linux based template on GCP.
First, run `coder template init` to create your first template. You’ll be given
a list of prefabricated templates. This tutorial shows you how to create a Linux
based template on GCP.
<img src="../images/platforms/google-cloud-platform/gcp6.png">
@ -90,23 +110,34 @@ Run the following command:
coder templates create
```
It will ask for your `project-id`, which you can find on the home page of your GCP Dashboard.
It will ask for your `project-id`, which you can find on the home page of your
GCP Dashboard.
Given it’s your first time setting up Coder, it may give an error that will look like the following:
Given it’s your first time setting up Coder, it may give an error that will look
like the following:
<img src="../images/platforms/google-cloud-platform/gcp7.png">
In the error message will be a link. In this case, the URL is `https://console.developes.google.com/apis/api/iam.googles.com/overview:?project=1073148106645`. Copy the respective URL from your error message, and visit it via your browser. It may ask you to enable `Identity and Access Management (IAM) API`.
In the error message will be a link. In this case, the URL is
`https://console.developes.google.com/apis/api/iam.googles.com/overview:?project=1073148106645`.
Copy the respective URL from your error message, and visit it via your browser.
It may ask you to enable `Identity and Access Management (IAM) API`.
Click `enable` and wait as the API initializes for your account.
Once initialized, click create credentials in the upper right-hand corner. Select the `Compute Engine API` from the dropdown, and select `Application Data` under `What data will you be accessing?`. In addition, select `Yes, I’m using one or more` under `Are you planning on using this API with Compute Engine, Kubernetes Engine, App Engine, or Cloud Functions?`.
Once initialized, click create credentials in the upper right-hand corner.
Select the `Compute Engine API` from the dropdown, and select `Application Data`
under `What data will you be accessing?`. In addition, select
`Yes, I’m using one or more` under
`Are you planning on using this API with Compute Engine, Kubernetes Engine, App Engine, or Cloud Functions?`.
<img src="../images/platforms/google-cloud-platform/gcp8.png">
Back in your GCP terminal, run the `coder templates create` one more time.
Congrats! You can now create new Linux-based workspaces that use Google Cloud Platform. Go onto your Coder dashboard, build your workspace, and get started coding!
Congrats! You can now create new Linux-based workspaces that use Google Cloud
Platform. Go onto your Coder dashboard, build your workspace, and get started
coding!
## Next Steps

77
docs/platforms/jfrog.md
View File

@ -1,18 +1,23 @@
# JFrog
Use Coder and JFrog together to secure your development environments without disturbing your developers' existing workflows.
Use Coder and JFrog together to secure your development environments without
disturbing your developers' existing workflows.
This guide will demonstrate how to use JFrog Artifactory as a package registry
within a workspace. We'll use Docker as the underlying compute. But, these concepts apply to any compute platform.
within a workspace. We'll use Docker as the underlying compute. But, these
concepts apply to any compute platform.
The full example template can be found [here](https://github.com/coder/coder/tree/main/examples/templates/jfrog/docker).
The full example template can be found
[here](https://github.com/coder/coder/tree/main/examples/templates/jfrog/docker).
## Requirements
- A JFrog Artifactory instance
- An admin-level access token for Artifactory
- 1:1 mapping of users in Coder to users in Artifactory by email address and username
- Repositories configured in Artifactory for each package manager you want to use
- 1:1 mapping of users in Coder to users in Artifactory by email address and
username
- Repositories configured in Artifactory for each package manager you want to
use
<blockquote class="info">
The admin-level access token is used to provision user tokens and is never exposed to
@ -64,7 +69,7 @@ provider "artifactory" {
When pushing the template, you can pass in the variables using the `--var` flag:
```sh
```shell
coder templates push --var 'jfrog_host=YYY.jfrog.io' --var 'artifactory_access_token=XXX'
```
@ -76,13 +81,14 @@ functionality for most developers.
Most users should be able to install `jf` by running the following command:
```sh
```shell
curl -fL https://install-cli.jfrog.io | sh
```
Other methods are listed [here](https://jfrog.com/getcli/).
In our Docker-based example, we install `jf` by adding these lines to our `Dockerfile`:
In our Docker-based example, we install `jf` by adding these lines to our
`Dockerfile`:
```Dockerfile
RUN curl -fL https://install-cli.jfrog.io | sh && chmod 755 $(which jf)
@ -90,7 +96,10 @@ RUN curl -fL https://install-cli.jfrog.io | sh && chmod 755 $(which jf)
## Configuring Coder workspace to use JFrog Artifactory repositories
Create a `locals` block to store the Artifactory repository keys for each package manager you want to use in your workspace. For example, if you want to use artifactory repositories with keys `npm`, `pypi`, and `go`, you can create a `locals` block like this:
Create a `locals` block to store the Artifactory repository keys for each
package manager you want to use in your workspace. For example, if you want to
use artifactory repositories with keys `npm`, `pypi`, and `go`, you can create a
`locals` block like this:
```hcl
locals {
@ -102,7 +111,8 @@ locals {
}
```
To automatically configure `jf` CLI and Artifactory repositories for each user, add the following lines to your `startup_script` in the `coder_agent` block:
To automatically configure `jf` CLI and Artifactory repositories for each user,
add the following lines to your `startup_script` in the `coder_agent` block:
```hcl
resource "coder_agent" "main" {
@ -146,8 +156,8 @@ resource "coder_agent" "main" {
}
```
You can verify that `jf` is configured correctly in your workspace by
running `jf c show`. It should display output like:
You can verify that `jf` is configured correctly in your workspace by running
`jf c show`. It should display output like:
```text
coder@jf:~$ jf c show
@ -165,16 +175,16 @@ Default: true
## Installing the JFrog VS Code Extension
You can install the JFrog VS Code extension into workspaces
by inserting the following lines into your `startup_script`:
You can install the JFrog VS Code extension into workspaces by inserting the
following lines into your `startup_script`:
```sh
# Install the JFrog VS Code extension.
# Find the latest version number at
# https://open-vsx.org/extension/JFrog/jfrog-vscode-extension.
JFROG_EXT_VERSION=2.4.1
curl -o /tmp/jfrog.vsix -L "https://open-vsx.org/api/JFrog/jfrog-vscode-extension/$JFROG_EXT_VERSION/file/JFrog.jfrog-vscode-extension-$JFROG_EXT_VERSION.vsix"
/tmp/code-server/bin/code-server --install-extension /tmp/jfrog.vsix
```shell
# Install the JFrog VS Code extension.
# Find the latest version number at
# https://open-vsx.org/extension/JFrog/jfrog-vscode-extension.
JFROG_EXT_VERSION=2.4.1
curl -o /tmp/jfrog.vsix -L "https://open-vsx.org/api/JFrog/jfrog-vscode-extension/$JFROG_EXT_VERSION/file/JFrog.jfrog-vscode-extension-$JFROG_EXT_VERSION.vsix"
/tmp/code-server/bin/code-server --install-extension /tmp/jfrog.vsix
```
Note that this method will only work if your developers use code-server.
@ -195,8 +205,8 @@ Artifactory:
Now, your developers can run `npm install`, `npm audit`, etc. and transparently
use Artifactory as the package registry. You can verify that `npm` is configured
correctly by running `npm install --loglevel=http react` and checking that
npm is only hitting your Artifactory URL.
correctly by running `npm install --loglevel=http react` and checking that npm
is only hitting your Artifactory URL.
## Configuring pip
@ -211,11 +221,15 @@ Artifactory:
EOF
```
Now, your developers can run `pip install` and transparently use Artifactory as the package registry. You can verify that `pip` is configured correctly by running `pip install --verbose requests` and checking that pip is only hitting your Artifactory URL.
Now, your developers can run `pip install` and transparently use Artifactory as
the package registry. You can verify that `pip` is configured correctly by
running `pip install --verbose requests` and checking that pip is only hitting
your Artifactory URL.
## Configuring Go
Add the following environment variable to your `coder_agent` block to configure `go` to use Artifactory:
Add the following environment variable to your `coder_agent` block to configure
`go` to use Artifactory:
```hcl
env = {
@ -224,10 +238,15 @@ Add the following environment variable to your `coder_agent` block to configure
```
You can apply the same concepts to Docker, Maven, and other package managers
supported by Artifactory. See the [JFrog documentation](https://jfrog.com/help/r/jfrog-artifactory-documentation/package-management) for more information.
supported by Artifactory. See the
[JFrog documentation](https://jfrog.com/help/r/jfrog-artifactory-documentation/package-management)
for more information.
## More reading
- See the full example template [here](https://github.com/coder/coder/tree/main/examples/templates/jfrog/docker).
- To serve extensions from your own VS Code Marketplace, check out [code-marketplace](https://github.com/coder/code-marketplace#artifactory-storage).
- To store templates in Artifactory, check out our [Artifactory modules](../templates/modules.md#artifactory) docs.
- See the full example template
[here](https://github.com/coder/coder/tree/main/examples/templates/jfrog/docker).
- To serve extensions from your own VS Code Marketplace, check out
[code-marketplace](https://github.com/coder/code-marketplace#artifactory-storage).
- To store templates in Artifactory, check out our
[Artifactory modules](../templates/modules.md#artifactory) docs.

64
docs/platforms/kubernetes/additional-clusters.md
View File

@ -1,15 +1,19 @@
# Additional clusters
With Coder, you can deploy workspaces in additional Kubernetes clusters using different [authentication methods](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#authentication) in the Terraform provider.
With Coder, you can deploy workspaces in additional Kubernetes clusters using
different
[authentication methods](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#authentication)
in the Terraform provider.
![Region picker in "Create Workspace" screen](../../images/platforms/kubernetes/region-picker.png)
## Option 1) Kubernetes contexts and kubeconfig
First, create a kubeconfig file with [multiple contexts](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/).
First, create a kubeconfig file with
[multiple contexts](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/).
```sh
$ kubectl config get-contexts
```shell
kubectl config get-contexts
CURRENT NAME CLUSTER
workspaces-europe-west2-c workspaces-europe-west2-c
@ -20,9 +24,10 @@ CURRENT NAME CLUSTER
If you deployed Coder on Kubernetes, you can attach a kubeconfig as a secret.
This assumes Coder is deployed on the `coder` namespace and your kubeconfig file is in ~/.kube/config.
This assumes Coder is deployed on the `coder` namespace and your kubeconfig file
is in ~/.kube/config.
```sh
```shell
kubectl create secret generic kubeconfig-secret -n coder --from-file=~/.kube/config
```
@ -41,15 +46,20 @@ coder:
readOnly: true
```
[Upgrade Coder](../../install/kubernetes.md#upgrading-coder-via-helm) with these new values.
[Upgrade Coder](../../install/kubernetes.md#upgrading-coder-via-helm) with these
new values.
### VM control plane
If you deployed Coder on a VM, copy the kubeconfig file to `/home/coder/.kube/config`.
If you deployed Coder on a VM, copy the kubeconfig file to
`/home/coder/.kube/config`.
### Create a Coder template
You can start from our [example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes). From there, add [template parameters](../../templates/parameters.md) to allow developers to pick their desired cluster.
You can start from our
[example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes).
From there, add [template parameters](../../templates/parameters.md) to allow
developers to pick their desired cluster.
```hcl
# main.tf
@ -79,17 +89,22 @@ provider "kubernetes" {
## Option 2) Kubernetes ServiceAccounts
Alternatively, you can authenticate with remote clusters with ServiceAccount tokens. Coder can store these secrets on your behalf with [managed Terraform variables](../../templates/parameters.md#managed-terraform-variables).
Alternatively, you can authenticate with remote clusters with ServiceAccount
tokens. Coder can store these secrets on your behalf with
[managed Terraform variables](../../templates/parameters.md#managed-terraform-variables).
Alternatively, these could also be fetched from Kubernetes secrets or even [Hashicorp Vault](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret).
Alternatively, these could also be fetched from Kubernetes secrets or even
[Hashicorp Vault](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret).
This guide assumes you have a `coder-workspaces` namespace on your remote cluster. Change the namespace accordingly.
This guide assumes you have a `coder-workspaces` namespace on your remote
cluster. Change the namespace accordingly.
### Create a ServiceAccount
Run this command against your remote cluster to create a ServiceAccount, Role, RoleBinding, and token:
Run this command against your remote cluster to create a ServiceAccount, Role,
RoleBinding, and token:
```sh
```shell
kubectl apply -n coder-workspaces -f - <<EOF
apiVersion: v1
kind: ServiceAccount
@ -141,7 +156,8 @@ rolebinding.rbac.authorization.k8s.io/coder created
### 2. Modify the Kubernetes template
You can start from our [example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes).
You can start from our
[example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes).
```hcl
variable "host" {
@ -172,20 +188,21 @@ provider "kubernetes" {
### Create Coder template with managed variables
Fetch the values from the secret and pass them to Coder. This should work on macOS and Linux.
Fetch the values from the secret and pass them to Coder. This should work on
macOS and Linux.
To get the cluster address:
```sh
$ kubectl cluster-info
```shell
kubectl cluster-info
Kubernetes control plane is running at https://example.domain:6443
$ export CLUSTER_ADDRESS=https://example.domain:6443
export CLUSTER_ADDRESS=https://example.domain:6443
```
To fetch the CA certificate and token:
```sh
```shell
export CLUSTER_CA_CERTIFICATE=$(kubectl get secrets coder-service-account-token -n coder-workspaces -o jsonpath="{.data.ca\.crt}")
export CLUSTER_SERVICEACCOUNT_TOKEN=$(kubectl get secrets coder-service-account-token -n coder-workspaces -o jsonpath="{.data.token}")
@ -193,7 +210,7 @@ export CLUSTER_SERVICEACCOUNT_TOKEN=$(kubectl get secrets coder-service-account-
Create the template with these values:
```sh
```shell
coder templates create \
--variable host=$CLUSTER_ADDRESS \
--variable cluster_ca_certificate=$CLUSTER_CA_CERTIFICATE \
@ -201,9 +218,10 @@ coder templates create \
--variable namespace=coder-workspaces
```
If you're on a Windows machine (or if one of the commands fail), try grabbing the values manually:
If you're on a Windows machine (or if one of the commands fail), try grabbing
the values manually:
```sh
```shell
# Get cluster API address
kubectl cluster-info

33
docs/platforms/kubernetes/deployment-logs.md
View File

@ -1,13 +1,22 @@
# Kubernetes event logs
To stream Kubernetes events into your workspace startup logs, you can use Coder's [`coder-logstream-kube`](https://github.com/coder/coder-logstream-kube) tool. `coder-logstream-kube` provides useful information about the workspace pod or deployment, such as:
To stream Kubernetes events into your workspace startup logs, you can use
Coder's [`coder-logstream-kube`](https://github.com/coder/coder-logstream-kube)
tool. `coder-logstream-kube` provides useful information about the workspace pod
or deployment, such as:
- Causes of pod provisioning failures, or why a pod is stuck in a pending state.
- Visibility into when pods are OOMKilled, or when they are evicted.
## Prerequisites
`coder-logstream-kube` works best with the [`kubernetes_deployment`](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/deployment) Terraform resource, which requires the `coder` service account to have permission to create deployments. For example, if you use [Helm](https://coder.com/docs/v2/latest/install/kubernetes#install-coder-with-helm) to install Coder, you should set `coder.serviceAccount.enableDeployments=true` in your `values.yaml`
`coder-logstream-kube` works best with the
[`kubernetes_deployment`](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/deployment)
Terraform resource, which requires the `coder` service account to have
permission to create deployments. For example, if you use
[Helm](../../install/kubernetes.md#install-coder-with-helm) to install Coder,
you should set `coder.serviceAccount.enableDeployments=true` in your
`values.yaml`
```diff
coder:
@ -19,11 +28,13 @@ serviceAccount:
name: coder
```
> Note: This is only required for Coder versions < 0.28.0, as this will be the default value for Coder versions >= 0.28.0
> Note: This is only required for Coder versions < 0.28.0, as this will be the
> default value for Coder versions >= 0.28.0
## Installation
Install the `coder-kubestream-logs` helm chart on the cluster where the deployment is running.
Install the `coder-kubestream-logs` helm chart on the cluster where the
deployment is running.
```shell
helm repo add coder-logstream-kube https://helm.coder.com/logstream-kube
@ -34,7 +45,8 @@ helm install coder-logstream-kube coder-logstream-kube/coder-logstream-kube \
## Example logs
Here is an example of the logs you can expect to see in the workspace startup logs:
Here is an example of the logs you can expect to see in the workspace startup
logs:
### Normal pod deployment
@ -54,6 +66,13 @@ Here is an example of the logs you can expect to see in the workspace startup lo
## How it works
Kubernetes provides an [informers](https://pkg.go.dev/k8s.io/client-go/informers) API that streams pod and event data from the API server.
Kubernetes provides an
[informers](https://pkg.go.dev/k8s.io/client-go/informers) API that streams pod
and event data from the API server.
coder-logstream-kube listens for pod creation events with containers that have the CODER_AGENT_TOKEN environment variable set. All pod events are streamed as logs to the Coder API using the agent token for authentication. For more details, see the [coder-logstream-kube](https://github.com/coder/coder-logstream-kube) repository.
coder-logstream-kube listens for pod creation events with containers that have
the CODER_AGENT_TOKEN environment variable set. All pod events are streamed as
logs to the Coder API using the agent token for authentication. For more
details, see the
[coder-logstream-kube](https://github.com/coder/coder-logstream-kube)
repository.

12
docs/platforms/kubernetes/index.md
View File

@ -4,10 +4,12 @@ Coder's control plane and/or workspaces can be deployed on Kubernetes.
## Installation
Refer to our [Helm install docs](../../install/kubernetes.md) to deploy Coder on Kubernetes. The default helm values will provision the following:
Refer to our [Helm install docs](../../install/kubernetes.md) to deploy Coder on
Kubernetes. The default helm values will provision the following:
- Coder control plane (as a `Deployment`)
- ServiceAccount + Role + RoleBinding to provision pods + PVCS in the current namespace (used for Kubernetes workspaces)
- ServiceAccount + Role + RoleBinding to provision pods + PVCS in the current
namespace (used for Kubernetes workspaces)
- LoadBalancer to access control plane
## Kubernetes templates
@ -18,9 +20,11 @@ From the dashboard, import the Kubernetes starter template:
In the next screen, set the following template variables:
- `use_kubeconfig`: `false` (The ServiceAccount will authorize Coder to create pods on your cluster)
- `use_kubeconfig`: `false` (The ServiceAccount will authorize Coder to create
pods on your cluster)
- `namespace`: `coder` (or whatever namespace you deployed Coder on)
![Variables for Kubernetes template](../../images/platforms/kubernetes/template-variables.png)
> If you deployed Coder on another platform besides Kubernetes, you can set `use_kubeconfig: true` for Coder to read the config from your VM, for example.
> If you deployed Coder on another platform besides Kubernetes, you can set
> `use_kubeconfig: true` for Coder to read the config from your VM, for example.

5
docs/platforms/other.md
View File

@ -1,6 +1,9 @@
# Other platforms
Coder is highly extensible and is not limited to the platforms outlined in these docs. The control plane can be provisioned on any VM or container compute, and workspaces can include any Terraform resource. See our [architecture diagram](../about/architecture.md) for more details.
Coder is highly extensible and is not limited to the platforms outlined in these
docs. The control plane can be provisioned on any VM or container compute, and
workspaces can include any Terraform resource. See our
[architecture diagram](../about/architecture.md) for more details.
The following resources may help as you're deploying Coder.

39
docs/secrets.md
View File

@ -9,26 +9,26 @@ Coder is open-minded about how you get your secrets into your workspaces.
## Wait a minute...
Your first stab at secrets with Coder should be your local method.
You can do everything you can locally and more with your Coder workspace, so
whatever workflow and tools you already use to manage secrets may be brought
over.
Your first stab at secrets with Coder should be your local method. You can do
everything you can locally and more with your Coder workspace, so whatever
workflow and tools you already use to manage secrets may be brought over.
Often, this workflow is simply:
1. Give your users their secrets in advance
1. Your users write them to a persistent file after
they've built their workspace
1. Your users write them to a persistent file after they've built their
workspace
[Template parameters](./templates/parameters.md) are a dangerous way to accept secrets.
We show parameters in cleartext around the product. Assume anyone with view
access to a workspace can also see its parameters.
[Template parameters](./templates/parameters.md) are a dangerous way to accept
secrets. We show parameters in cleartext around the product. Assume anyone with
view access to a workspace can also see its parameters.
## SSH Keys
Coder generates SSH key pairs for each user. This can be used as an authentication mechanism for
git providers or other tools. Within workspaces, git will attempt to use this key within workspaces
via the `$GIT_SSH_COMMAND` environment variable.
Coder generates SSH key pairs for each user. This can be used as an
authentication mechanism for git providers or other tools. Within workspaces,
git will attempt to use this key within workspaces via the `$GIT_SSH_COMMAND`
environment variable.
Users can view their public key in their account settings:
@ -40,8 +40,8 @@ Users can view their public key in their account settings:
## Dynamic Secrets
Dynamic secrets are attached to the workspace lifecycle and automatically
injected into the workspace. With a little bit of up front template work,
they make life simpler for both the end user and the security team.
injected into the workspace. With a little bit of up front template work, they
make life simpler for both the end user and the security team.
This method is limited to
[services with Terraform providers](https://registry.terraform.io/browse/providers),
@ -64,14 +64,17 @@ resource "coder_agent" "main" {
}
```
A catch-all variation of this approach is dynamically provisioning a cloud service account (e.g [GCP](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/google_service_account_key#private_key))
for each workspace and then making the relevant secrets available via the cloud's secret management
system.
A catch-all variation of this approach is dynamically provisioning a cloud
service account (e.g
[GCP](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/google_service_account_key#private_key))
for each workspace and then making the relevant secrets available via the
cloud's secret management system.
## Displaying Secrets
While you can inject secrets into the workspace via environment variables, you
can also show them in the Workspace UI with [`coder_metadata`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/metadata).
can also show them in the Workspace UI with
[`coder_metadata`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/metadata).
![secret UI](./images/secret-metadata-ui.png)

35
docs/security/0001_user_apikeys_invalidation.md
View File

@ -4,31 +4,47 @@
## Summary
Coder identified an issue in [https://github.com/coder/coder](https://github.com/coder/coder) where API tokens belonging to a deleted user were not invalidated. A deleted user in possession of a valid and non-expired API token is still able to use the above token with their full suite of capabilities.
Coder identified an issue in
[https://github.com/coder/coder](https://github.com/coder/coder) where API
tokens belonging to a deleted user were not invalidated. A deleted user in
possession of a valid and non-expired API token is still able to use the above
token with their full suite of capabilities.
## Impact: HIGH
If exploited, an attacker could perform any action that the deleted user was authorized to perform.
If exploited, an attacker could perform any action that the deleted user was
authorized to perform.
## Exploitability: HIGH
The CLI writes the API key to `~/.coderv2/session` by default, so any deleted user who previously logged in via the Coder CLI has the potential to exploit this. Note that there is a time window for exploitation; API tokens have a maximum lifetime after which they are no longer valid.
The CLI writes the API key to `~/.coderv2/session` by default, so any deleted
user who previously logged in via the Coder CLI has the potential to exploit
this. Note that there is a time window for exploitation; API tokens have a
maximum lifetime after which they are no longer valid.
The issue only affects users who were active (not suspended) at the time they were deleted. Users who were first suspended and later deleted cannot exploit this issue.
The issue only affects users who were active (not suspended) at the time they
were deleted. Users who were first suspended and later deleted cannot exploit
this issue.
## Affected Versions
All versions of Coder between v0.8.15 and v0.22.2 (inclusive) are affected.
All customers are advised to upgrade to [v0.23.0](https://github.com/coder/coder/releases/tag/v0.23.0) as soon as possible.
All customers are advised to upgrade to
[v0.23.0](https://github.com/coder/coder/releases/tag/v0.23.0) as soon as
possible.
## Details
Coder incorrectly failed to invalidate API keys belonging to a user when they were deleted. When authenticating a user via their API key, Coder incorrectly failed to check whether the API key corresponds to a deleted user.
Coder incorrectly failed to invalidate API keys belonging to a user when they
were deleted. When authenticating a user via their API key, Coder incorrectly
failed to check whether the API key corresponds to a deleted user.
## Indications of Compromise
> 💡 Automated remediation steps in the upgrade purge all affected API keys. Either perform the following query before upgrade or run it on a backup of your database from before the upgrade.
> 💡 Automated remediation steps in the upgrade purge all affected API keys.
> Either perform the following query before upgrade or run it on a backup of
> your database from before the upgrade.
Execute the following SQL query:
@ -65,4 +81,7 @@ Otherwise, the following information will be reported:
- User API key ID
- Time the affected API key was last used
> 💡 If your license includes the [Audit Logs](https://coder.com/docs/v2/latest/admin/audit-logs#filtering-logs) feature, you can then query all actions performed by the above users by using the filter `email:$USER_EMAIL`.
> 💡 If your license includes the
> [Audit Logs](https://coder.com/docs/v2/latest/admin/audit-logs#filtering-logs)
> feature, you can then query all actions performed by the above users by using
> the filter `email:$USER_EMAIL`.

13
docs/security/index.md
View File

@ -1,12 +1,17 @@
# Security Advisories
> If you discover a vulnerability in Coder, please do not hesitate to report it to us by following the instructions [here](https://github.com/coder/coder/blob/main/SECURITY.md).
> If you discover a vulnerability in Coder, please do not hesitate to report it
> to us by following the instructions
> [here](https://github.com/coder/coder/blob/main/SECURITY.md).
From time to time, Coder employees or other community members may discover vulnerabilities in the product.
From time to time, Coder employees or other community members may discover
vulnerabilities in the product.
If a vulnerability requires an immediate upgrade to mitigate a potential security risk, we will add it to the below table.
If a vulnerability requires an immediate upgrade to mitigate a potential
security risk, we will add it to the below table.
Click on the description links to view more details about each specific vulnerability.
Click on the description links to view more details about each specific
vulnerability.
---

28
docs/templates/README.md vendored
View File

@ -16,13 +16,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 +31,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 +41,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 <your-api-key> login https://coder.example.com/ # aka the URL to your coder instance
```
@ -49,7 +49,7 @@ coder --token <your-api-key> 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 +74,7 @@ coder templates create <template-name>
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
```
@ -232,7 +232,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 {
@ -254,7 +254,7 @@ Using the UI, navigate to the template page, click on the menu, and select "Edit
Using the CLI, login to Coder and run the following command to edit a single
template:
```console
```shell
coder templates edit <template-name> --description "This is my template"
```
@ -263,20 +263,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 <template-name> 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 <template-name>
```
@ -292,7 +292,7 @@ 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 <template-name>
```
@ -329,7 +329,7 @@ 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 = {
@ -370,7 +370,7 @@ practices:
- 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)
- 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)
### Agent does not become ready

46
docs/templates/agent-metadata.md vendored
View File

@ -2,19 +2,23 @@
![agent-metadata](../images/agent-metadata.png)
With Agent Metadata, template admins can expose operational metrics from
their workspaces to their users. It is the dynamic complement of [Resource Metadata](./resource-metadata.md).
With Agent Metadata, template admins can expose operational metrics from their
workspaces to their users. It is the dynamic complement of
[Resource Metadata](./resource-metadata.md).
See the [Terraform reference](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#metadata).
See the
[Terraform reference](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#metadata).
## Examples
All of these examples use [heredoc strings](https://developer.hashicorp.com/terraform/language/expressions/strings#heredoc-strings) for the script declaration. With heredoc strings, you
can script without messy escape codes, just as if you were working in your terminal.
All of these examples use
[heredoc strings](https://developer.hashicorp.com/terraform/language/expressions/strings#heredoc-strings)
for the script declaration. With heredoc strings, you can script without messy
escape codes, just as if you were working in your terminal.
Some of the below examples use the [`coder stat`](../cli/stat.md) command.
This is useful for determining CPU/memory usage inside a container, which
can be tricky otherwise.
Some of the below examples use the [`coder stat`](../cli/stat.md) command. This
is useful for determining CPU/memory usage inside a container, which can be
tricky otherwise.
Here's a standard set of metadata snippets for Linux agents:
@ -84,9 +88,9 @@ resource "coder_agent" "main" {
## Utilities
[top](https://linux.die.net/man/1/top) is available in most Linux
distributions and provides virtual memory, CPU and IO statistics. Running `top`
produces output that looks like:
[top](https://linux.die.net/man/1/top) is available in most Linux distributions
and provides virtual memory, CPU and IO statistics. Running `top` produces
output that looks like:
```text
%Cpu(s): 65.8 us, 4.4 sy, 0.0 ni, 29.3 id, 0.3 wa, 0.0 hi, 0.2 si, 0.0 st
@ -95,8 +99,8 @@ MiB Swap: 0.0 total, 0.0 free, 0.0 used. 11021.3 avail Mem
```
[vmstat](https://linux.die.net/man/8/vmstat) is available in most Linux
distributions and provides virtual memory, CPU and IO statistics. Running `vmstat`
produces output that looks like:
distributions and provides virtual memory, CPU and IO statistics. Running
`vmstat` produces output that looks like:
```text
procs -----------memory---------- ---swap-- -----io---- -system-- ------cpu-----
@ -104,9 +108,9 @@ r b swpd free buff cache si so bi bo in cs us sy id wa st
0 0 19580 4781680 12133692 217646944 0 2 4 32 1 0 1 1 98 0 0
```
[dstat](https://linux.die.net/man/1/dstat) is considerably more parseable
than `vmstat` but often not included in base images. It is easily installed by
most package managers under the name `dstat`. The output of running `dstat 1 1` looks
[dstat](https://linux.die.net/man/1/dstat) is considerably more parseable than
`vmstat` but often not included in base images. It is easily installed by most
package managers under the name `dstat`. The output of running `dstat 1 1` looks
like:
```text
@ -117,9 +121,9 @@ usr sys idl wai stl| read writ| recv send| in out | int csw
## DB Write Load
Agent metadata can generate a significant write load and overwhelm your
database if you're not careful. The approximate writes per second can be
calculated using the formula:
Agent metadata can generate a significant write load and overwhelm your database
if you're not careful. The approximate writes per second can be calculated using
the formula:
```text
(metadata_count * num_running_agents * 2) / metadata_avg_interval
@ -133,5 +137,5 @@ For example, let's say you have
You can expect `(10 * 6 * 2) / 4` or 30 writes per second.
One of the writes is to the `UNLOGGED` `workspace_agent_metadata` table and
the other to the `NOTIFY` query that enables live stats streaming in the UI.
One of the writes is to the `UNLOGGED` `workspace_agent_metadata` table and the
other to the `NOTIFY` query that enables live stats streaming in the UI.

33
docs/templates/authentication.md vendored
View File

@ -7,16 +7,19 @@
</p>
</blockquote>
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.

10
docs/templates/change-management.md vendored
View File

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

42
docs/templates/devcontainers.md vendored
View File

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

122
docs/templates/docker-in-workspaces.md vendored
View File

@ -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 <<EOF | kubectl create -f -
apiVersion: apps/v1
kind: DaemonSet
@ -220,30 +251,40 @@ Prior to completing the steps below, please review the following Podman document
2. Be sure to label your nodes to enable smarter-device-manager:
```sh
```shell
kubectl get nodes
kubectl label nodes --all smarter-device-manager=enabled
```
> ⚠️ **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 {

263
docs/templates/index.md vendored
View File

@ -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 <your-api-key> login https://coder.example.com/ # aka the URL to your coder instance
```
@ -49,7 +50,7 @@ coder --token <your-api-key> 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 <template-name>
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 <template-name> --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 <template-name> 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 <template-name>
```
@ -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 <template-name>
```
@ -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)

60
docs/templates/modules.md vendored
View File

@ -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 - <<EOF
apiVersion: v1
@ -90,8 +110,8 @@ coder:
## Artifactory
JFrog Artifactory can serve as a Terraform module registry, allowing you to simplify
a Coder-stored template to a `module` block and input variables.
JFrog Artifactory can serve as a Terraform module registry, allowing you to
simplify a Coder-stored template to a `module` block and input variables.
With this approach, you can:
@ -114,7 +134,7 @@ Remember to replace `cdr.jfrog.io` with your Artifactory instance URL.
You can upload the underlying module to Artifactory with:
```console
```shell
# one-time setup commands
# run this on the coder server (or external provisioners, if you have them)
terraform login cdr.jfrog.io; jf tfc --global
@ -125,12 +145,16 @@ jf tf p --namespace=main --provider=docker --tag=v0.0.1
### Example template
We have an example template [here](https://github.com/coder/coder/tree/main/examples/templates/jfrog/remote) that uses our [JFrog Docker](../platforms/jfrog.md) template
as the underlying module.
We have an example template
[here](https://github.com/coder/coder/tree/main/examples/templates/jfrog/remote)
that uses our [JFrog Docker](../platforms/jfrog.md) template as the underlying
module.
### Next up
Learn more about
- JFrog's Terraform Registry support [here](https://jfrog.com/help/r/jfrog-artifactory-documentation/terraform-registry).
- Configuring the JFrog toolchain inside a workspace [here](../platforms/jfrog.md).
- JFrog's Terraform Registry support
[here](https://jfrog.com/help/r/jfrog-artifactory-documentation/terraform-registry).
- Configuring the JFrog toolchain inside a workspace
[here](../platforms/jfrog.md).

26
docs/templates/open-in-coder.md vendored
View File

@ -1,6 +1,7 @@
# Open in Coder
An "Open in Coder" button can be embedded into your git repos or internal wikis to allow developers to quickly launch a new workspace.
An "Open in Coder" button can be embedded into your git repos or internal wikis
to allow developers to quickly launch a new workspace.
<video autoplay playsinline loop>
<source src="https://github.com/coder/coder/blob/main/docs/images/templates/open-in-coder.mp4?raw=true" type="video/mp4">
@ -9,13 +10,17 @@ Your browser does not support the video tag.
## How it works
To support any infrastructure and software stack, Coder provides a generic approach for "Open in Coder" flows.
To support any infrastructure and software stack, Coder provides a generic
approach for "Open in Coder" flows.
1. Set up [Git Authentication](../admin/git-providers.md#require-git-authentication-in-templates) in your Coder deployment
1. Set up
[Git Authentication](../admin/git-providers.md#require-git-authentication-in-templates)
in your Coder deployment
1. Modify your template to auto-clone repos:
> The id in the template's `coder_git_auth` data source must match the `CODER_GITAUTH_0_ID` in the Coder deployment configuration.
> The id in the template's `coder_git_auth` data source must match the
> `CODER_GITAUTH_0_ID` in the Coder deployment configuration.
- If you want the template to clone a specific git repo
@ -46,7 +51,8 @@ To support any infrastructure and software stack, Coder provides a generic appro
> - `/home/coder/coder`
> - `coder` (relative to the home directory)
- If you want the template to support any repository via [parameters](./parameters.md)
- If you want the template to support any repository via
[parameters](./parameters.md)
```hcl
# Require git authentication to use this template
@ -86,7 +92,9 @@ To support any infrastructure and software stack, Coder provides a generic appro
[![Open in Coder](https://YOUR_ACCESS_URL/open-in-coder.svg)](https://YOUR_ACCESS_URL/templates/YOUR_TEMPLATE/workspace)
```
> Be sure to replace `YOUR_ACCESS_URL` with your Coder access url (e.g. https://coder.example.com) and `YOUR_TEMPLATE` with the name of your template.
> Be sure to replace `YOUR_ACCESS_URL` with your Coder access url (e.g.
> https://coder.example.com) and `YOUR_TEMPLATE` with the name of your
> template.
1. Optional: pre-fill parameter values in the "Create Workspace" page
@ -100,8 +108,10 @@ To support any infrastructure and software stack, Coder provides a generic appro
## Example: Kubernetes
For a full example of the Open in Coder flow in Kubernetes, check out [this example template](https://github.com/bpmct/coder-templates/tree/main/kubernetes-open-in-coder).
For a full example of the Open in Coder flow in Kubernetes, check out
[this example template](https://github.com/bpmct/coder-templates/tree/main/kubernetes-open-in-coder).
## Devcontainer support
Devcontainer support is on the roadmap. [Follow along here](https://github.com/coder/coder/issues/5559)
Devcontainer support is on the roadmap.
[Follow along here](https://github.com/coder/coder/issues/5559)

115
docs/templates/parameters.md vendored
View File

@ -1,6 +1,7 @@
# Parameters
Templates can contain _parameters_, which allow prompting the user for additional information when creating workspaces in both the UI and CLI.
Templates can contain _parameters_, which allow prompting the user for
additional information when creating workspaces in both the UI and CLI.
![Parameters in Create Workspace screen](../images/parameters.png)
@ -45,12 +46,15 @@ provider "docker" {
## Types
The following parameter types are supported: `string`, `list(string)`, `bool`, and `number`.
The following parameter types are supported: `string`, `list(string)`, `bool`,
and `number`.
### List of strings
List of strings is a specific parameter type, that can't be easily mapped to the default value, which is string type.
Parameters with the `list(string)` type must be converted to JSON arrays using [jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode)
List of strings is a specific parameter type, that can't be easily mapped to the
default value, which is string type. Parameters with the `list(string)` type
must be converted to JSON arrays using
[jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode)
function.
```hcl
@ -101,7 +105,9 @@ data "coder_parameter" "docker_host" {
## Required and optional parameters
A parameter is considered to be _required_ if it doesn't have the `default` property. The user **must** provide a value to this parameter before creating a workspace.
A parameter is considered to be _required_ if it doesn't have the `default`
property. The user **must** provide a value to this parameter before creating a
workspace.
```hcl
data "coder_parameter" "account_name" {
@ -111,8 +117,8 @@ data "coder_parameter" "account_name" {
}
```
If a parameter contains the `default` property, Coder will use this value
if the user does not specify any:
If a parameter contains the `default` property, Coder will use this value if the
user does not specify any:
```hcl
data "coder_parameter" "base_image" {
@ -122,7 +128,8 @@ data "coder_parameter" "base_image" {
}
```
Admins can also set the `default` property to an empty value so that the parameter field can remain empty:
Admins can also set the `default` property to an empty value so that the
parameter field can remain empty:
```hcl
data "coder_parameter" "dotfiles_url" {
@ -133,7 +140,10 @@ data "coder_parameter" "dotfiles_url" {
}
```
Terraform [conditional expressions](https://developer.hashicorp.com/terraform/language/expressions/conditionals) can be used to determine whether the user specified a value for an optional parameter:
Terraform
[conditional expressions](https://developer.hashicorp.com/terraform/language/expressions/conditionals)
can be used to determine whether the user specified a value for an optional
parameter:
```hcl
resource "coder_agent" "main" {
@ -150,7 +160,10 @@ resource "coder_agent" "main" {
## Mutability
Immutable parameters can be only set before workspace creation, or during update on the first usage to set the initial value for required parameters. The idea is to prevent users from modifying fragile or persistent workspace resources like volumes, regions, etc.:
Immutable parameters can be only set before workspace creation, or during update
on the first usage to set the initial value for required parameters. The idea is
to prevent users from modifying fragile or persistent workspace resources like
volumes, regions, etc.:
```hcl
data "coder_parameter" "region" {
@ -161,16 +174,19 @@ data "coder_parameter" "region" {
}
```
It is allowed to modify the mutability state anytime. In case of emergency, template authors can temporarily allow for changing immutable parameters to fix an operational issue, but it is not
advised to overuse this opportunity.
It is allowed to modify the mutability state anytime. In case of emergency,
template authors can temporarily allow for changing immutable parameters to fix
an operational issue, but it is not advised to overuse this opportunity.
## Ephemeral parameters
Ephemeral parameters are introduced to users in the form of "build options." This functionality can be used to model
specific behaviors within a Coder workspace, such as reverting to a previous image, restoring from a volume snapshot, or
building a project without utilizing cache.
Ephemeral parameters are introduced to users in the form of "build options."
This functionality can be used to model specific behaviors within a Coder
workspace, such as reverting to a previous image, restoring from a volume
snapshot, or building a project without utilizing cache.
As these parameters are ephemeral in nature, subsequent builds will proceed in the standard manner.
As these parameters are ephemeral in nature, subsequent builds will proceed in
the standard manner.
```hcl
data "coder_parameter" "force_rebuild" {
@ -185,12 +201,15 @@ data "coder_parameter" "force_rebuild" {
## Validation
Rich parameters support multiple validation modes - min, max, monotonic numbers, and regular expressions.
Rich parameters support multiple validation modes - min, max, monotonic numbers,
and regular expressions.
### Number
A _number_ parameter can be limited to boundaries - min, max. Additionally, the monotonicity (`increasing` or `decreasing`) between the current parameter value and the new one can be verified too.
Monotonicity can be enabled for resources that can't be shrunk without implications, for instance - disk volume size.
A _number_ parameter can be limited to boundaries - min, max. Additionally, the
monotonicity (`increasing` or `decreasing`) between the current parameter value
and the new one can be verified too. Monotonicity can be enabled for resources
that can't be shrunk without implications, for instance - disk volume size.
```hcl
data "coder_parameter" "instances" {
@ -207,7 +226,9 @@ data "coder_parameter" "instances" {
### String
A _string_ parameter can have a regular expression defined to make sure that the parameter value matches the pattern. The `regex` property requires a corresponding `error` property.
A _string_ parameter can have a regular expression defined to make sure that the
parameter value matches the pattern. The `regex` property requires a
corresponding `error` property.
```hcl
data "coder_parameter" "project_id" {
@ -224,21 +245,29 @@ data "coder_parameter" "project_id" {
### Legacy parameters are unsupported now
In Coder, workspaces using legacy parameters can't be deployed anymore. To address this, it is necessary to either remove or adjust incompatible templates.
In some cases, deleting a workspace with a hard dependency on a legacy parameter may be challenging. To cleanup unsupported workspaces, administrators are advised to take the following actions for affected templates:
In Coder, workspaces using legacy parameters can't be deployed anymore. To
address this, it is necessary to either remove or adjust incompatible templates.
In some cases, deleting a workspace with a hard dependency on a legacy parameter
may be challenging. To cleanup unsupported workspaces, administrators are
advised to take the following actions for affected templates:
1. Enable the `feature_use_managed_variables` provider flag.
2. Ensure that every legacy variable block has defined missing default values, or convert it to `coder_parameter`.
2. Ensure that every legacy variable block has defined missing default values,
or convert it to `coder_parameter`.
3. Push the new template version using UI or CLI.
4. Update unsupported workspaces to the newest template version.
5. Delete the affected workspaces that have been updated to the newest template version.
5. Delete the affected workspaces that have been updated to the newest template
version.
### Migration
> ⚠️ Migration is available until v0.24.0 (Jun 2023) release.
Terraform `variable` shouldn't be used for workspace scoped parameters anymore, and it's required to convert `variable` to `coder_parameter` resources. To make the migration smoother, there is a special property introduced -
`legacy_variable` and `legacy_variable_name` , which can link `coder_parameter` with a legacy variable.
Terraform `variable` shouldn't be used for workspace scoped parameters anymore,
and it's required to convert `variable` to `coder_parameter` resources. To make
the migration smoother, there is a special property introduced -
`legacy_variable` and `legacy_variable_name` , which can link `coder_parameter`
with a legacy variable.
```hcl
variable "legacy_cpu" {
@ -263,33 +292,44 @@ data "coder_parameter" "cpu" {
1. Prepare and update a new template version:
- Add `coder_parameter` resource matching the legacy variable to migrate.
- Use `legacy_variable_name` and `legacy_variable` to link the `coder_parameter` to the legacy variable.
- Mark the new parameter as `mutable`, so that Coder will not block updating existing workspaces.
- Use `legacy_variable_name` and `legacy_variable` to link the
`coder_parameter` to the legacy variable.
- Mark the new parameter as `mutable`, so that Coder will not block updating
existing workspaces.
2. Update all workspaces to the updated template version. Coder will populate the added `coder_parameter`s with values from legacy variables.
2. Update all workspaces to the updated template version. Coder will populate
the added `coder_parameter`s with values from legacy variables.
3. Prepare another template version:
- Remove the migrated variables.
- Remove properties `legacy_variable` and `legacy_variable_name` from `coder_parameter`s.
- Remove properties `legacy_variable` and `legacy_variable_name` from
`coder_parameter`s.
4. Update all workspaces to the updated template version (2nd).
5. Prepare a third template version:
- Enable the `feature_use_managed_variables` provider flag to use managed Terraform variables for template customization. Once the flag is enabled, legacy variables won't be used.
- Enable the `feature_use_managed_variables` provider flag to use managed
Terraform variables for template customization. Once the flag is enabled,
legacy variables won't be used.
6. Update all workspaces to the updated template version (3rd).
7. Delete legacy parameters.
As a template improvement, the template author can consider making some of the new `coder_parameter` resources `mutable`.
As a template improvement, the template author can consider making some of the
new `coder_parameter` resources `mutable`.
## Terraform template-wide variables
> ⚠️ Flag `feature_use_managed_variables` is available until v0.25.0 (Jul 2023) release. After this release, template-wide Terraform variables will be enabled by default.
> ⚠️ Flag `feature_use_managed_variables` is available until v0.25.0 (Jul 2023)
> release. After this release, template-wide Terraform variables will be enabled
> by default.
As parameters are intended to be used only for workspace customization purposes, Terraform variables can be freely managed by the template author to build templates. Workspace users are not able to modify
template variables.
As parameters are intended to be used only for workspace customization purposes,
Terraform variables can be freely managed by the template author to build
templates. Workspace users are not able to modify template variables.
The template author can enable Terraform template-wide variables mode by specifying the following flag:
The template author can enable Terraform template-wide variables mode by
specifying the following flag:
```hcl
provider "coder" {
@ -297,4 +337,5 @@ provider "coder" {
}
```
Once it's defined, coder will allow for modifying variables by using CLI and UI forms, but it will not be possible to use legacy parameters.
Once it's defined, coder will allow for modifying variables by using CLI and UI
forms, but it will not be possible to use legacy parameters.

17
docs/templates/resource-metadata.md vendored
View File

@ -1,6 +1,8 @@
# Resource Metadata
Expose key workspace information to your users via [`coder_metadata`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/metadata) resources in your template code.
Expose key workspace information to your users via
[`coder_metadata`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/metadata)
resources in your template code.
![ui](../images/metadata-ui.png)
@ -19,8 +21,8 @@ and any other Terraform resource attribute.
## Example
Expose the disk size, deployment name, and persistent
directory in a Kubernetes template with:
Expose the disk size, deployment name, and persistent directory in a Kubernetes
template with:
```hcl
resource "kubernetes_persistent_volume_claim" "root" {
@ -57,7 +59,8 @@ resource "coder_metadata" "deployment" {
## Hiding resources in the UI
Some resources don't need to be exposed in the UI; this helps keep the workspace view clean for developers. To hide a resource, use the `hide` attribute:
Some resources don't need to be exposed in the UI; this helps keep the workspace
view clean for developers. To hide a resource, use the `hide` attribute:
```hcl
resource "coder_metadata" "hide_serviceaccount" {
@ -73,7 +76,8 @@ resource "coder_metadata" "hide_serviceaccount" {
## Using custom resource icon
To use custom icons on your resources, use the `icon` attribute (must be a valid path or URL):
To use custom icons on your resources, use the `icon` attribute (must be a valid
path or URL):
```hcl
resource "coder_metadata" "resource_with_icon" {
@ -95,7 +99,8 @@ To make easier for you to customize your resource we added some built-in icons:
- Widgets `/icon/widgets.svg`
- Database `/icon/database.svg`
We also have other icons related to the IDEs. You can see all the icons [here](https://github.com/coder/coder/tree/main/site/static/icon).
We also have other icons related to the IDEs. You can see all the icons
[here](https://github.com/coder/coder/tree/main/site/static/icon).
## Agent Metadata

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

@ -1,22 +1,23 @@
# Resource Persistence
Coder templates have full control over workspace ephemerality. In a
completely ephemeral workspace, there are zero resources in the Off state. In
a completely persistent workspace, there is no difference between the Off and
On states.
Coder templates have full control over workspace ephemerality. In a completely
ephemeral workspace, there are zero resources in the Off state. In a completely
persistent workspace, there is no difference between the Off and On states.
Most workspaces fall somewhere in the middle, persisting user data
such as filesystem volumes, but deleting expensive, reproducible resources
such as compute instances.
Most workspaces fall somewhere in the middle, persisting user data such as
filesystem volumes, but deleting expensive, reproducible resources such as
compute instances.
By default, all Coder resources are persistent, but
production templates **must** employ the practices laid out in this document
to prevent accidental deletion.
By default, all Coder resources are persistent, but production templates
**must** employ the practices laid out in this document to prevent accidental
deletion.
## Disabling Persistence
The [`coder_workspace` data source](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace) exposes the `start_count = [0 | 1]` attribute that other
resources reference to become ephemeral.
The
[`coder_workspace` data source](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace)
exposes the `start_count = [0 | 1]` attribute that other resources reference to
become ephemeral.
For example:
@ -45,8 +46,8 @@ resource "docker_volume" "home_volume" {
```
Because we depend on `coder_workspace.me.owner`, if the owner changes their
username, Terraform would recreate the volume (wiping its data!) the next
time the workspace restarts.
username, Terraform would recreate the volume (wiping its data!) the next time
the workspace restarts.
Therefore, persistent resource names must only depend on immutable IDs such as:
@ -67,9 +68,12 @@ resource "docker_volume" "home_volume" {
## 🛡 Bulletproofing
Even if our persistent resource depends exclusively on static IDs, a change to
the `name` format or other attributes would cause Terraform to rebuild the resource.
the `name` format or other attributes would cause Terraform to rebuild the
resource.
Prevent Terraform from recreating the resource under any circumstance by setting the [`ignore_changes = all` directive in the `lifecycle` block](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#ignore_changes).
Prevent Terraform from recreating the resource under any circumstance by setting
the
[`ignore_changes = all` directive in the `lifecycle` block](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#ignore_changes).
```hcl
data "coder_workspace" "me" {

61
docs/workspaces.md
View File

@ -5,9 +5,10 @@ for software development.
## Create workspaces
Each Coder user has their own workspaces created from [shared templates](./templates/index.md):
Each Coder user has their own workspaces created from
[shared templates](./templates/index.md):
```console
```shell
# create a workspace from the template; specify any variables
coder create --template="<templateName>" <workspaceName>
@ -22,15 +23,17 @@ Coder [supports multiple IDEs](./ides.md) for use with your workspaces.
## Workspace lifecycle
Workspaces in Coder are started and stopped, often based on whether there was
any activity or if there was a [template update](./templates/index.md#Start/stop) available.
any activity or if there was a
[template update](./templates/index.md#Start/stop) available.
Resources are often destroyed and re-created when a workspace is restarted,
though the exact behavior depends on the template. For more
information, see [Resource Persistence](./templates/resource-persistence.md).
though the exact behavior depends on the template. For more information, see
[Resource Persistence](./templates/resource-persistence.md).
> ⚠️ To avoid data loss, refer to your template documentation for information on
> where to store files, install software, etc., so that they persist. Default
> templates are documented in [../examples/templates](https://github.com/coder/coder/tree/c6b1daabc5a7aa67bfbb6c89966d728919ba7f80/examples/templates).
> templates are documented in
> [../examples/templates](https://github.com/coder/coder/tree/c6b1daabc5a7aa67bfbb6c89966d728919ba7f80/examples/templates).
>
> You can use `coder show <workspace-name>` to see which resources are
> persistent and which are ephemeral.
@ -39,49 +42,51 @@ When a workspace is deleted, all of the workspace's resources are deleted.
## Workspace scheduling
By default, workspaces are manually turned on/off by the user. However, a schedule
can be defined on a per-workspace basis to automate the workspace start/stop.
By default, workspaces are manually turned on/off by the user. However, a
schedule can be defined on a per-workspace basis to automate the workspace
start/stop.
![Scheduling UI](./images/schedule.png)
### Autostart
The autostart feature automates the workspace build at a user-specified time
and day(s) of the week. In addition, users can select their preferred timezone.
The autostart feature automates the workspace build at a user-specified time and
day(s) of the week. In addition, users can select their preferred timezone.
![Autostart UI](./images/autostart.png)
### Autostop
The autostop feature shuts off workspaces after given number of hours in the "on"
state. If Coder detects workspace connection activity, the autostop timer is bumped up
one hour. IDE, SSH, Port Forwarding, and coder_app activity trigger this bump.
The autostop feature shuts off workspaces after given number of hours in the
"on" state. If Coder detects workspace connection activity, the autostop timer
is bumped up one hour. IDE, SSH, Port Forwarding, and coder_app activity trigger
this bump.
![autostop UI](./images/autostop.png)
### Max lifetime
Max lifetime is a template-level setting that determines the number of hours a
workspace can run before it is automatically shutdown, regardless of any
active connections. This setting ensures workspaces do not run in perpetuity
when connections are left open inadvertently.
workspace can run before it is automatically shutdown, regardless of any active
connections. This setting ensures workspaces do not run in perpetuity when
connections are left open inadvertently.
## Updating workspaces
Use the following command to update a workspace to the latest template version.
The workspace will be stopped and started:
```console
```shell
coder update <workspace-name>
```
## Repairing workspaces
Use the following command to re-enter template input
variables in an existing workspace. This command is useful when a workspace fails
to build because its state is out of sync with the template.
Use the following command to re-enter template input variables in an existing
workspace. This command is useful when a workspace fails to build because its
state is out of sync with the template.
```console
```shell
coder update <your workspace name> --always-prompt
```
@ -99,16 +104,22 @@ Coder stores macOS and Linux logs at the following locations:
## Workspace filtering
In the Coder UI, you can filter your workspaces using pre-defined filters or employing the Coder's filter query. Take a look at the following examples to understand how to use the Coder's filter query:
In the Coder UI, you can filter your workspaces using pre-defined filters or
employing the Coder's filter query. Take a look at the following examples to
understand how to use the Coder's filter query:
- To find the workspaces that you own, use the filter `owner:me`.
- To find workspaces that are currently running, use the filter `status:running`.
- To find workspaces that are currently running, use the filter
`status:running`.
The following filters are supported:
- `owner` - Represents the `username` of the owner. You can also use `me` as a convenient alias for the logged-in user.
- `owner` - Represents the `username` of the owner. You can also use `me` as a
convenient alias for the logged-in user.
- `template` - Specifies the name of the template.
- `status` - Indicates the status of the workspace. For a list of supported statuses, please refer to the [WorkspaceStatus documentation](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#WorkspaceStatus).
- `status` - Indicates the status of the workspace. For a list of supported
statuses, please refer to the
[WorkspaceStatus documentation](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#WorkspaceStatus).
---

50
dogfood/guide.md
View File

@ -1,6 +1,8 @@
# Dogfooding Guide
This guide explains how to [dogfood](https://www.techopedia.com/definition/30784/dogfooding) coder for employees at Coder.
This guide explains how to
[dogfood](https://www.techopedia.com/definition/30784/dogfooding) coder for
employees at Coder.
## How to
@ -8,17 +10,21 @@ The following explains how to do certain things related to dogfooding.
### Dogfood using Coder's Deployment
1. Go to [https://dev.coder.com/templates/coder-ts](https://dev.coder.com/templates/coder-ts)
1. Go to
[https://dev.coder.com/templates/coder-ts](https://dev.coder.com/templates/coder-ts)
1. If you don't have an account, sign in with GitHub
2. If you see a dialog/pop-up, hit "Cancel" (this is because of Rippling)
2. Create a workspace
3. [Connect with your favorite IDE](https://coder.com/docs/coder-oss/latest/ides)
4. Clone the repo: `git clone git@github.com:coder/coder.git`
5. Follow the [contributing guide](https://coder.com/docs/coder-oss/latest/CONTRIBUTING)
5. Follow the
[contributing guide](https://coder.com/docs/coder-oss/latest/CONTRIBUTING)
### Run Coder in your Coder Workspace
1. Clone the Git repo `[https://github.com/coder/coder](https://github.com/coder/coder)` and `cd` into it
1. Clone the Git repo
`[https://github.com/coder/coder](https://github.com/coder/coder)` and `cd`
into it
2. Run `sudo apt update` and then `sudo apt install -y netcat`
- skip this step if using the `coder` template
3. Run `make bin`
@ -33,7 +39,8 @@ The following explains how to do certain things related to dogfooding.
Don’t fret! This is a known issue. To get around it:
1. Add `export DB_FROM=coderdb` to your `.bashrc` (make sure you `source ~/.bashrc`)
1. Add `export DB_FROM=coderdb` to your `.bashrc` (make sure you
`source ~/.bashrc`)
2. Run `sudo service postgresql start`
3. Run `sudo -u postgres psql` (this will open the PostgreSQL CLI)
4. Run `postgres-# alter user postgres password 'postgres';`
@ -44,13 +51,23 @@ The following explains how to do certain things related to dogfooding.
</aside>
4. Run `./scripts/develop.sh` which will start _two_ separate processes:
1. `[http://localhost:3000](http://localhost:3000)` — backend API server 👈 Backend devs will want to talk to this
2. `[http://localhost:8080](http://localhost:8080)` — Node.js dev server 👈 Frontend devs will want to talk to this
5. Ensure that you’re logged in: `./scripts/coder-dev.sh list` — should return no workspace. If this returns an error, double-check the output of running `scripts/develop.sh`.
6. A template named `docker-amd64` (or `docker-arm64` if you’re on ARM) will have automatically been created for you. If you just want to create a workspace quickly, you can run `./scripts/coder-dev.sh create myworkspace -t docker-amd64` and this will get you going quickly!
7. To create your own template, you can do: `./scripts/coder-dev.sh templates init` and choose your preferred option.
For example, choosing “Develop in Docker” will create a new folder `docker` that contains the bare bones for starting a Docker workspace template.
Then, enter the folder that was just created and customize as you wish.
1. `[http://localhost:3000](http://localhost:3000)` — backend API server
👈 Backend devs will want to talk to this
2. `[http://localhost:8080](http://localhost:8080)` — Node.js dev server
👈 Frontend devs will want to talk to this
5. Ensure that you’re logged in: `./scripts/coder-dev.sh list` — should return
no workspace. If this returns an error, double-check the output of running
`scripts/develop.sh`.
6. A template named `docker-amd64` (or `docker-arm64` if you’re on ARM) will
have automatically been created for you. If you just want to create a
workspace quickly, you can run
`./scripts/coder-dev.sh create myworkspace -t docker-amd64` and this will
get you going quickly!
7. To create your own template, you can do:
`./scripts/coder-dev.sh templates init` and choose your preferred option.
For example, choosing “Develop in Docker” will create a new folder `docker`
that contains the bare bones for starting a Docker workspace template. Then,
enter the folder that was just created and customize as you wish.
<aside>
💡 **For all Docker templates:**
@ -85,11 +102,13 @@ Run 'coder create --help' for usage.
Check the output of `docker ps -a`
- If you see a container with the status `Exited` run `docker logs <container name>` and see what the issue with the container output is
- If you see a container with the status `Exited` run
`docker logs <container name>` and see what the issue with the container
output is
Enable verbose container logging for Docker:
```console
```shell
sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.orig
sudo cat > /etc/docker/daemon.json << EOF
{
@ -105,4 +124,5 @@ sudo journalctl -u docker -f
### Help! I'm still blocked
Post in the #dogfood Slack channel internally or open a Discussion on GitHub and tag @jsjoeio or @bpmct
Post in the #dogfood Slack channel internally or open a Discussion on GitHub and
tag @jsjoeio or @bpmct

2
examples/lima/README.md
View File

@ -20,7 +20,7 @@ This will:
- Start an Ubuntu 22.04 VM
- Install Docker and Terraform from the official repos
- Install Coder using the [installation script](https://coder.com/docs/coder-oss/latest/install#installsh)
- Install Coder using the [installation script](../../docs/install/install.sh.md)
- Generates an initial user account `admin@coder.com` with a randomly generated password (stored in the VM under `/home/${USER}.linux/.config/coderv2/password`)
- Initializes a [sample Docker template](https://github.com/coder/coder/tree/main/examples/templates/docker) for creating workspaces

33
examples/templates/community-templates.md
View File

@ -2,22 +2,35 @@
This is a list of templates and actions created by the community.
See [Getting Started](./README.md#getting-started) for how to use these templates.
See [Getting Started](./README.md#getting-started) for how to use these
templates.
> If you have created a template, see one that's missing or one that's no longer
> maintained, please submit a pull request to improve this list. Thank you!
## Templates
- [ntimo/coder-hetzner-cloud-template](https://github.com/ntimo/coder-hetzner-cloud-template) - Setup a Hetzner Cloud instance as dev environment with or without vscode.
- [matifali/coder-templates](https://github.com/matifali/coder-templates) - Deeplearning with Jupyter Notebook/Lab and Matlab in browser.
- [m.lan/coder-templates](https://gitlab.com/m.lan/coder-templates) - Kubernetes template with DinD.
- [jsjoeio/coder-templates](https://github.com/jsjoeio/coder-templates) - Docker templates that prompt for dotfiles and base Docker image.
- [sharkymark/v2-templates](https://github.com/sharkymark/v2-templates) - Kubernetes, Docker, AWS, Google Cloud, Azure templates, videos, emoji links, and API examples.
- [bpmct/coder-templates](https://github.com/bpmct/coder-templates) - Kubernetes, OpenStack, podman, Docker, VM, AWS, Google Cloud, Azure templates.
- [kozmiknano/vscode-server-template](https://github.com/KozmikNano/vscode-server-template) - Run the full VS Code server within docker! (Built-in settings sync and Microsoft Marketplace enabled)
- [atnomoverflow/coder-template](https://github.com/atnomoverflow/coder-template) - Kubernetes template that install VS code server Rstudio jupyter and also set ssh access to gitlab (Works also on self managed gitlab).
- [ntimo/coder-hetzner-cloud-template](https://github.com/ntimo/coder-hetzner-cloud-template) -
Setup a Hetzner Cloud instance as dev environment with or without vscode.
- [matifali/coder-templates](https://github.com/matifali/coder-templates) -
Deeplearning with Jupyter Notebook/Lab and Matlab in browser.
- [m.lan/coder-templates](https://gitlab.com/m.lan/coder-templates) - Kubernetes
template with DinD.
- [jsjoeio/coder-templates](https://github.com/jsjoeio/coder-templates) - Docker
templates that prompt for dotfiles and base Docker image.
- [sharkymark/v2-templates](https://github.com/sharkymark/v2-templates) -
Kubernetes, Docker, AWS, Google Cloud, Azure templates, videos, emoji links,
and API examples.
- [bpmct/coder-templates](https://github.com/bpmct/coder-templates) -
Kubernetes, OpenStack, podman, Docker, VM, AWS, Google Cloud, Azure templates.
- [kozmiknano/vscode-server-template](https://github.com/KozmikNano/vscode-server-template) -
Run the full VS Code server within docker! (Built-in settings sync and
Microsoft Marketplace enabled)
- [atnomoverflow/coder-template](https://github.com/atnomoverflow/coder-template) -
Kubernetes template that install VS code server Rstudio jupyter and also set
ssh access to gitlab (Works also on self managed gitlab).
## Automation
- [Update Coder Template](https://github.com/marketplace/actions/update-coder-template) - A GitHub action to automate coder template changes.
- [Update Coder Template](https://github.com/marketplace/actions/update-coder-template) -
A GitHub action to automate coder template changes.

26
examples/web-server/apache/README.md
View File

@ -4,7 +4,7 @@
1. Start a Coder deployment and be sure to set the following [configuration values](https://coder.com/docs/v2/latest/admin/configure):
```console
```env
CODER_HTTP_ADDRESS=127.0.0.1:3000
CODER_ACCESS_URL=https://coder.example.com
CODER_WILDCARD_ACCESS_URL=*coder.example.com
@ -18,13 +18,13 @@
3. Install Apache (assuming you're on Debian/Ubuntu):
```console
```shell
sudo apt install apache2
```
4. Enable the following Apache modules:
```console
```shell
sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod ssl
@ -33,7 +33,7 @@
5. Stop Apache service and disable default site:
```console
```shell
sudo a2dissite 000-default.conf
sudo systemctl stop apache2
```
@ -56,7 +56,7 @@
dns_cloudflare_api_token = YOUR_API_TOKEN
```
```console
```shell
mkdir -p ~/.secrets/certbot
touch ~/.secrets/certbot/cloudflare.ini
nano ~/.secrets/certbot/cloudflare.ini
@ -64,7 +64,7 @@
3. Set the correct permissions:
```console
```shell
sudo chmod 600 ~/.secrets/certbot/cloudflare.ini
```
@ -72,7 +72,7 @@
1. Create the wildcard certificate:
```console
```shell
sudo certbot certonly --dns-cloudflare --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini -d coder.example.com -d *.coder.example.com
```
@ -82,7 +82,7 @@
1. Create Apache configuration for Coder:
```console
```shell
sudo nano /etc/apache2/sites-available/coder.conf
```
@ -122,13 +122,13 @@
3. Enable the site:
```console
```shell
sudo a2ensite coder.conf
```
4. Restart Apache:
```console
```shell
sudo systemctl restart apache2
```
@ -136,19 +136,19 @@
1. Create a new file in `/etc/cron.weekly`:
```console
```shell
sudo touch /etc/cron.weekly/certbot
```
2. Make it executable:
```console
```shell
sudo chmod +x /etc/cron.weekly/certbot
```
3. And add this code:
```sh
```shell
#!/bin/sh
sudo certbot renew -q
```

10
examples/web-server/caddy/README.md
View File

@ -10,7 +10,7 @@ This is an example configuration of how to use Coder with [caddy](https://caddys
1. Start with our example configuration
```console
```shell
# Create a project folder
cd $HOME
mkdir coder-with-caddy
@ -30,7 +30,7 @@ This is an example configuration of how to use Coder with [caddy](https://caddys
1. Start Coder. Set `CODER_ACCESS_URL` and `CODER_WILDCARD_ACCESS_URL` to the domain you're using in your Caddyfile.
```console
```shell
export CODER_ACCESS_URL=https://coder.example.com
export CODER_WILDCARD_ACCESS_URL=*.coder.example.com
docker compose up -d # Run on startup
@ -60,19 +60,19 @@ This is an example configuration of how to use Coder with [caddy](https://caddys
If you're [keeping Caddy running](https://caddyserver.com/docs/running) via a system service:
```console
```shell
sudo systemctl restart caddy
```
Or run a standalone server:
```console
```shell
caddy run
```
6. Optionally, use [ufw](https://wiki.ubuntu.com/UncomplicatedFirewall) or another firewall to disable external traffic outside of Caddy.
```console
```shell
# Check status of UncomplicatedFirewall
sudo ufw status

28
examples/web-server/nginx/README.md
View File

@ -4,7 +4,7 @@
1. Start a Coder deployment and be sure to set the following [configuration values](https://coder.com/docs/v2/latest/admin/configure):
```console
```env
CODER_HTTP_ADDRESS=127.0.0.1:3000
CODER_ACCESS_URL=https://coder.example.com
CODER_WILDCARD_ACCESS_URL=*coder.example.com
@ -18,13 +18,13 @@
3. Install NGINX (assuming you're on Debian/Ubuntu):
```console
```shell
sudo apt install nginx
```
4. Stop NGINX service:
```console
```shell
sudo systemctl stop nginx
```
@ -34,13 +34,13 @@
1. Create NGINX configuration for this app:
```console
```shell
sudo touch /etc/nginx/sites-available/coder.example.com
```
2. Activate this file:
```console
```shell
sudo ln -s /etc/nginx/sites-available/coder.example.com /etc/nginx/sites-enabled/coder.example.com
```
@ -62,7 +62,7 @@
dns_cloudflare_api_token = YOUR_API_TOKEN
```
```console
```shell
mkdir -p ~/.secrets/certbot
touch ~/.secrets/certbot/cloudflare.ini
nano ~/.secrets/certbot/cloudflare.ini
@ -70,7 +70,7 @@
3. Set the correct permissions:
```console
```shell
sudo chmod 600 ~/.secrets/certbot/cloudflare.ini
```
@ -78,7 +78,7 @@
1. Create the wildcard certificate:
```console
```shell
sudo certbot certonly --dns-cloudflare --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini -d coder.example.com -d *.coder.example.com
```
@ -86,7 +86,7 @@
1. Edit the file with:
```console
```shell
sudo nano /etc/nginx/sites-available/coder.example.com
```
@ -129,7 +129,7 @@
3. Test the configuration:
```console
```shell
sudo nginx -t
```
@ -137,26 +137,26 @@
1. Create a new file in `/etc/cron.weekly`:
```console
```shell
sudo touch /etc/cron.weekly/certbot
```
2. Make it executable:
```console
```shell
sudo chmod +x /etc/cron.weekly/certbot
```
3. And add this code:
```sh
```shell
#!/bin/sh
sudo certbot renew -q
```
## Restart NGINX
```console
```shell
sudo systemctl restart nginx
```

4
helm/provisioner/Chart.yaml
View File

@ -1,6 +1,8 @@
apiVersion: v2
name: coder-provisioner
description: "External provisioner daemon for Coder. This is an Enterprise feature; contact sales@coder.com."
description:
"External provisioner daemon for Coder. This is an Enterprise feature; contact
sales@coder.com."
home: https://github.com/coder/coder
# version and appVersion are injected at release and will always be shown as

2
scripts/apidocgen/markdown-template/security.def
View File

@ -3,7 +3,7 @@
Long-lived tokens can be generated to perform actions on behalf of your user account:
```console
```shell
coder tokens create
```

4
scripts/apidocgen/postprocess/main.go
View File

@ -24,13 +24,13 @@ const (
Generate a token on your Coder deployment by visiting:
` + "````sh" + `
` + "````shell" + `
https://coder.example.com/settings/tokens
` + "````" + `
List your workspaces
` + "````sh" + `
` + "````shell" + `
# CLI
curl https://coder.example.com/api/v2/workspaces?q=owner:me \
-H "Coder-Session-Token: <your-token>"

10
site/.prettierrc.yaml
View File

@ -4,6 +4,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
@ -11,10 +12,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:
- ./**/*.yaml
- ./**/*.yml
options:
proseWrap: always