synced/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2025-07-09 11:45:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: restructure docs (#14421)

Browse Source 
Closes #13434 
Supersedes #14182

---------

Co-authored-by: Ethan <39577870+ethanndickson@users.noreply.github.com>
Co-authored-by: Ethan Dickson <ethan@coder.com>
Co-authored-by: Ben Potter <ben@coder.com>
Co-authored-by: Stephen Kirby <58410745+stirby@users.noreply.github.com>
Co-authored-by: Stephen Kirby <me@skirby.dev>
Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
This commit is contained in:
Muhammad Atif Ali
2024-10-05 08:52:04 -07:00
committed by GitHub
parent 288df75686
commit 419eba5fb6
298 changed files with 5009 additions and 3889 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.github/workflows/typos.toml vendored
View File

@ -22,6 +22,7 @@ pn = "pn"
EDE = "EDE"
# HELO is an SMTP command
HELO = "HELO"
LKE = "LKE"
[files]
extend-exclude = [

25
.vscode/settings.json vendored
View File

@ -6,14 +6,17 @@
"ASKPASS",
"authcheck",
"autostop",
"autoupdate",
"awsidentity",
"bodyclose",
"buildinfo",
"buildname",
"Caddyfile",
"circbuf",
"cliflag",
"cliui",
"codecov",
"codercom",
"coderd",
"coderdenttest",
"coderdtest",
@ -21,15 +24,19 @@
"contravariance",
"cronstrue",
"databasefake",
"dbcrypt",
"dbgen",
"dbmem",
"dbtype",
"DERP",
"derphttp",
"derpmap",
"devcontainers",
"devel",
"devtunnel",
"dflags",
"dogfood",
"dotfiles",
"drpc",
"drpcconn",
"drpcmux",
@ -38,18 +45,22 @@
"embeddedpostgres",
"enablements",
"enterprisemeta",
"Entra",
"errgroup",
"eventsourcemock",
"externalauth",
"Failf",
"fatih",
"filebrowser",
"Formik",
"gitauth",
"Gitea",
"gitsshkey",
"goarch",
"gographviz",
"goleak",
"gonet",
"googleclouddns",
"gossh",
"gsyslog",
"GTTY",
@ -63,9 +74,11 @@
"initialisms",
"ipnstate",
"isatty",
"jetbrains",
"Jobf",
"Keygen",
"kirsle",
"knowledgebase",
"Kubernetes",
"ldflags",
"magicsock",
@ -77,6 +90,7 @@
"namesgenerator",
"namespacing",
"netaddr",
"netcheck",
"netip",
"netmap",
"netns",
@ -93,6 +107,7 @@
"opty",
"paralleltest",
"parameterscopeid",
"portsharing",
"pqtype",
"prometheusmetrics",
"promhttp",
@ -100,6 +115,8 @@
"provisionerd",
"provisionerdserver",
"provisionersdk",
"psql",
"ptrace",
"ptty",
"ptys",
"ptytest",
@ -114,6 +131,7 @@
"Signup",
"slogtest",
"sourcemapped",
"speedtest",
"spinbutton",
"Srcs",
"stdbuf",
@ -154,13 +172,15 @@
"turnconn",
"typegen",
"typesafe",
"unauthenticate",
"unconvert",
"Untar",
"Userspace",
"untar",
"userspace",
"VMID",
"walkthrough",
"weblinks",
"webrtc",
"websockets",
"wgcfg",
"wgconfig",
"wgengine",
@ -172,6 +192,7 @@
"workspaceapps",
"workspacebuilds",
"workspacename",
"workspaceproxies",
"wsjson",
"xerrors",
"xlarge",

25
Makefile
View File

@ -495,9 +495,9 @@ gen: \
coderd/rbac/object_gen.go \
codersdk/rbacresources_gen.go \
site/src/api/rbacresourcesGenerated.ts \
docs/admin/prometheus.md \
docs/reference/cli/README.md \
docs/admin/audit-logs.md \
docs/admin/integrations/prometheus.md \
docs/reference/cli/index.md \
docs/admin/security/audit-logs.md \
coderd/apidoc/swagger.json \
.prettierignore.include \
.prettierignore \
@ -525,9 +525,9 @@ gen/mark-fresh:
coderd/rbac/object_gen.go \
codersdk/rbacresources_gen.go \
site/src/api/rbacresourcesGenerated.ts \
docs/admin/prometheus.md \
docs/reference/cli/README.md \
docs/admin/audit-logs.md \
docs/admin/integrations/prometheus.md \
docs/reference/cli/index.md \
docs/admin/security/audit-logs.md \
coderd/apidoc/swagger.json \
.prettierignore.include \
.prettierignore \
@ -638,21 +638,20 @@ codersdk/rbacresources_gen.go: scripts/rbacgen/codersdk.gotmpl scripts/rbacgen/m
site/src/api/rbacresourcesGenerated.ts: scripts/rbacgen/codersdk.gotmpl scripts/rbacgen/main.go coderd/rbac/object.go coderd/rbac/policy/policy.go
go run scripts/rbacgen/main.go typescript > "$@"
docs/admin/prometheus.md: scripts/metricsdocgen/main.go scripts/metricsdocgen/metrics
docs/admin/integrations/prometheus.md: scripts/metricsdocgen/main.go scripts/metricsdocgen/metrics
go run scripts/metricsdocgen/main.go
./scripts/pnpm_install.sh
pnpm exec prettier --write ./docs/admin/prometheus.md
pnpm exec prettier --write ./docs/admin/integrations/prometheus.md
docs/reference/cli/README.md: scripts/clidocgen/main.go examples/examples.gen.json $(GO_SRC_FILES)
docs/reference/cli/index.md: scripts/clidocgen/main.go examples/examples.gen.json $(GO_SRC_FILES)
CI=true BASE_PATH="." go run ./scripts/clidocgen
./scripts/pnpm_install.sh
pnpm exec prettier --write ./docs/reference/cli/README.md ./docs/reference/cli/*.md ./docs/manifest.json
pnpm exec prettier --write ./docs/reference/cli/index.md ./docs/reference/cli/*.md ./docs/manifest.json
docs/admin/audit-logs.md: coderd/database/querier.go scripts/auditdocgen/main.go enterprise/audit/table.go coderd/rbac/object_gen.go
docs/admin/security/audit-logs.md: coderd/database/querier.go scripts/auditdocgen/main.go enterprise/audit/table.go coderd/rbac/object_gen.go
go run scripts/auditdocgen/main.go
./scripts/pnpm_install.sh
pnpm exec prettier --write ./docs/admin/audit-logs.md
pnpm exec prettier --write ./docs/admin/security/audit-logs.md
coderd/apidoc/swagger.json: $(shell find ./scripts/apidocgen $(FIND_EXCLUSIONS) -type f) $(wildcard coderd/*.go) $(wildcard enterprise/coderd/*.go) $(wildcard codersdk/*.go) $(wildcard enterprise/wsproxy/wsproxysdk/*.go) $(DB_GEN_FILES) .swaggo docs/manifest.json coderd/rbac/object_gen.go
./scripts/apidocgen/generate.sh

3
docs/CONTRIBUTING.md
View File

@ -315,6 +315,9 @@ Breaking changes can be triggered in two ways:
### Security
> If you find a vulnerability, **DO NOT FILE AN ISSUE**. Instead, send an email
> to security@coder.com.
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

50
docs/README.md
View File

@ -1,5 +1,7 @@
# About Coder
<!-- Warning for docs contributors: The first route in manifest.json must be titled "About" for the static landing page to work correctly. -->
Coder is an open-source platform for creating and managing developer workspaces
on your preferred clouds and servers.
@ -7,7 +9,10 @@ on your preferred clouds and servers.
<img src="./images/hero-image.png">
</p>
By building on top of common development interfaces (SSH) and infrastructure tools (Terraform), Coder aims to make the process of **provisioning** and **accessing** remote workspaces approachable for organizations of various sizes and stages of cloud-native maturity.
By building on top of common development interfaces (SSH) and infrastructure
tools (Terraform), Coder aims to make the process of **provisioning** and
**accessing** remote workspaces approachable for organizations of various sizes
and stages of cloud-native maturity.
<blockquote class="warning">
<p>
@ -18,21 +23,28 @@ By building on top of common development interfaces (SSH) and infrastructure too
## How it works
Coder workspaces are represented with Terraform, but no Terraform knowledge is
required to get started. We have a database of pre-made templates built into the
product.
required to get started. We have a
[database](https://registry.coder.com/templates) of pre-made templates built
into the product.
<p align="center">
<img src="./images/providers-compute.png">
</p>
Coder workspaces don't stop at compute. You can add storage buckets, secrets, sidecars
and whatever else Terraform lets you dream up.
Coder workspaces don't stop at compute. You can add storage buckets, secrets,
sidecars and whatever else Terraform lets you dream up.
[Learn more about managing infrastructure.](./templates/index.md)
[Learn more about templates.](./admin/templates/index.md)
## IDE Support
You can use any Web IDE ([code-server](https://github.com/coder/code-server), [projector](https://github.com/JetBrains/projector-server), [Jupyter](https://jupyter.org/), etc.), [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/), [VS Code Remote](https://code.visualstudio.com/docs/remote/ssh-tutorial) or even a file sync such as [mutagen](https://mutagen.io/).
You can use any [Web IDE](./admin/templates/extending-templates/web-ides.md)
([code-server](https://github.com/coder/code-server),
[projector](https://github.com/JetBrains/projector-server),
[Jupyter](https://jupyter.org), etc.),
[JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/),
[VS Code Remote](https://code.visualstudio.com/docs/remote/ssh-tutorial) or even
a file sync such as [mutagen](https://mutagen.io/).
<p align="center">
<img src="./images/ide-icons.svg" height=72>
@ -41,11 +53,11 @@ You can use any Web IDE ([code-server](https://github.com/coder/code-server), [p
## Why remote development
Migrating from local developer machines to workspaces hosted by cloud services
is an [increasingly common solution for
developers](https://blog.alexellis.io/the-internet-is-my-computer/) and
[organizations
alike](https://slack.engineering/development-environments-at-slack). There are
several benefits, including:
is an
[increasingly common solution for developers](https://blog.alexellis.io/the-internet-is-my-computer/)
and
[organizations alike](https://slack.engineering/development-environments-at-slack).
There are several benefits, including:
- **Increased speed:** Server-grade compute speeds up operations in software
development, such as IDE loading, code compilation and building, and the
@ -80,8 +92,9 @@ layer of infrastructure control. This additional layer allows admins to:
- Enable persistent workspaces, which are like local machines, but faster and
hosted by a cloud service
Coder includes [production-ready templates](https://github.com/coder/coder/tree/c6b1daabc5a7aa67bfbb6c89966d728919ba7f80/examples/templates) for use with AWS EC2,
Azure, Google Cloud, Kubernetes, and more.
Coder includes
[production-ready templates](https://registry.coder.com/templates) for use with
AWS EC2, Azure, Google Cloud, Kubernetes, and more.
## What Coder is _not_
@ -99,10 +112,5 @@ Azure, Google Cloud, Kubernetes, and more.
- Coder is not a collaboration platform. You can use git and dedicated IDE
extensions for pull requests, code reviews, and pair programming.
- Coder is not a SaaS/fully-managed offering. You must host
Coder on a cloud service (AWS, Azure, GCP) or your private data center.
## Up next
- Learn about [Templates](./templates/index.md)
- [Install Coder](./install/index.md#install-coder)
- Coder is not a SaaS/fully-managed offering. You must host Coder on a cloud
service (AWS, Azure, GCP) or your private data center.

5
docs/admin/README.md
View File

@ -1,5 +0,0 @@
Get started with Coder administration:
<children>
This page is rendered on https://coder.com/docs/admin. Refer to the other documents in the `admin/` directory.
</children>

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

@ -1,33 +0,0 @@
# 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.
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.
## 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:
| Log Level | Module | Log message | Potential issues |
| --------- | ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------- |
| `ERROR` | `coderd` | `workspace build error` | Workspace owner is unable to start their workspace. |
| `ERROR` | `coderd.autobuild` | `workspace build error` | Autostart failed to initiate the workspace. |
| `ERROR` | `coderd.provisionerd-<name>` | | The provisioner job encounters issues importing the workspace template or building the workspace. |
| `ERROR` | `coderd.userauth` | | Authentication problems, such as the inability of the workspace user to log in. |
| `ERROR` | `coderd.prometheusmetrics` | | The metrics aggregator's queue is full, causing it to reject new metrics. |

175
docs/admin/external-auth.md
View File

@ -1,21 +1,5 @@
# External Authentication
Coder integrates with Git and OpenID Connect to automate away the need for
developers to authenticate with external services within their workspace.
## Git Providers
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/external-auth.mp4?raw=true" type="video/mp4">
Your browser does not support the video tag.
</video>
## Configuration
To add an external authentication provider, you'll need to create an OAuth
application. The following providers are supported:
@ -25,8 +9,8 @@ application. The following providers are supported:
- [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops)
- [Azure DevOps (via Entra ID)](https://learn.microsoft.com/en-us/entra/architecture/auth-oauth2)
The next step is to [configure the Coder server](./configure.md) to use the
OAuth application by setting the following environment variables:
The next step is to configure the Coder server to use the OAuth application by
setting the following environment variables:
```env
CODER_EXTERNAL_AUTH_0_ID="<USER_DEFINED_ID>"
@ -43,7 +27,7 @@ The `CODER_EXTERNAL_AUTH_0_ID` environment variable is used for internal
reference. Therefore, it can be set arbitrarily (e.g., `primary-github` for your
GitHub provider).
### GitHub
## GitHub
> If you don't require fine-grained access control, it's easier to configure a
> GitHub OAuth app!
@ -84,7 +68,7 @@ CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
```
### GitHub Enterprise
## GitHub Enterprise
GitHub Enterprise requires the following environment variables:
@ -98,7 +82,7 @@ CODER_EXTERNAL_AUTH_0_AUTH_URL="https://github.example.com/login/oauth/authorize
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token"
```
### Bitbucket Server
## Bitbucket Server
Bitbucket Server requires the following environment variables:
@ -110,7 +94,7 @@ CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxx
CODER_EXTERNAL_AUTH_0_AUTH_URL=https://bitbucket.domain.com/rest/oauth2/latest/authorize
```
### Azure DevOps
## Azure DevOps
Azure DevOps requires the following environment variables:
@ -124,7 +108,7 @@ CODER_EXTERNAL_AUTH_0_AUTH_URL="https://app.vssps.visualstudio.com/oauth2/author
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://app.vssps.visualstudio.com/oauth2/token"
```
### Azure DevOps (via Entra ID)
## Azure DevOps (via Entra ID)
Azure DevOps (via Entra ID) requires the following environment variables:
@ -138,7 +122,7 @@ CODER_EXTERNAL_AUTH_0_AUTH_URL="https://login.microsoftonline.com/<TENANT ID>/oa
> Note: Your app registration in Entra ID requires the `vso.code_write` scope
### GitLab self-managed
## GitLab self-managed
GitLab self-managed requires the following environment variables:
@ -154,7 +138,7 @@ CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://gitlab.company.org/oauth/token"
CODER_EXTERNAL_AUTH_0_REGEX=gitlab\.company\.org
```
### Gitea
## Gitea
```env
CODER_EXTERNAL_AUTH_0_ID="gitea"
@ -168,7 +152,7 @@ CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitea.com/login/oauth/authorize"
The Redirect URI for Gitea should be
https://coder.company.org/external-auth/gitea/callback
### Self-managed git providers
## Self-managed git providers
Custom authentication and token URLs should be used for self-managed Git
provider deployments.
@ -182,12 +166,12 @@ CODER_EXTERNAL_AUTH_0_REGEX=github\.company\.org
> Note: The `REGEX` variable must be set if using a custom git domain.
### JFrog Artifactory
## JFrog Artifactory
See [this](https://coder.com/docs/guides/artifactory-integration#jfrog-oauth)
guide on instructions on how to set up for JFrog Artifactory.
See [this](../admin/integrations/jfrog-artifactory.md) guide on instructions on
how to set up for JFrog Artifactory.
### Custom scopes
## Custom scopes
Optionally, you can request custom scopes:
@ -195,10 +179,11 @@ Optionally, you can request custom scopes:
CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key"
```
### Multiple External Providers (enterprise) (premium)
## Multiple External Providers (enterprise) (premium)
Multiple providers are an [Enterprise feature](https://coder.com/pricing). Below
is an example configuration with multiple providers.
Multiple providers are an Enterprise feature.
[Learn more](https://coder.com/pricing#compare-plans). Below is an example
configuration with multiple providers.
```env
# Provider 1) github.com
@ -206,7 +191,7 @@ CODER_EXTERNAL_AUTH_0_ID=primary-github
CODER_EXTERNAL_AUTH_0_TYPE=github
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
CODER_EXTERNAL_AUTH_0_REGEX=github.com/orgname
CODER_EXTERNAL_AUTH_0_REGEX=github.com/org
# Provider 2) github.example.com
CODER_EXTERNAL_AUTH_1_ID=secondary-github
@ -219,128 +204,10 @@ CODER_EXTERNAL_AUTH_1_TOKEN_URL="https://github.example.com/login/oauth/access_t
CODER_EXTERNAL_AUTH_1_VALIDATE_URL="https://github.example.com/api/v3/user"
```
To support regex matching for paths (e.g. github.com/orgname), you'll need to
add this to the
To support regex matching for paths (e.g. github.com/org), 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):
```shell
git config --global credential.useHttpPath true
```
### Kubernetes environment variables
If you deployed Coder with Kubernetes you can set the environment variables in
your `values.yaml` file:
```yaml
coder:
env:
# […]
- name: CODER_EXTERNAL_AUTH_0_ID
value: USER_DEFINED_ID
- name: CODER_EXTERNAL_AUTH_0_TYPE
value: github
- name: CODER_EXTERNAL_AUTH_0_CLIENT_ID
valueFrom:
secretKeyRef:
name: github-primary-basic-auth
key: client-id
- name: CODER_EXTERNAL_AUTH_0_CLIENT_SECRET
valueFrom:
secretKeyRef:
name: github-primary-basic-auth
key: client-secret
```
You can set the secrets by creating a `github-primary-basic-auth.yaml` file and
applying it.
```yaml
apiVersion: v1
kind: Secret
metadata:
name: github-primary-basic-auth
type: Opaque
stringData:
client-secret: xxxxxxxxx
client-id: xxxxxxxxx
```
Make sure to restart the affected pods for the change to take effect.
## 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:
![Git authentication in template](../images/admin/git-auth-template.png)
### Native git authentication will auto-refresh tokens
<blockquote class="info">
<p>
This is the preferred authentication method.
</p>
</blockquote>
By default, the coder agent will configure native `git` authentication via the
`GIT_ASKPASS` environment variable. Meaning, with no additional configuration,
external authentication will work with native `git` commands.
To check the auth token being used **from inside a running workspace**, run:
```shell
# If the exit code is non-zero, then the user is not authenticated with the
# external provider.
coder external-auth access-token <external-auth-id>
```
Note: Some IDE's override the `GIT_ASKPASS` environment variable and need to be
configured.
**VSCode**
Use the
[Coder](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote)
extension to automatically configure these settings for you!
Otherwise, you can manually configure the following settings:
- Set `git.terminalAuthentication` to `false`
- Set `git.useIntegratedAskPass` to `false`
### Hard coded tokens do not auto-refresh
If the token is required to be inserted into the workspace, for example
[GitHub cli](https://cli.github.com/), the auth token can be inserted from the
template. This token will not auto-refresh. The following example will
authenticate via GitHub and auto-clone a repo into the `~/coder` directory.
```hcl
data "coder_external_auth" "github" {
# Matches the ID of the external auth provider in Coder.
id = "github"
}
resource "coder_agent" "dev" {
os = "linux"
arch = "amd64"
dir = "~/coder"
env = {
GITHUB_TOKEN : data.coder_external_auth.github.access_token
}
startup_script = <<EOF
if [ ! -d ~/coder ]; then
git clone https://github.com/coder/coder
fi
EOF
}
```
See the
[Terraform provider documentation](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/external_auth)
for all available options.

13
docs/admin/groups.md
View File

@ -1,13 +0,0 @@
# Groups
Groups can be used with [template RBAC](./rbac.md) to give groups of users
access to specific templates. They can be defined via the Coder web UI,
[synced from your identity provider](./auth.md) or
[managed via Terraform](https://registry.terraform.io/providers/coder/coderd/latest/docs/resources/template).
![Groups](../images/groups.png)
## Enabling this feature
This feature is only available with a
[Premium or Enterprise license](https://coder.com/pricing).

18
docs/admin/index.md Normal file
View File

@ -0,0 +1,18 @@
# Administration
These guides contain information on managing the Coder control plane and
[authoring templates](./templates/index.md).
First time viewers looking to set up control plane access can start with the
[configuration guide](./setup/index.md). If you're a team lead looking to design
environments for your developers, check out our
[templates guides](./templates/index.md). If you are a developer using Coder, we
recommend the [user guides](../user-guides/index.md).
For automation and scripting workflows, see our [CLI](../reference/cli/index.md)
and [API](../reference/api/index.md) docs.
For any information not strictly contained in these sections, check out our
[Tutorials](../tutorials/index.md) and [FAQs](../tutorials/faqs.md).
<children></children>

130
docs/admin/infrastructure/architecture.md Normal file
View File

@ -0,0 +1,130 @@
# Architecture
The Coder deployment model is flexible and offers various components that
platform administrators can deploy and scale depending on their use case. This
page describes possible deployments, challenges, and risks associated with them.
<div class="tabs">
## Community Edition
![Architecture Diagram](../../images/architecture-diagram.png)
## Enterprise
![Single Region Architecture Diagram](../../images/architecture-single-region.png)
## Multi-Region Enterprise
![Multi Region Architecture Diagram](../../images/architecture-multi-region.png)
</div>
## Primary components
### 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.
It offers:
- Dashboard (UI)
- HTTP API
- Dev URLs (HTTP reverse proxy to workspaces)
- Workspace Web Applications (e.g for easy access to `code-server`)
- Agent registration
### provisionerd
_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](../provisioners.md) can be added for security or
scalability purposes.
### Workspaces
At the highest level, a workspace is a set of cloud resources. These resources
can be VMs, Kubernetes clusters, storage buckets, or whatever else Terraform
lets you dream up.
The resources that run the agent are described as _computational resources_,
while those that don't are called _peripheral resources_.
Each resource may also be _persistent_ or _ephemeral_ depending on whether
they're destroyed on workspace stop.
### 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.
It offers the following services along with much more:
- SSH
- Port forwarding
- Liveness checks
- `startup_script` automation
Templates are responsible for
[creating and running agents](../templates/extending-templates/index.md#workspace-agents)
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:
- Reducing global client latency (distribute coderd and centralize database)
- Achieving greater availability and efficiency (horizontally scale individual
services)
## Data Layer
### PostgreSQL (Recommended)
While `coderd` runs a bundled version of PostgreSQL, we recommend running an
external PostgreSQL 13+ database for production deployments.
A managed PostgreSQL database, with daily backups, is recommended:
- For AWS: Amazon RDS for PostgreSQL
- For Azure: Azure Database for PostgreSQL
- Flexible Server For GCP: Cloud SQL for PostgreSQL
Learn more about database requirements:
[Database Health](../monitoring/health-check.md#database)
### Git Providers (Recommended)
Users will likely need to pull source code and other artifacts from a git
provider. The Coder control plane and workspaces will need network connectivity
to the git provider.
- [GitHub Enterprise](../external-auth.md#github-enterprise)
- [GitLab](../external-auth.md#gitlab-self-managed)
- [BitBucket](../external-auth.md#bitbucket-server)
- [Other Providers](../external-auth.md#self-managed-git-providers)
### Artifact Manager (Optional)
Workspaces and templates can pull artifacts from an artifact manager, such as
JFrog Artifactory. This can be configured on the infrastructure level, or in
some cases within Coder:
- Tutorial: [JFrog Artifactory and Coder](../integrations/jfrog-artifactory.md)
### Container Registry (Optional)
If you prefer not to pull container images for the control plane (`coderd`,
`provisionerd`) and workspaces from public container registry (Docker Hub,
GitHub Container Registry) you can run your own container registry with Coder.
To shorten the provisioning time, it is recommended to deploy registry mirrors
in the same region as the workspace nodes.

32
docs/admin/infrastructure/index.md Normal file
View File

@ -0,0 +1,32 @@
# Infrastructure
Learn how to spin up & manage Coder infrastructure.
## Architecture
Coder is a self-hosted platform that runs on your own servers. For large
deployments, we recommend running the control plane on Kubernetes. Workspaces
can be run as VMs or Kubernetes pods. The control plane (`coderd`) runs in a
single region. However, workspace proxies, provisioners, and workspaces can run
across regions or even cloud providers for the optimal developer experience.
Learn more about Coder's
[architecture, concepts, and dependencies](./architecture.md).
## Reference Architectures
We publish [reference architectures](./validated-architectures/index.md) that
include best practices around Coder configuration, infrastructure sizing,
autoscaling, and operational readiness for different deployment sizes (e.g.
`Up to 2000 users`).
## Scale Tests
Use our [scale test utility](./scale-utility.md) that can be run on your Coder
deployment to simulate user activity and measure performance.
## Monitoring
See our dedicated [Monitoring](../monitoring/index.md) section for details
around monitoring your Coder deployment via a bundled Grafana dashboard, health
check, and/or within your own observability stack via Prometheus metrics.

19
docs/admin/scaling/scale-testing.md → docs/admin/infrastructure/scale-testing.md
View File

@ -90,11 +90,11 @@ Database:
## Available reference architectures
[Up to 1,000 users](../../architecture/1k-users.md)
[Up to 1,000 users](./validated-architectures/1k-users.md)
[Up to 2,000 users](../../architecture/2k-users.md)
[Up to 2,000 users](./validated-architectures/2k-users.md)
[Up to 3,000 users](../../architecture/3k-users.md)
[Up to 3,000 users](./validated-architectures/3k-users.md)
## Hardware recommendation
@ -113,12 +113,12 @@ on the workload size to ensure deployment stability.
#### CPU and memory usage
Enabling
[agent stats collection](../../reference/cli/server.md#--prometheus-collect-agent-stats)
[agent stats collection](../../reference/cli/index.md#--prometheus-collect-agent-stats)
(optional) may increase memory consumption.
Enabling direct connections between users and workspace agents (apps or SSH
traffic) can help prevent an increase in CPU usage. It is recommended to keep
[this option enabled](../../reference/cli/server.md#--disable-direct-connections)
[this option enabled](../../reference/cli/index.md#--disable-direct-connections)
unless there are compelling reasons to disable it.
Inactive users do not consume Coder resources.
@ -149,18 +149,19 @@ Terminal (bidirectional), and Workspace events/logs (unidirectional).
If the Coder deployment expects traffic from developers spread across the globe,
be aware that customer-facing latency might be higher because of the distance
between users and the load balancer. Fortunately, the latency can be improved
with a deployment of Coder [workspace proxies](../workspace-proxies.md).
with a deployment of Coder
[workspace proxies](../networking/workspace-proxies.md).
**Node Autoscaling**
We recommend disabling the autoscaling for `coderd` nodes. Autoscaling can cause
interruptions for user connections, see
[Autoscaling](scale-utility.md#autoscaling) for more details.
[Autoscaling](./scale-utility.md#autoscaling) for more details.
### Control plane: Workspace Proxies
When scaling [workspace proxies](../workspace-proxies.md), follow the same
guidelines as for `coderd` above:
When scaling [workspace proxies](../networking/workspace-proxies.md), follow the
same guidelines as for `coderd` above:
- `1 vCPU x 2 GB memory` for every 250 users.
- Disable autoscaling.

15
docs/admin/scaling/scale-utility.md → docs/admin/infrastructure/scale-utility.md
View File

@ -6,15 +6,15 @@ infrastructure. For scale-testing Kubernetes clusters we recommend to install
and use the dedicated Coder template,
[scaletest-runner](https://github.com/coder/coder/tree/main/scaletest/templates/scaletest-runner).
Learn more about [Coder’s architecture](../../architecture/architecture.md) and
our [scale-testing methodology](scale-testing.md).
Learn more about [Coder’s architecture](./architecture.md) and our
[scale-testing methodology](./scale-testing.md).
## Recent scale tests
> Note: the below information is for reference purposes only, and are not
> intended to be used as guidelines for infrastructure sizing. Review the
> [Reference Architectures](../../architecture/validated-arch.md#node-sizing)
> for hardware sizing recommendations.
> [Reference Architectures](./validated-architectures/index.md#node-sizing) for
> hardware sizing recommendations.
| Environment | Coder CPU | Coder RAM | Coder Replicas | Database | Users | Concurrent builds | Concurrent connections (Terminal/SSH) | Coder Version | Last tested |
| ---------------- | --------- | --------- | -------------- | ----------------- | ----- | ----------------- | ------------------------------------- | ------------- | ------------ |
@ -249,6 +249,7 @@ 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.
day-to-day use, you can leverage Coder's
[Prometheus metrics](../integrations/prometheus.md) to identify bottlenecks
during scale tests. Additionally, you can use your existing cloud monitoring
stack to measure load, view server logs, etc.

0
docs/architecture/1k-users.md → docs/admin/infrastructure/validated-architectures/1k-users.md
View File

0
docs/architecture/2k-users.md → docs/admin/infrastructure/validated-architectures/2k-users.md
View File

0
docs/architecture/3k-users.md → docs/admin/infrastructure/validated-architectures/3k-users.md
View File

78
docs/architecture/validated-arch.md → docs/admin/infrastructure/validated-architectures/index.md
View File

@ -61,18 +61,19 @@ by default.
### User
A [user](../admin/users.md) is an individual who utilizes the Coder platform to
develop, test, and deploy applications using workspaces. Users can select
A [user](../../users/index.md) is an individual who utilizes the Coder platform
to develop, test, and deploy applications using workspaces. Users can select
available templates to provision workspaces. They interact with Coder using the
web interface, the CLI tool, or directly calling API methods.
### Workspace
A [workspace](../workspaces.md) refers to an isolated development environment
where users can write, build, and run code. Workspaces are fully configurable
and can be tailored to specific project requirements, providing developers with
a consistent and efficient development environment. Workspaces can be
autostarted and autostopped, enabling efficient resource management.
A [workspace](../../../user-guides/workspace-management.md) refers to an
isolated development environment where users can write, build, and run code.
Workspaces are fully configurable and can be tailored to specific project
requirements, providing developers with a consistent and efficient development
environment. Workspaces can be autostarted and autostopped, enabling efficient
resource management.
Users can connect to workspaces using SSH or via workspace applications like
`code-server`, facilitating collaboration and remote access. Additionally,
@ -82,22 +83,24 @@ Coder templates and deployed on resources created by provisioners.
### Template
A [template](../templates/index.md) in Coder is a predefined configuration for
creating workspaces. Templates streamline the process of workspace creation by
providing pre-configured settings, tooling, and dependencies. They are built by
template administrators on top of Terraform, allowing for efficient management
of infrastructure resources. Additionally, templates can utilize Coder modules
to leverage existing features shared with other templates, enhancing flexibility
and consistency across deployments. Templates describe provisioning rules for
infrastructure resources offered by Terraform providers.
A [template](../../../admin/templates/index.md) in Coder is a predefined
configuration for creating workspaces. Templates streamline the process of
workspace creation by providing pre-configured settings, tooling, and
dependencies. They are built by template administrators on top of Terraform,
allowing for efficient management of infrastructure resources. Additionally,
templates can utilize Coder modules to leverage existing features shared with
other templates, enhancing flexibility and consistency across deployments.
Templates describe provisioning rules for infrastructure resources offered by
Terraform providers.
### Workspace Proxy
A [workspace proxy](../admin/workspace-proxies.md) serves as a relay connection
option for developers connecting to their workspace over SSH, a workspace app,
or through port forwarding. It helps reduce network latency for geo-distributed
teams by minimizing the distance network traffic needs to travel. Notably,
workspace proxies do not handle dashboard connections or API calls.
A [workspace proxy](../../../admin/networking/workspace-proxies.md) serves as a
relay connection option for developers connecting to their workspace over SSH, a
workspace app, or through port forwarding. It helps reduce network latency for
geo-distributed teams by minimizing the distance network traffic needs to
travel. Notably, workspace proxies do not handle dashboard connections or API
calls.
### Provisioner
@ -161,7 +164,7 @@ compute as users start/stop workspaces at the beginning and end of their day.
Set nodeSelectors, affinities, and tolerations in Coder templates to assign
workspaces to the given node group:
```hcl
```tf
resource "kubernetes_deployment" "coder" {
spec {
template {
@ -212,11 +215,11 @@ resource "kubernetes_deployment" "coder" {
For sizing recommendations, see the below reference architectures:
- [Up to 1,000 users](./1k-users.md)
- [Up to 1,000 users](1k-users.md)
- [Up to 2,000 users](./2k-users.md)
- [Up to 2,000 users](2k-users.md)
- [Up to 3,000 users](./3k-users.md)
- [Up to 3,000 users](3k-users.md)
### Networking
@ -297,8 +300,9 @@ considerations:
active users.
- Enable High Availability mode for database engine for large scale deployments.
If you enable [database encryption](../admin/encryption.md) in Coder, consider
allocating an additional CPU core to every `coderd` replica.
If you enable
[database encryption](../../../admin/security/database-encryption.md) in Coder,
consider allocating an additional CPU core to every `coderd` replica.
#### Resource utilization guidelines
@ -320,27 +324,25 @@ could affect workspace users experience once the platform is live.
### Helm Chart Configuration
1. Reference our [Helm chart values file](../../helm/coder/values.yaml) and
identify the required values for deployment.
1. Reference our [Helm chart values file](../../../../helm/coder/values.yaml)
and identify the required values for deployment.
1. Create a `values.yaml` and add it to your version control system.
1. Determine the necessary environment variables. Here is the
[full list of supported server environment variables](../reference/cli/server.md).
[full list of supported server environment variables](../../../reference/cli/server.md).
1. Follow our documented
[steps for installing Coder via Helm](../install/kubernetes.md).
[steps for installing Coder via Helm](../../../install/kubernetes.md).
### Template configuration
1. Establish dedicated accounts for users with the _Template Administrator_
role.
1. Maintain Coder templates using
[version control](../templates/change-management.md) and the
[coderd Terraform Provider](https://registry.terraform.io/providers/coder/coderd/latest/docs).
[version control](../../templates/managing-templates/change-management.md).
1. Consider implementing a GitOps workflow to automatically push new template
versions into Coder from git. For example, on Github, you can use the
[Update Coder Template](https://github.com/marketplace/actions/update-coder-template)
action.
[Setup Coder](https://github.com/marketplace/actions/setup-coder) action.
1. Evaluate enabling
[automatic template updates](../templates/general-settings.md#require-automatic-updates-enterprise)
[automatic template updates](../../templates/managing-templates/index.md#template-update-policies-enterprise-premium)
upon workspace startup.
### Observability
@ -352,12 +354,12 @@ could affect workspace users experience once the platform is live.
leverage pre-configured dashboards, alerts, and runbooks for monitoring
Coder. This includes integrations between Prometheus, Grafana, Loki, and
Alertmanager.
1. Review the [Prometheus response](../admin/prometheus.md) and set up alarms on
selected metrics.
1. Review the [Prometheus response](../../integrations/prometheus.md) and set up
alarms on selected metrics.
### User support
1. Incorporate [support links](../admin/appearance.md#support-links) into
1. Incorporate [support links](../../setup/appearance.md#support-links) into
internal documentation accessible from the user context menu. Ensure that
hyperlinks are valid and lead to up-to-date materials.
1. Encourage the use of `coder support bundle` to allow workspace users to

11
docs/platforms/other.md → docs/admin/integrations/index.md
View File

@ -1,13 +1,18 @@
# Other platforms
# Integrations
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 documentation](../architecture/architecture.md) for more details.
[architecture diagram](../infrastructure/architecture.md) for more details.
You can host your deployment on almost any infrastructure. To learn how, read
our [installation guides](../../install/index.md).
<children></children>
The following resources may help as you're deploying Coder.
- [Coder packages: one-click install on cloud providers](https://github.com/coder/packages)
- [Deploy Coder offline](../install/offline.md)
- [Deploy Coder offline](../../install/offline.md)
- [Supported resources (Terraform registry)](https://registry.terraform.io)
- [Writing custom templates](../templates/index.md)

0
docs/guides/island-integration.md → docs/admin/integrations/island.md
View File

11
docs/guides/artifactory-integration.md → docs/admin/integrations/jfrog-artifactory.md
View File

@ -69,7 +69,7 @@ artifactory:
<https://JFROG_URL/ui/admin/configuration/integrations/new> and select the
Application Type as the integration you created in step 1.
![JFrog Platform new integration](../images/guides/artifactory-integration/jfrog-oauth-app.png)
![JFrog Platform new integration](../../images/guides/artifactory-integration/jfrog-oauth-app.png)
3. Add a new
[external authentication](https://coder.com/docs/admin/external-auth) to
@ -94,7 +94,7 @@ CODER_EXTERNAL_AUTH_1_SCOPES="applied-permissions/user"
[JFrog-OAuth](https://registry.coder.com/modules/jfrog-oauth) module to
configure the integration.
```hcl
```tf
module "jfrog" {
source = "registry.coder.com/modules/jfrog-oauth/coder"
version = "1.0.0"
@ -129,7 +129,7 @@ To set this up, follow these steps:
store the token in a sensitive terraform variable to prevent it from being
displayed in plain text in the terraform state.
```hcl
```tf
variable "artifactory_access_token" {
type = string
sensitive = true
@ -162,7 +162,8 @@ concepts apply to all compute types.
## Offline Deployments
See the [offline deployments](../templates/modules.md#offline-installations)
See the
[offline deployments](../templates/extending-templates/modules.md#offline-installations)
section for instructions on how to use coder-modules in an offline environment
with Artifactory.
@ -172,5 +173,3 @@ with Artifactory.
[here](https://github.com/coder/coder/tree/main/examples/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.

29
docs/guides/xray-integration.md → docs/admin/integrations/jfrog-xray.md
View File

@ -26,22 +26,21 @@ using Coder's [JFrog Xray Integration](https://github.com/coder/coder-xray).
with a user that has the read
[permission](https://jfrog.com/help/r/jfrog-platform-administration-documentation/permissions)
for the repositories you want to scan.
2. Create a Coder
[token](https://coder.com/docs/cli/tokens_create#tokens-create) with a user
that has the [`owner`](https://coder.com/docs/admin/users#roles) role.
3. Create kubernetes secrets for the JFrog Xray and Coder tokens.
1. Create a Coder [token](../../reference/cli/tokens_create.md#tokens-create)
with a user that has the [`owner`](../users#roles) role.
1. Create Kubernetes secrets for the JFrog Xray and Coder tokens.
```bash
kubectl create secret generic coder-token --from-literal=coder-token='<token>'
kubectl create secret generic jfrog-token --from-literal=user='<user>' --from-literal=token='<token>'
```
```bash
kubectl create secret generic coder-token --from-literal=coder-token='<token>'
kubectl create secret generic jfrog-token --from-literal=user='<user>' --from-literal=token='<token>'
```
4. Deploy the Coder - JFrog Xray integration.
1. Deploy the Coder - JFrog Xray integration.
```bash
helm repo add coder-xray https://helm.coder.com/coder-xray
```bash
helm repo add coder-xray https://helm.coder.com/coder-xray
helm upgrade --install coder-xray coder-xray/coder-xray \
helm upgrade --install coder-xray coder-xray/coder-xray \
--namespace coder-xray \
--create-namespace \
--set namespace="<CODER_WORKSPACES_NAMESPACE>" \ # Replace with your Coder workspaces namespace
@ -49,7 +48,7 @@ helm upgrade --install coder-xray coder-xray/coder-xray \
--set coder.secretName="coder-token" \
--set artifactory.url="https://<your-artifactory-url>" \
--set artifactory.secretName="jfrog-token"
```
```
### Updating the Coder template
@ -66,6 +65,6 @@ image = "<ARTIFACTORY_URL>/<REPO>/<IMAGE>:<TAG>"
> create a
> [Docker config](https://jfrog.com/help/r/jfrog-artifactory-documentation/docker-advanced-topics)
> and use it in the `imagePullSecrets` field of the kubernetes pod. See this
> [guide](./image-pull-secret.md) for more information.
> [guide](../../tutorials/image-pull-secret.md) for more information.
![JFrog Xray Integration](../images/guides/xray-integration/example.png)
![JFrog Xray Integration](../../images/guides/xray-integration/example.png)

8
docs/platforms/kubernetes/deployment-logs.md → docs/admin/integrations/kubernetes-logs.md
View File

@ -50,19 +50,19 @@ logs:
### Normal pod deployment
![normal pod deployment](./coder-logstream-kube-logs-normal.png)
![normal pod deployment](../../images/admin/integrations/coder-logstream-kube-logs-normal.png)
### Wrong image
![Wrong image name](./coder-logstream-kube-logs-wrong-image.png)
![Wrong image name](../../images/admin/integrations/coder-logstream-kube-logs-wrong-image.png)
### Kubernetes quota exceeded
![Kubernetes quota exceeded](./coder-logstream-kube-logs-quota-exceeded.png)
![Kubernetes quota exceeded](../../images/admin/integrations/coder-logstream-kube-logs-quota-exceeded.png)
### Pod crash loop
![Pod crash loop](./coder-logstream-kube-logs-pod-crashed.png)
![Pod crash loop](../../images/admin/integrations/coder-logstream-kube-logs-pod-crashed.png)
## How it works

43
docs/platforms/kubernetes/additional-clusters.md → docs/admin/integrations/multiple-kube-clusters.md
View File

@ -5,7 +5,7 @@ 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)
![Region picker in "Create Workspace" screen](../../images/admin/integrations/kube-region-picker.png)
## Option 1) Kubernetes contexts and kubeconfig
@ -58,10 +58,11 @@ If you deployed Coder on a VM, copy the kubeconfig file to
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
From there, add
[template parameters](../templates/extending-templates/parameters.md) to allow
developers to pick their desired cluster.
```hcl
```tf
# main.tf
data "coder_parameter" "kube_context" {
@ -91,7 +92,7 @@ provider "kubernetes" {
Alternatively, you can authenticate with remote clusters with ServiceAccount
tokens. Coder can store these secrets on your behalf with
[managed Terraform variables](../../templates/variables.md).
[managed Terraform variables](../templates/extending-templates/variables.md).
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).
@ -99,16 +100,30 @@ Alternatively, these could also be fetched from Kubernetes secrets or even
This guide assumes you have a `coder-workspaces` namespace on your remote
cluster. Change the namespace accordingly.
### Create a Role and RoleBinding
### Create a ServiceAccount
Run this command against your remote cluster to create a Role and RoleBinding:
Run this command against your remote cluster to create a ServiceAccount, Role,
RoleBinding, and token:
```shell
kubectl apply -n coder-workspaces -f - <<EOF
apiVersion: v1
kind: ServiceAccount
metadata:
name: coder-v2
---
apiVersion: v1
kind: Secret
metadata:
name: coder-v2
annotations:
kubernetes.io/service-account.name: coder-v2
type: kubernetes.io/service-account-token
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: coder-workspaces
name: coder-v2
rules:
- apiGroups: ["", "apps", "networking.k8s.io"]
resources: ["persistentvolumeclaims", "pods", "deployments", "services", "secrets", "pods/exec","pods/log", "events", "networkpolicies", "serviceaccounts"]
@ -120,13 +135,13 @@ rules:
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: coder-workspaces
name: coder-v2
subjects:
- kind: ServiceAccount
name: coder
name: coder-v2
roleRef:
kind: Role
name: coder-workspaces
name: coder-v2
apiGroup: rbac.authorization.k8s.io
EOF
```
@ -134,8 +149,10 @@ EOF
The output should be similar to:
```text
role.rbac.authorization.k8s.io/coder-workspaces created
rolebinding.rbac.authorization.k8s.io/coder-workspaces created
serviceaccount/coder-v2 created
secret/coder-v2 created
role.rbac.authorization.k8s.io/coder-v2 created
rolebinding.rbac.authorization.k8s.io/coder-v2 created
```
### 2. Modify the Kubernetes template
@ -143,7 +160,7 @@ rolebinding.rbac.authorization.k8s.io/coder-workspaces created
You can start from our
[example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes).
```hcl
```tf
variable "host" {
description = "Cluster host address"
sensitive = true

23
docs/admin/integrations/opentofu.md Normal file
View File

@ -0,0 +1,23 @@
# Provisioning with OpenTofu
<!-- Keeping this in as a placeholder for supporting OpenTofu. We should fix support for custom terraform binaries ASAP. -->
> ⚠️ This guide is a work in progress. We do not officially support using custom
> Terraform binaries in your Coder deployment. To track progress on the work,
> see this related [Github Issue](https://github.com/coder/coder/issues/12009).
Coder deployments support any custom Terraform binary, including
[OpenTofu](https://opentofu.org/docs/) - an open source alternative to
Terraform.
> You can read more about OpenTofu and Hashicorp's licensing in our
> [blog post](https://coder.com/blog/hashicorp-license) on the Terraform
> licensing changes.
## Using a custom Terraform binary
You can change your deployment custom Terraform binary as long as it is in
`PATH` and is within the
[supported versions](https://github.com/coder/coder/blob/f57ce97b5aadd825ddb9a9a129bb823a3725252b/provisioner/terraform/install.go#L22-L25).
The hardcoded version check ensures compatibility with our
[example templates](https://github.com/coder/coder/tree/main/examples/templates).

4
docs/admin/prometheus.md → docs/admin/integrations/prometheus.md
View File

@ -101,7 +101,7 @@ spec:
`CODER_PROMETHEUS_COLLECT_AGENT_STATS` before they can be retrieved from the
deployment. They will always be available from the agent.
<!-- Code generated by 'make docs/admin/prometheus.md'. DO NOT EDIT -->
<!-- Code generated by 'make docs/admin/integrations/prometheus.md'. DO NOT EDIT -->
| Name | Type | Description | Labels |
| ------------------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
@ -183,4 +183,4 @@ deployment. They will always be available from the agent.
| `promhttp_metric_handler_requests_in_flight` | gauge | Current number of scrapes being served. | |
| `promhttp_metric_handler_requests_total` | counter | Total number of scrapes by HTTP status code. | `code` |
<!-- End generated by 'make docs/admin/prometheus.md'. -->
<!-- End generated by 'make docs/admin/integrations/prometheus.md'. -->

48
docs/admin/integrations/vault.md Normal file
View File

@ -0,0 +1,48 @@
# Integrating HashiCorp Vault with Coder
<div>
<a href="https://github.com/matifali" style="text-decoration: none; color: inherit;">
<span style="vertical-align:middle;">Muhammad Atif Ali</span>
<img src="https://github.com/matifali.png" width="24px" height="24px" style="vertical-align:middle; margin: 0px;"/>
</a>
</div>
August 05, 2024
---
This guide will walk you through the process of adding
[HashiCorp Vault](https://www.vaultproject.io/) integration to Coder workspaces.
Coder makes it easy to integrate HashiCorp Vault with your workspaces by
providing official terraform modules to integrate Vault with Coder. This guide
will show you how to use these modules to integrate HashiCorp Vault with Coder.
## `vault-github`
[`vault-github`](https://registry.coder.com/modules/vault-github) is a terraform
module that allows you to authenticate with Vault using a GitHub token. This
modules uses the existing GitHub [external authentication](../external-auth.md)
to get the token and authenticate with Vault.
To use this module, you need to add the following code to your terraform
configuration:
```tf
module "vault" {
source = "registry.coder.com/modules/vault-github/coder"
version = "1.0.7"
agent_id = coder_agent.example.id
vault_addr = "https://vault.example.com"
coder_github_auth_id = "my-github-auth-id"
}
```
This module will install and authenticate the `vault` CLI in your Coder
workspace.
Users then can use the `vault` CLI to interact with the vault, e.g., to het a kv
secret,
```shell
vault kv get -namespace=YOUR_NAMESPACE -mount=MOUNT_NAME SECRET_NAME
```

4
docs/licensing.md → docs/admin/licensing/index.md
View File

@ -26,13 +26,13 @@ First, ensure you have a license key
With an `Owner` account, navigate to `Deployment -> Licenses`, `Add a license`
then drag or select the license file with the `jwt` extension.
![Add License UI](./images/add-license-ui.png)
![Add License UI](../../images/add-license-ui.png)
### Coder CLI
First, ensure you have a license key
([request a trial](https://coder.com/trial)) and the
[Coder CLI](./install/index.md) installed.
[Coder CLI](../../install/cli.md) installed.
1. Save your license key to disk and make note of the path
2. Open a terminal

48
docs/admin/healthcheck.md → docs/admin/monitoring/health-check.md
View File

@ -3,16 +3,18 @@
Coder includes an operator-friendly deployment health page that provides a
number of details about the health of your Coder deployment.
![Health check in Coder Dashboard](../../images/admin/monitoring/health-check.png)
You can view it at `https://${CODER_URL}/health`, or you can alternatively view
the
[JSON response directly](../reference/api/debug.md#debug-info-deployment-health).
[JSON response directly](../../reference/api/debug.md#debug-info-deployment-health).
The deployment health page is broken up into the following sections:
## Access URL
The Access URL section shows checks related to Coder's
[access URL](./configure.md#access-url).
[access URL](../setup/index.md#access-url).
Coder will periodically send a GET request to `${CODER_ACCESS_URL}/healthz` and
validate that the response is `200 OK`. The expected response body is also the
@ -26,7 +28,7 @@ _Access URL not set_
**Problem:** no access URL has been configured.
**Solution:** configure an [access URL](./configure.md#access-url) for Coder.
**Solution:** configure an [access URL](../setup/index.md#access-url) for Coder.
### EACS02
@ -107,7 +109,7 @@ query fails.
_Database Latency High_
**Problem:** This code is returned if the median latency is higher than the
[configured threshold](../reference/cli/server.md#--health-check-threshold-database).
[configured threshold](../../reference/cli/server.md#--health-check-threshold-database).
This may not be an error as such, but is an indication of a potential issue.
**Solution:** Investigate the sizing of the configured database with regard to
@ -118,9 +120,9 @@ configured threshold to a higher value (this will not address the root cause).
> [!TIP]
>
> - You can enable
> [detailed database metrics](../reference/cli/server.md#--prometheus-collect-db-metrics)
> [detailed database metrics](../../reference/cli/server.md#--prometheus-collect-db-metrics)
> in Coder's Prometheus endpoint.
> - If you have [tracing enabled](../reference/cli/server.md#--trace), these
> - If you have [tracing enabled](../../reference/cli/server.md#--trace), these
> traces may also contain useful information regarding Coder's database
> activity.
@ -129,9 +131,9 @@ configured threshold to a higher value (this will not address the root cause).
Coder workspace agents may use
[DERP (Designated Encrypted Relay for Packets)](https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp)
to communicate with Coder. This requires connectivity to a number of configured
[DERP servers](../reference/cli/server.md#--derp-config-path) which are used to
relay traffic between Coder and workspace agents. Coder periodically queries the
health of its configured DERP servers and may return one or more of the
[DERP servers](../../reference/cli/server.md#--derp-config-path) which are used
to relay traffic between Coder and workspace agents. Coder periodically queries
the health of its configured DERP servers and may return one or more of the
following:
### EDERP01
@ -148,7 +150,7 @@ misconfigured reverse HTTP proxy. Additionally, while workspace users should
still be able to reach their workspaces, connection performance may be degraded.
> **Note:** This may also be shown if you have
> [forced websocket connections for DERP](../reference/cli/server.md#--derp-force-websockets).
> [forced websocket connections for DERP](../../reference/cli/server.md#--derp-force-websockets).
**Solution:** ensure that any proxies you use allow connection upgrade with the
`Upgrade: derp` header.
@ -181,7 +183,7 @@ to establish [direct connections](../networking/stun.md). Without at least one
working STUN server, direct connections may not be possible.
**Solution:** Ensure that the
[configured STUN severs](../reference/cli/server.md#derp-server-stun-addresses)
[configured STUN severs](../../reference/cli/server.md#--derp-server-stun-addresses)
are reachable from Coder and that UDP traffic can be sent/received on the
configured port.
@ -205,7 +207,8 @@ for long-lived connections:
- Between users interacting with Coder's Web UI (for example, the built-in
terminal, or VSCode Web),
- Between workspace agents and `coderd`,
- Between Coder [workspace proxies](../admin/workspace-proxies.md) and `coderd`.
- Between Coder [workspace proxies](../networking/workspace-proxies.md) and
`coderd`.
Any issues causing failures to establish WebSocket connections will result in
**severe** impairment of functionality for users. To validate this
@ -250,8 +253,8 @@ to write a message.
## Workspace Proxy
If you have configured [Workspace Proxies](../admin/workspace-proxies.md), Coder
will periodically query their availability and show their status here.
If you have configured [Workspace Proxies](../networking/workspace-proxies.md),
Coder will periodically query their availability and show their status here.
### EWP01
@ -292,10 +295,10 @@ be built until there is at least one provisioner daemon running.
**Solution:**
If you are using
[External Provisioner Daemons](./provisioners.md#external-provisioners), ensure
[External Provisioner Daemons](../provisioners.md#external-provisioners), ensure
that they are able to successfully connect to Coder. Otherwise, ensure
[`--provisioner-daemons`](../reference/cli/server.md#provisioner-daemons) is set
to a value greater than 0.
[`--provisioner-daemons`](../../reference/cli/server.md#--provisioner-daemons)
is set to a value greater than 0.
> Note: This may be a transient issue if you are currently in the process of
> updating your deployment.
@ -330,17 +333,6 @@ version of Coder.
> Note: This may be a transient issue if you are currently in the process of
> updating your deployment.
### EIF01
_Interface with Small MTU_
**Problem:** One or more local interfaces have MTU smaller than 1378, which is
the minimum MTU for Coder to establish direct connections without fragmentation.
**Solution:** Since IP fragmentation can be a source of performance problems, we
recommend you disable the interface when using Coder or
[disable direct connections](../../cli#--disable-direct-connections)
## EUNKNOWN
_Unknown Error_

24
docs/admin/monitoring/index.md Normal file
View File

@ -0,0 +1,24 @@
# Monitoring Coder
Learn about our the tools, techniques, and best practices to monitor Coder your
Coder deployment.
## Quick Start: Observability Helm Chart
Deploy Prometheus, Grafana, Alert Manager, and pre-built dashboards on your
Kubernetes cluster to monitor the Coder control plane, provisioners, and
workspaces.
![Grafana Dashboard](../../images/admin/monitoring/grafana-dashboard.png)
Learn how to install & read the docs on the
[Observability Helm Chart GitHub](https://github.com/coder/observability)
## Table of Contents
- [Logs](./logs.md): Learn how to access to Coder server logs, agent logs, and
even how to expose Kubernetes pod scheduling logs.
- [Metrics](./metrics.md): Learn about the valuable metrics to measure on a
Coder deployment, regardless of your monitoring stack.
- [Health Check](./health-check.md): Learn about the periodic health check and
error codes that run on Coder deployments.

59
docs/admin/monitoring/logs.md Normal file
View File

@ -0,0 +1,59 @@
# Logs
All Coder services log to standard output, which can be critical for identifying
errors and monitoring Coder's deployment health. Like any service, logs can be
captured via Splunk, Datadog, Grafana Loki, or other ingestion tools.
## `coderd` Logs
By default, the Coder server exports human-readable logs to standard output. You
can access these logs via `kubectl logs deployment/coder -n <coder-namespace>`
on Kubernetes or `journalctl -u coder` if you deployed Coder on a host
machine/VM.
- To change the log format/location, you can set
[`CODER_LOGGING_HUMAN`](../../reference/cli/server.md#--log-human) and
[`CODER_LOGGING_JSON](../../reference/cli/server.md#--log-json) server config.
options.
- To only display certain types of logs, use
the[`CODER_LOG_FILTER`](../../reference/cli/server.md#-l---log-filter) server
config.
Events such as server errors, audit logs, user activities, and SSO & OpenID
Connect logs are all captured in the `coderd` logs.
## `provisionerd` Logs
Logs for [external provisioners](../provisioners.md) are structured
[and configured](../../reference/cli/provisioner_start.md#--log-human) similarly
to `coderd` logs. Use these logs to troubleshoot and monitor the Terraform
operations behind workspaces and templates.
## Workspace Logs
The [Coder agent](../infrastructure/architecture.md#agents) inside workspaces
provides useful logs around workspace-to-server and client-to-workspace
connections. For Kubernetes workspaces, these are typically the pod logs as the
agent runs via the container entrypoint.
Agent logs are also stored in the workspace filesystem by default:
- macOS/Linux: `/tmp/coder-agent.log`
- Windows: Refer to the template code (e.g.
[azure-windows](https://github.com/coder/coder/blob/2cfadad023cb7f4f85710cff0b21ac46bdb5a845/examples/templates/azure-windows/Initialize.ps1.tftpl#L64))
to see where logs are stored.
> Note: Logs are truncated once they reach 5MB in size.
Startup script logs are also stored in the temporary directory of macOS and
Linux workspaces.
## Kubernetes Event Logs
Sometimes, a workspace may take a while to start or even fail to start due to
underlying events on the Kubernetes cluster such as a node being out of
resources or a missing image. You can install
[coder-logstream-kube](../integrations/kubernetes-logs.md) to stream Kubernetes
events to the Coder UI.
![Kubernetes logs in Coder dashboard](../../images/admin/monitoring/logstream-kube.png)

22
docs/admin/monitoring/metrics.md Normal file
View File

@ -0,0 +1,22 @@
# Deployment Metrics
Coder exposes many metrics which give insight into the current state of a live
Coder deployment. Our metrics are designed to be consumed by a
[Prometheus server](https://prometheus.io/).
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.
### Setting up metrics
To set up metrics monitoring, please read our
[Prometheus integration guide](../integrations/prometheus.md). The following
links point to relevant sections there.
- [Enable Prometheus metrics](../integrations/prometheus.md#enable-prometheus-metrics)
in the control plane
- [Enable the Prometheus endpoint in Helm](../integrations/prometheus.md#kubernetes-deployment)
(Kubernetes users only)
- [Configure Prometheus to scrape Coder metrics](../integrations/prometheus.md#prometheus-configuration)
- [See the list of available metrics](../integrations/prometheus.md#available-metrics)

19
docs/admin/notifications.md → docs/admin/monitoring/notifications/index.md
View File

@ -3,12 +3,11 @@
Notifications are sent by Coder in response to specific internal events, such as
a workspace being deleted or a user being created.
**Notifications are currently an experimental feature.**
## Enable experiment
In order to activate the notifications feature, you'll need to enable the
`notifications` experiment.
In order to activate the notifications feature on Coder v2.15.X, you'll need to
enable the `notifications` experiment. Notifications are enabled by default
starting in v2.16.0.
```bash
# Using the CLI flag
@ -74,7 +73,7 @@ flags.
Notifications can currently be delivered by either SMTP or webhook. Each message
can only be delivered to one method, and this method is configured globally with
[`CODER_NOTIFICATIONS_METHOD`](https://coder.com/docs/reference/cli/server#--notifications-method)
[`CODER_NOTIFICATIONS_METHOD`](../../../reference/cli/server.md#--notifications-method)
(default: `smtp`).
Enterprise customers can configure which method to use for each of the supported
@ -229,14 +228,14 @@ All users have the option to opt-out of any notifications. Go to **Account** ->
**Notifications** to turn notifications on or off. The delivery method for each
notification is indicated on the right hand side of this table.
![User Notification Preferences](../images/user-notification-preferences.png)
![User Notification Preferences](../../../images/admin/monitoring/notifications/user-notification-preferences.png)
## Delivery Preferences (enterprise) (premium)
Administrators can configure which delivery methods are used for each different
[event type](#event-types).
![preferences](../images/admin/notification-admin-prefs.png)
![preferences](../../../images/admin/monitoring/notifications/notification-admin-prefs.png)
You can find this page under
`https://$CODER_ACCESS_URL/deployment/notifications?tab=events`.
@ -247,10 +246,10 @@ Administrators may wish to stop _all_ notifications across the deployment. We
support a killswitch in the CLI for these cases.
To pause sending notifications, execute
[`coder notifications pause`](https://coder.com/docs/reference/cli/notifications_pause).
[`coder notifications pause`](../../../reference/cli/notifications_pause.md).
To resume sending notifications, execute
[`coder notifications resume`](https://coder.com/docs/reference/cli/notifications_resume).
[`coder notifications resume`](../../../reference/cli/notifications_resume.md).
## Troubleshooting
@ -277,7 +276,7 @@ Messages older than 7 days are deleted.
### Message States
![states](../images/admin/notification-states.png)
![states](../../../images/admin/monitoring/notifications/notification-states.png)
_A notifier here refers to a Coder replica which is responsible for dispatching
the notification. All running replicas act as notifiers to process pending

25
docs/admin/notifications/slack.md → docs/admin/monitoring/notifications/slack.md
View File

@ -17,8 +17,8 @@ consistent between Slack and their Coder login.
Before setting up Slack notifications, ensure that you have the following:
- Administrator access to the Slack platform to create apps
- Coder platform with
[notifications enabled](../notifications#enable-experiment)
- Coder platform v2.15.0 or greater with
[notifications enabled](./index.md#enable-experiment) for versions <v2.16.0
## Create Slack Application
@ -90,11 +90,9 @@ receiver.router.post("/v1/webhook", async (req, res) => {
return res.status(400).send("Error: request body is missing");
}
const { title_markdown, body_markdown } = req.body;
if (!title_markdown || !body_markdown) {
return res
.status(400)
.send('Error: missing fields: "title_markdown", or "body_markdown"');
const { title, body } = req.body;
if (!title || !body) {
return res.status(400).send('Error: missing fields: "title", or "body"');
}
const payload = req.body.payload;
@ -120,11 +118,11 @@ receiver.router.post("/v1/webhook", async (req, res) => {
blocks: [
{
type: "header",
text: { type: "mrkdwn", text: title_markdown },
text: { type: "plain_text", text: title },
},
{
type: "section",
text: { type: "mrkdwn", text: body_markdown },
text: { type: "mrkdwn", text: body },
},
],
};
@ -194,12 +192,9 @@ must respond appropriately.
## Enable Webhook Integration in Coder
To enable webhook integration in Coder, ensure the "notifications" experiment is
activated by running the following command:
```bash
export CODER_EXPERIMENTS=notifications
```
To enable webhook integration in Coder, ensure the "notifications"
[experiment is activated](./index.md#enable-experiment) (only required in
v2.15.X).
Then, define the POST webhook endpoint matching the deployed Slack bot:

19
docs/admin/notifications/teams.md → docs/admin/monitoring/notifications/teams.md
View File

@ -15,7 +15,7 @@ Before setting up Microsoft Teams notifications, ensure that you have the
following:
- Administrator access to the Teams platform
- Coder platform with notifications enabled
- Coder platform with [notifications enabled](./index.md#enable-experiment)
## Build Teams Workflow
@ -67,10 +67,10 @@ The process of setting up a Teams workflow consists of three key steps:
}
}
},
"title_markdown": {
"title": {
"type": "string"
},
"body_markdown": {
"body": {
"type": "string"
}
}
@ -108,11 +108,11 @@ The process of setting up a Teams workflow consists of three key steps:
},
{
"type": "TextBlock",
"text": "**@{replace(body('Parse_JSON')?['title_markdown'], '"', '\"')}**"
"text": "**@{replace(body('Parse_JSON')?['title'], '"', '\"')}**"
},
{
"type": "TextBlock",
"text": "@{replace(body('Parse_JSON')?['body_markdown'], '"', '\"')}",
"text": "@{replace(body('Parse_JSON')?['body'], '"', '\"')}",
"wrap": true
},
{
@ -133,12 +133,9 @@ The process of setting up a Teams workflow consists of three key steps:
## Enable Webhook Integration
To enable webhook integration in Coder, ensure the "notifications" experiment is
activated by running the following command:
```bash
export CODER_EXPERIMENTS=notifications
```
To enable webhook integration in Coder, ensure the "notifications"
[experiment is activated](./index.md#enable-experiment) (only required in
v2.15.X).
Then, define the POST webhook endpoint created by your Teams workflow:

13
docs/admin/high-availability.md → docs/admin/networking/high-availability.md
View File

@ -32,10 +32,9 @@ 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.
relay (default). If you're using [custom relays](./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.
@ -51,7 +50,7 @@ Here's an example 3-node network configuration setup:
## Kubernetes
If you installed Coder via
[our Helm Chart](../install/kubernetes.md#install-coder-with-helm), just
[our Helm Chart](../../install/kubernetes.md#4-install-coder-with-helm), just
increase `coder.replicaCount` in `values.yaml`.
If you installed Coder into Kubernetes by some other means, insert the relay URL
@ -71,5 +70,5 @@ Then, increase the number of pods.
## Up next
- [Networking](../networking/index.md)
- [Kubernetes](../install/kubernetes.md)
- [Read more on Coder's networking stack](./index.md)
- [Install on Kubernetes](../../install/kubernetes.md)

46
docs/networking/index.md → docs/admin/networking/index.md
View File

@ -17,6 +17,14 @@ user <-> workspace connections are end-to-end encrypted.
In order for clients and workspaces to be able to connect:
> **Note:** We strongly recommend that clients connect to Coder and their
> workspaces over a good quality, broadband network connection. The following
> are minimum requirements:
>
> - better than 400ms round-trip latency to the Coder server and to their
> workspace
> - better than 0.5% random packet loss
- All clients and agents must be able to establish a connection to the Coder
server (`CODER_ACCESS_URL`) over HTTP/HTTPS.
- Any reverse proxy or ingress between the Coder control plane and
@ -35,20 +43,20 @@ In order for clients to be able to establish direct connections:
> **Note:** Direct connections via the web browser are not supported. To improve
> latency for browser-based applications running inside Coder workspaces in
> regions far from the Coder control plane, consider deploying one or more
> [workspace proxies](../admin/workspace-proxies.md).
> [workspace proxies](./workspace-proxies.md).
- The client is connecting using the CLI (e.g. `coder ssh` or
`coder port-forward`). Note that the
[VSCode extension](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote)
and [JetBrains Plugin](https://plugins.jetbrains.com/plugin/19620-coder/), and
[`ssh coder.<workspace>`](../reference/cli/config-ssh.md) all utilize the CLI
to establish a workspace connection.
[`ssh coder.<workspace>`](../../reference/cli/config-ssh.md) all utilize the
CLI to establish a workspace connection.
- Either the client or workspace agent are able to discover a reachable
`ip:port` of their counterpart. If the agent and client are able to
communicate with each other using their locally assigned IP addresses, then a
direct connection can be established immediately. Otherwise, the client and
agent will contact
[the configured STUN servers](../reference/cli/server.md#derp-server-stun-addresses)
[the configured STUN servers](../../reference/cli/server.md#derp-server-stun-addresses)
to try and determine which `ip:port` can be used to communicate with their
counterpart. See [STUN and NAT](./stun.md) for more details on how this
process works.
@ -56,9 +64,9 @@ In order for clients to be able to establish direct connections:
**all ports** to each others' respective networks.
- To establish a direct connection, both agent and client use STUN. This
involves sending UDP packets outbound on `udp/3478` to the configured
[STUN server](../reference/cli/server.md#--derp-server-stun-addresses). If
either the agent or the client are unable to send and receive UDP packets to
a STUN server, then direct connections will not be possible.
[STUN server](../../reference/cli/server.md#--derp-server-stun-addresses).
If either the agent or the client are unable to send and receive UDP packets
to a STUN server, then direct connections will not be possible.
- Both agents and clients will then establish a
[WireGuard](https://www.wireguard.com/)️ tunnel and send UDP traffic on
ephemeral (high) ports. If a firewall between the client and the agent
@ -67,8 +75,8 @@ In order for clients to be able to establish direct connections:
## 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.
via [`ACCESS_URL`](../../admin/setup/index.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.
@ -111,14 +119,14 @@ for more information on how this process works.
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](../reference/cli/server.md#--derp-server-stun-addresses),
[Coder uses Google's public STUN server](../../reference/cli/server.md#--derp-server-stun-addresses),
but this can be disabled or changed for
[offline deployments](../install/offline.md).
[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).
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).
@ -165,8 +173,8 @@ $ coder server --derp-config-path derpmap.json
The dashboard (and web apps opened through the dashboard) are served from the
coder server, so they can only be geo-distributed with High Availability mode in
our Enterprise and Premium Editions.
[Reach out to Sales](https://coder.com/contact) to learn more.
our Enterprise Edition. [Reach out to Sales](https://coder.com/contact) to learn
more.
## Browser-only connections (enterprise) (premium)
@ -175,7 +183,15 @@ 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).
via the web terminal and
[web IDEs](../../user-guides/workspace-access/web-ides.md).
### Workspace Proxies (enterprise) (premium)
Workspace proxies are a Coder Enterprise feature that allows you to provide
low-latency browser experiences for geo-distributed teams.
To learn more, see [Workspace Proxies](./workspace-proxies.md).
## Up next

23
docs/networking/port-forwarding.md → docs/admin/networking/port-forwarding.md
View File

@ -49,10 +49,10 @@ For more examples, see `coder port-forward --help`.
## Dashboard
> 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.
> [wildcard access URL](../../admin/setup/index.md#wildcard-access-url). If an
> access URL is not specified, Coder will create
> [a publicly accessible URL](../../admin/setup/index.md#tunnel) to reverse
> proxy the deployment, and port forwarding will work.
>
> There is a
> [DNS limitation](https://datatracker.ietf.org/doc/html/rfc1035#section-2.3.1)
@ -67,7 +67,7 @@ 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
```tf
# node app
resource "coder_app" "node-react-app" {
agent_id = coder_agent.dev.id
@ -90,7 +90,7 @@ 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/networking/portforwarddashboard.png)
![Port forwarding from an app in the UI](../../images/networking/portforwarddashboard.png)
## Accessing workspace ports
@ -99,7 +99,7 @@ to specify an arbitrary port. Coder will also detect if apps inside the
workspace are listening on ports, and list them below the port input (this is
only supported on Windows and Linux workspace agents).
![Port forwarding in the UI](../images/networking/listeningports.png)
![Port forwarding in the UI](../../images/networking/listeningports.png)
### Sharing ports
@ -118,7 +118,7 @@ Once a port is shared at either `authenticated` or `public` levels, it will stay
pinned in the open ports UI for better accessibility regardless of whether or
not it is still accessible.
![Annotated port controls in the UI](../images/networking/annotatedports.png)
![Annotated port controls in the UI](../../images/networking/annotatedports.png)
The sharing level is limited by the maximum level enforced in the template
settings in enterprise deployments, and not restricted in OSS deployments.
@ -137,7 +137,7 @@ maximum sharing level is set to `Owner`, meaning port sharing is disabled for
end-users. OSS deployments allow all workspaces to share ports at both the
`authenticated` and `public` levels.
![Max port sharing level in the UI](../images/networking/portsharingmax.png)
![Max port sharing level in the UI](../../images/networking/portsharingmax.png)
### Configuring port protocol
@ -274,8 +274,9 @@ 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](../../user-guides/workspace-access/index.md#configure-ssh) on
your local machine. Then, use `ssh` to forward like so:
```console
ssh -L 8080:localhost:8000 coder.myworkspace

8
docs/networking/stun.md → docs/admin/networking/stun.md
View File

@ -66,7 +66,7 @@ In this example, both the client and agent are located on the network
direction, both client and agent are able to communicate directly with each
other's locally assigned IP address.
![Diagram of a workspace agent and client in the same network](../images/networking/stun1.png)
![Diagram of a workspace agent and client in the same network](../../images/networking/stun1.png)
### 2. Direct connections with one layer of NAT
@ -75,12 +75,12 @@ to each other over the public Internet. Both client and agent connect to a
configured STUN server located on the public Internet to determine the public IP
address and port on which they can be reached.
![Diagram of a workspace agent and client in separate networks](../images/networking/stun2.1.png)
![Diagram of a workspace agent and client in separate networks](../../images/networking/stun2.1.png)
They then exchange this information through Coder server, and can then
communicate directly with each other through their respective NATs.
![Diagram of a workspace agent and client in separate networks](../images/networking/stun2.2.png)
![Diagram of a workspace agent and client in separate networks](../../images/networking/stun2.2.png)
### 3. Direct connections with VPN and NAT hairpinning
@ -121,7 +121,7 @@ addresses on the corporate network from which their traffic appears to
originate. Using these internal addresses is much more likely to result in a
successful direct connection.
![Diagram of a workspace agent and client over VPN](../images/networking/stun3.png)
![Diagram of a workspace agent and client over VPN](../../images/networking/stun3.png)
## Hard NAT

0
docs/networking/troubleshooting.md → docs/admin/networking/troubleshooting.md
View File

66
docs/admin/workspace-proxies.md → docs/admin/networking/workspace-proxies.md
View File

@ -4,15 +4,16 @@ 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.
terminal and [web IDEs](../../user-guides/workspace-access/index.md#web-ides),
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.
![ProxyDiagram](../images/workspaceproxy/proxydiagram.png)
![ProxyDiagram](../../images/admin/networking/workspace-proxies/proxydiagram.png)
# Deploy a workspace proxy
@ -26,12 +27,8 @@ Workspace proxies can be used in the browser by navigating to the user
## Requirements
- The [Coder CLI](../reference/cli) must be installed and authenticated as a
user with the Owner role.
- Alternatively, the
[coderd Terraform Provider](https://registry.terraform.io/providers/coder/coderd/latest)
can be used to create and manage workspace proxies, if authenticated as a user
with the Owner role.
- The [Coder CLI](../../reference/cli/index.md) must be installed and
authenticated as a user with the Owner role.
## Step 1: Create the proxy
@ -153,8 +150,8 @@ coder wsproxy server
### Running as a system service
If you've installed Coder via a [system package](../install/index.md), you can
configure the workspace proxy by settings in
If you've installed Coder via a [system package](../../install/index.md), you
can configure the workspace proxy by settings in
`/etc/coder.d/coder-workspace-proxy.env`
To run workspace proxy as a system service on the host:
@ -202,49 +199,6 @@ FROM ghcr.io/coder/coder:latest
ENTRYPOINT ["/opt/coder", "wsproxy", "server"]
```
### Managing via Terraform
The
[coderd Terraform Provider](https://registry.terraform.io/providers/coder/coderd/latest)
can also be used to create and manage workspace proxies in the same Terraform
configuration as your deployment.
```hcl
provider "coderd" {
url = "https://coder.example.com"
token = "****"
}
resource "coderd_workspace_proxy" "sydney-wsp" {
name = "sydney-wsp"
display_name = "Australia (Sydney)"
icon = "/emojis/1f1e6-1f1fa.png"
}
resource "kubernetes_deployment" "syd_wsproxy" {
metadata { /* ... */ }
spec {
template {
metadata { /* ... */ }
spec {
container {
name = "syd-wsp"
image = "ghcr.io/coder/coder:latest"
args = ["wsproxy", "server"]
env {
name = "CODER_PROXY_SESSION_TOKEN"
value = coderd_workspace_proxy.sydney-wsp.session_token
}
/* ... */
}
/* ... */
}
}
/* ... */
}
}
```
### Selecting a proxy
Users can select a workspace proxy at the top-right of the browser-based Coder
@ -252,9 +206,9 @@ 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)
![Workspace proxy picker](../../images/admin/networking/workspace-proxies/ws-proxy-picker.png)
## Step 3: Observability
## Observability
Coder workspace proxy exports metrics via the HTTP endpoint, which can be
enabled using either the environment variable `CODER_PROMETHEUS_ENABLE` or the

18
docs/admin/provisioners.md
View File

@ -10,18 +10,20 @@ are often benefits to running external provisioner daemons:
- **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.
server. See
[Provider Authentication](../admin/templates/extending-templates/provider-authentication.md)
for more details.
- **Isolate secrets**: Keep Coder unaware of cloud secrets, manage/rotate
secrets on provisioner servers.
- **Reduce server load**: External provisioners reduce load and build queue
times from the Coder server. See
[Scaling Coder](scaling/scale-utility.md#recent-scale-tests) for more details.
[Scaling Coder](../admin/infrastructure/index.md#scale-tests) for more
details.
Each provisioner runs a single
[concurrent workspace build](scaling/scale-testing.md#control-plane-provisioner).
[concurrent workspace build](../admin/infrastructure/scale-testing.md#control-plane-provisionerd).
For example, running 30 provisioner containers will allow 30 users to start
workspaces at the same time.
@ -32,9 +34,7 @@ to learn how to start provisioners via Docker, Kubernetes, Systemd, etc.
## Authentication
The provisioner daemon must authenticate with your Coder deployment. If you have
multiple [organizations](./organizations.md), you'll need at least 1 provisioner
running for each organization.
The provisioner daemon must authenticate with your Coder deployment.
<div class="tabs">
@ -79,7 +79,7 @@ Kubernetes/Docker/etc.
A user account with the role `Template Admin` or `Owner` can start provisioners
using their user account. This may be beneficial if you are running provisioners
via [automation](./automation.md).
via [automation](../reference/index.md).
```sh
coder login https://<your-coder-url>
@ -208,7 +208,7 @@ Provisioners can broadly be categorized by scope: `organization` or `user`. The
scope of a provisioner can be specified with
[`-tag=scope=<scope>`](../reference/cli/provisioner_start.md#t---tag) when
starting the provisioner daemon. Only users with at least the
[Template Admin](../admin/users.md#roles) role or higher may create
[Template Admin](./users/index.md#roles) role or higher may create
organization-scoped provisioner daemons.
There are two exceptions:

23
docs/admin/rbac.md
View File

@ -1,23 +0,0 @@
# 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 via the Coder web UI,
[synced from your identity provider](./auth.md) or
[managed via Terraform](https://registry.terraform.io/providers/coder/coderd/latest/docs/resources/template).
![rbac](../images/template-rbac.png)
The "Everyone" group makes a template accessible to all users. This can be
removed to make a template private.
## Permissions
You can set the following permissions:
- **Admin**: Read, use, edit, push, and delete
- **View**: Read, use
## Enabling this feature
This feature is only available with an
[Enterprise or Premium license](https://coder.com/pricing).

0
docs/security/0001_user_apikeys_invalidation.md → docs/admin/security/0001_user_apikeys_invalidation.md
View File

18
docs/admin/audit-logs.md → docs/admin/security/audit-logs.md
View File

@ -6,7 +6,7 @@ Audit Logs allows **Auditors** to monitor user operations in their deployment.
We track the following resources:
<!-- Code generated by 'make docs/admin/audit-logs.md'. DO NOT EDIT -->
<!-- Code generated by 'make docs/admin/security/audit-logs.md'. DO NOT EDIT -->
| <b>Resource<b> | |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@ -30,7 +30,7 @@ We track the following resources:
| WorkspaceBuild<br><i>start, stop</i> | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>build_number</td><td>false</td></tr><tr><td>created_at</td><td>false</td></tr><tr><td>daily_cost</td><td>false</td></tr><tr><td>deadline</td><td>false</td></tr><tr><td>id</td><td>false</td></tr><tr><td>initiator_by_avatar_url</td><td>false</td></tr><tr><td>initiator_by_username</td><td>false</td></tr><tr><td>initiator_id</td><td>false</td></tr><tr><td>job_id</td><td>false</td></tr><tr><td>max_deadline</td><td>false</td></tr><tr><td>provisioner_state</td><td>false</td></tr><tr><td>reason</td><td>false</td></tr><tr><td>template_version_id</td><td>true</td></tr><tr><td>transition</td><td>false</td></tr><tr><td>updated_at</td><td>false</td></tr><tr><td>workspace_id</td><td>false</td></tr></tbody></table> |
| WorkspaceProxy<br><i></i> | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>created_at</td><td>true</td></tr><tr><td>deleted</td><td>false</td></tr><tr><td>derp_enabled</td><td>true</td></tr><tr><td>derp_only</td><td>true</td></tr><tr><td>display_name</td><td>true</td></tr><tr><td>icon</td><td>true</td></tr><tr><td>id</td><td>true</td></tr><tr><td>name</td><td>true</td></tr><tr><td>region_id</td><td>true</td></tr><tr><td>token_hashed_secret</td><td>true</td></tr><tr><td>updated_at</td><td>false</td></tr><tr><td>url</td><td>true</td></tr><tr><td>version</td><td>true</td></tr><tr><td>wildcard_hostname</td><td>true</td></tr></tbody></table> |
<!-- End generated by 'make docs/admin/audit-logs.md'. -->
<!-- End generated by 'make docs/admin/security/audit-logs.md'. -->
## Filtering logs
@ -70,15 +70,15 @@ audit trails.
Audit logs can be accessed through our REST API. You can find detailed
information about this in our
[endpoint documentation](../reference/api/audit.md#get-audit-logs).
[endpoint documentation](../../reference/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).
Example of a [JSON formatted](../reference/cli/server.md#--log-json) audit log
entry:
Example of a [JSON formatted](../../reference/cli/server.md#--log-json) audit
log entry:
```json
{
@ -113,8 +113,8 @@ entry:
}
```
Example of a [human readable](../reference/cli/server.md#--log-human) audit log
entry:
Example of a [human readable](../../reference/cli/server.md#--log-human) audit
log entry:
```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=""
@ -122,5 +122,5 @@ entry:
## Enabling this feature
This feature is only available with a
[Premium or Enterprise license](https://coder.com/pricing).
This feature is only available with an enterprise license.
[Learn more](../licensing/index.md)

22
docs/admin/encryption.md → docs/admin/security/database-encryption.md
View File

@ -7,7 +7,7 @@ preventing attackers with database access from using them to impersonate users.
## How it works
Coder allows administrators to specify
[external token encryption keys](../reference/cli/server.md#external-token-encryption-keys).
[external token encryption keys](../../reference/cli/server.md#external-token-encryption-keys).
If configured, Coder will use these keys to encrypt external user tokens before
storing them in the database. The encryption algorithm used is AES-256-GCM with
a 32-byte key length.
@ -47,7 +47,7 @@ Additional database fields may be encrypted in the future.
- Ensure you have a valid backup of your database. **Do not skip this step.** If
you are using the built-in PostgreSQL database, you can run
[`coder server postgres-builtin-url`](../reference/cli/server_postgres-builtin-url.md)
[`coder server postgres-builtin-url`](../../reference/cli/server_postgres-builtin-url.md)
to get the connection URL.
- Generate a 32-byte random key and base64-encode it. For example:
@ -90,7 +90,7 @@ if you need to rotate keys, you can perform the following procedure:
- Generate a new encryption key following the same procedure as above.
- Add the above key to the list of
[external token encryption keys](../reference/cli/server.md#--external-token-encryption-keys).
[external token encryption keys](../../reference/cli/server.md#--external-token-encryption-keys).
**The new key must appear first in the list**. For example, in the Kubernetes
secret created above:
@ -110,13 +110,13 @@ data:
encrypted with the old key(s).
- To re-encrypt all encrypted database fields with the new key, run
[`coder server dbcrypt rotate`](../reference/cli/server_dbcrypt_rotate.md).
[`coder server dbcrypt rotate`](../../reference/cli/server_dbcrypt_rotate.md).
This command will re-encrypt all tokens with the specified new encryption key.
We recommend performing this action during a maintenance window.
> Note: this command requires direct access to the database. If you are using
> the built-in PostgreSQL database, you can run
> [`coder server postgres-builtin-url`](../reference/cli/server_postgres-builtin-url.md)
> [`coder server postgres-builtin-url`](../../reference/cli/server_postgres-builtin-url.md)
> to get the connection URL.
- Once the above command completes successfully, remove the old encryption key
@ -133,7 +133,7 @@ To disable encryption, perform the following actions:
being written, which may cause the next step to fail.
- Run
[`coder server dbcrypt decrypt`](../reference/cli/server_dbcrypt_decrypt.md).
[`coder server dbcrypt decrypt`](../../reference/cli/server_dbcrypt_decrypt.md).
This command will decrypt all encrypted user tokens and revoke all active
encryption keys.
@ -143,7 +143,7 @@ To disable encryption, perform the following actions:
> to help prevent accidentally decrypting data.
- Remove all
[external token encryption keys](../reference/cli/server.md#--external-token-encryption-keys)
[external token encryption keys](../../reference/cli/server.md#--external-token-encryption-keys)
from Coder's configuration.
- Start coderd. You can now safely delete the encryption keys from your secret
@ -161,12 +161,12 @@ To delete all encrypted data from your database, perform the following actions:
being written.
- Run
[`coder server dbcrypt delete`](../reference/cli/server_dbcrypt_delete.md).
[`coder server dbcrypt delete`](../../reference/cli/server_dbcrypt_delete.md).
This command will delete all encrypted user tokens and revoke all active
encryption keys.
- Remove all
[external token encryption keys](../reference/cli/server.md#--external-token-encryption-keys)
[external token encryption keys](../../reference/cli/server.md#--external-token-encryption-keys)
from Coder's configuration.
- Start coderd. You can now safely delete the encryption keys from your secret
@ -175,11 +175,11 @@ To delete all encrypted data from your database, perform the following actions:
## Troubleshooting
- If Coder detects that the data stored in the database was not encrypted with
any known keys, it will refuse to start. If you are seeing this behaviour,
any known keys, it will refuse to start. If you are seeing this behavior,
ensure that the encryption keys provided are correct.
- If Coder detects that the data stored in the database was encrypted with a key
that is no longer active, it will refuse to start. If you are seeing this
behaviour, ensure that the encryption keys provided are correct and that you
behavior, ensure that the encryption keys provided are correct and that you
have not revoked any keys that are still in use.
- Decryption may fail if newly encrypted data is written while decryption is in
progress. If this happens, ensure that all active coder instances are stopped,

4
docs/security/index.md → docs/admin/security/index.md
View File

@ -16,5 +16,5 @@ vulnerability.
---
| Description | Severity | Fix | Vulnerable Versions |
| ---------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------- | ------------------- |
| [API tokens of deleted users not invalidated](./0001_user_apikeys_invalidation.md) | HIGH | [v0.23.0](https://github.com/coder/coder/releases/tag/v0.23.0) | v0.8.25 - v0.22.2 |
| --------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------- | ------------------- |
| [API tokens of deleted users not invalidated](https://github.com/coder/coder/blob/main/docs/security/0001_user_apikeys_invalidation.md) | HIGH | [v0.23.0](https://github.com/coder/coder/releases/tag/v0.23.0) | v0.8.25 - v0.22.2 |

31
docs/secrets.md → docs/admin/security/secrets.md
View File

@ -19,9 +19,10 @@ Often, this workflow is simply:
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/extending-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
@ -32,7 +33,7 @@ environment variable.
Users can view their public key in their account settings:
![SSH keys in account settings](./images/ssh-keys.png)
![SSH keys in account settings](../../images/ssh-keys.png)
> Note: SSH keys are never stored in Coder workspaces, and are fetched only when
> SSH is invoked. The keys are held in-memory and never written to disk.
@ -49,7 +50,7 @@ which excludes obscure API providers.
Dynamic secrets can be implemented in your template code like so:
```hcl
```tf
resource "twilio_iam_api_key" "api_key" {
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
friendly_name = "Test API Key"
@ -76,11 +77,11 @@ 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).
![secret UI](./images/secret-metadata-ui.png)
![Secrets UI](../../images/admin/secret-metadata.PNG)
Can be produced with
```hcl
```tf
resource "twilio_iam_api_key" "api_key" {
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
friendly_name = "Test API Key"
@ -90,9 +91,23 @@ resource "twilio_iam_api_key" "api_key" {
resource "coder_metadata" "twilio_key" {
resource_id = twilio_iam_api_key.api_key.id
item {
key = "secret"
key = "Username"
value = "Administrator"
}
item {
key = "Password"
value = twilio_iam_api_key.api_key.secret
sensitive = true
}
}
```
## Secrets Management
For more advanced secrets management, you can use a secrets management tool to
store and retrieve secrets in your workspace. For example, you can use
[HashiCorp Vault](https://www.vaultproject.io/) to inject secrets into your
workspace.
Refer to our [HashiCorp Vault Integration](../integrations/vault.md) guide for
more information on how to integrate HashiCorp Vault with Coder.

18
docs/admin/appearance.md → docs/admin/setup/appearance.md
View File

@ -6,7 +6,7 @@ requirements.
You can access the Appearance settings by navigating to
`Deployment > Appearance`.
![application name and logo url](../images/admin/application-name-logo-url.png)
![application name and logo url](../../images/admin/setup/appearance/application-name-logo-url.png)
## Application Name
@ -20,7 +20,7 @@ page and in the top left corner of the dashboard. The default is the Coder logo.
## Announcement Banners
![service banner](../images/admin/announcement_banner_settings.png)
![announcement banner](../../images/admin/setup/appearance/announcement_banner_settings.png)
Announcement Banners let admins post important messages to all site users. Only
Site Owners may set the announcement banners.
@ -28,17 +28,17 @@ Site Owners may set the announcement banners.
Example: Use multiple announcement banners for concurrent deployment-wide
updates, such as maintenance or new feature rollout.
![Multiple announcements](../images/admin/multiple-banners.PNG)
![Multiple announcements](../../images/admin/setup/appearance/multiple-banners.PNG)
Example: Adhere to government network classification requirements and notify
users of which network their Coder deployment is on.
![service banner secret](../images/admin/service-banner-secret.png)
![service banner secret](../../images/admin/setup/appearance/service-banner-secret.png)
## OIDC Login Button Customization
[Use environment variables to customize](./auth.md#oidc-login-customization) the
text and icon on the OIDC button on the Sign In page.
[Use environment variables to customize](../users/oidc-auth.md#oidc-login-customization)
the text and icon on the OIDC button on the Sign In page.
## Support Links
@ -47,13 +47,13 @@ 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)
![support links](../../images/admin/setup/appearance/support-links.png)
### Icons
The link icons are optional, and can be set to any url or
[builtin icon](../templates/icons.md#bundled-icons), additionally `bug`, `chat`,
and `docs` are available as three special icons.
[builtin icon](../templates/extending-templates/icons.md#bundled-icons),
additionally `bug`, `chat`, and `docs` are available as three special icons.
### Configuration

84
docs/admin/configure.md → docs/admin/setup/index.md
View File

@ -1,6 +1,8 @@
# Configure Control Plane Access
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](../reference/cli/server.md).
[CLI documentation](../../reference/cli/server.md).
## Access URL
@ -39,9 +41,8 @@ coder server
`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`).
or running [coder_apps](../templates/index.md) 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
@ -49,8 +50,8 @@ If you are providing TLS certificates directly to the Coder server, either
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`](../reference/cli/server.md#--tls-cert-file) and
[`--tls-key-file`](../reference/cli/server.md#--tls-key-file) command line
[`--tls-cert-file`](../../reference/cli/server.md#--tls-cert-file) and
[`--tls-key-file`](../../reference/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).
@ -60,9 +61,9 @@ 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)
- [NGINX](https://github.com/coder/coder/tree/main/examples/web-server/nginx)
- [Apache](./web-server/apache/index.md)
- [Caddy](./web-server/caddy/index.md)
- [NGINX](./web-server/nginx/index.md)
### Kubernetes TLS configuration
@ -129,63 +130,24 @@ steps:
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/index.md), you can
configure the server by setting the following variables in
`/etc/coder.d/coder.env`:
```env
# String. Specifies the external URL (HTTP/S) to access Coder.
CODER_ACCESS_URL=https://coder.example.com
# String. Address to serve the API and dashboard.
CODER_HTTP_ADDRESS=0.0.0.0:3000
# String. The URL of a PostgreSQL database to connect to. If empty, PostgreSQL binaries
# will be downloaded from Maven (https://repo1.maven.org/maven2) and store all
# data in the config root. Access the built-in database with "coder server postgres-builtin-url".
CODER_PG_CONNECTION_URL=
# Boolean. Specifies if TLS will be enabled.
CODER_TLS_ENABLE=
# If CODER_TLS_ENABLE=true, also set:
CODER_TLS_ADDRESS=0.0.0.0:3443
# String. Specifies the path to the certificate for TLS. It requires a PEM-encoded file.
# To configure the listener to use a CA certificate, concatenate the primary
# certificate and the CA certificate together. The primary certificate should
# appear first in the combined file.
CODER_TLS_CERT_FILE=
# String. Specifies the path to the private key for the certificate. It requires a
# PEM-encoded file.
CODER_TLS_KEY_FILE=
```
To run Coder as a system service on the host:
```shell
# Use systemd to start Coder now and on reboot
sudo systemctl enable --now coder
# View the logs to ensure a successful start
journalctl -u coder.service -b
```
To restart Coder after applying system changes:
```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.
## External Authentication
Coder supports external authentication via OAuth2.0. This allows enabling
integrations with git providers, such as GitHub, GitLab, and Bitbucket etc.
External authentication can also be used to integrate with external services
like JFrog Artifactory and others.
Please refer to the [external authentication](../external-auth.md) section for
more information.
## Up Next
- [Learn how to upgrade Coder](./upgrade.md).
- [Learn how to setup and manage templates](../templates/index.md)
- [Setup external provisioners](../provisioners.md)

0
docs/admin/telemetry.md → docs/admin/setup/telemetry.md
View File

0
examples/web-server/apache/coder.conf → docs/admin/setup/web-server/apache/coder.conf
View File

36
examples/web-server/apache/README.md → docs/admin/setup/web-server/apache/index.md
View File

@ -2,7 +2,8 @@
## Requirements
1. Start a Coder deployment and be sure to set the following [configuration values](https://coder.com/docs/admin/configure):
1. Start a Coder deployment and be sure to set the following
[configuration values](../../index.md):
```env
CODER_HTTP_ADDRESS=127.0.0.1:3000
@ -10,11 +11,16 @@
CODER_WILDCARD_ACCESS_URL=*coder.example.com
```
Throughout the guide, be sure to replace `coder.example.com` with the domain you intend to use with Coder.
Throughout the guide, be sure to replace `coder.example.com` with the domain
you intend to use with Coder.
2. Configure your DNS provider to point your coder.example.com and \*.coder.example.com to your server's public IP address.
2. Configure your DNS provider to point your coder.example.com and
\*.coder.example.com to your server's public IP address.
> For example, to use `coder.example.com` as your subdomain, configure `coder.example.com` and `*.coder.example.com` to point to your server's public ip. This can be done by adding A records in your DNS provider's dashboard.
> For example, to use `coder.example.com` as your subdomain, configure
> `coder.example.com` and `*.coder.example.com` to point to your server's
> public ip. This can be done by adding A records in your DNS provider's
> dashboard.
3. Install Apache (assuming you're on Debian/Ubuntu):
@ -40,17 +46,25 @@
## Install and configure LetsEncrypt Certbot
1. Install LetsEncrypt Certbot: Refer to the [CertBot documentation](https://certbot.eff.org/instructions?ws=apache&os=ubuntufocal&tab=wildcard). Be sure to pick the wildcard tab and select your DNS provider for instructions to install the necessary DNS plugin.
1. Install LetsEncrypt Certbot: Refer to the
[CertBot documentation](https://certbot.eff.org/instructions?ws=apache&os=ubuntufocal&tab=wildcard).
Be sure to pick the wildcard tab and select your DNS provider for
instructions to install the necessary DNS plugin.
## Create DNS provider credentials
> This example assumes you're using CloudFlare as your DNS provider. For other providers, refer to the [CertBot documentation](https://eff-certbot.readthedocs.io/en/stable/using.html#dns-plugins).
> This example assumes you're using CloudFlare as your DNS provider. For other
> providers, refer to the
> [CertBot documentation](https://eff-certbot.readthedocs.io/en/stable/using.html#dns-plugins).
1. Create an API token for the DNS provider you're using: e.g. [CloudFlare](https://dash.cloudflare.com/profile/api-tokens) with the following permissions:
1. Create an API token for the DNS provider you're using: e.g.
[CloudFlare](https://developers.cloudflare.com/fundamentals/api/get-started/create-token)
with the following permissions:
- Zone - DNS - Edit
2. Create a file in `.secrets/certbot/cloudflare.ini` with the following content:
2. Create a file in `.secrets/certbot/cloudflare.ini` with the following
content:
```ini
dns_cloudflare_api_token = YOUR_API_TOKEN
@ -78,7 +92,8 @@
## Configure Apache
> This example assumes Coder is running locally on `127.0.0.1:3000` and that you're using `coder.example.com` as your subdomain.
> This example assumes Coder is running locally on `127.0.0.1:3000` and that
> you're using `coder.example.com` as your subdomain.
1. Create Apache configuration for Coder:
@ -153,4 +168,5 @@
sudo certbot renew -q
```
And that's it, you should now be able to access Coder at your sub(domain) e.g. `https://coder.example.com`.
And that's it, you should now be able to access Coder at your sub(domain) e.g.
`https://coder.example.com`.

0
examples/web-server/caddy/Caddyfile → docs/admin/setup/web-server/caddy/Caddyfile
View File

0
examples/web-server/caddy/docker-compose.yaml → docs/admin/setup/web-server/caddy/docker-compose.yaml
View File

90
examples/web-server/caddy/README.md → docs/admin/setup/web-server/caddy/index.md
View File

@ -1,12 +1,15 @@
# Caddy
This is an example configuration of how to use Coder with [caddy](https://caddyserver.com/docs). To use Caddy to generate TLS certificates, you'll need a domain name that resolves to your Caddy server.
This is an example configuration of how to use Coder with
[caddy](https://caddyserver.com/docs). To use Caddy to generate TLS
certificates, you'll need a domain name that resolves to your Caddy server.
## Getting started
### With docker-compose
1. [Install Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/)
1. [Install Docker](https://docs.docker.com/engine/install/) and
[Docker Compose](https://docs.docker.com/compose/install/)
1. Start with our example configuration
@ -18,17 +21,22 @@ This is an example configuration of how to use Coder with [caddy](https://caddys
# Clone coder/coder and copy the Caddy example
git clone https://github.com/coder/coder /tmp/coder
mv /tmp/coder/examples/web-server/caddy $(pwd)
mv /tmp/coder/docs/admin/setup/web-server/caddy $(pwd)
```
1. Modify the [Caddyfile](./Caddyfile) and change the following values:
- `localhost:3000`: Change to `coder:7080` (Coder container on Docker network)
- `email@example.com`: Email to request certificates from LetsEncrypt/ZeroSSL (does not have to be Coder admin email)
- `localhost:3000`: Change to `coder:7080` (Coder container on Docker
network)
- `email@example.com`: Email to request certificates from LetsEncrypt/ZeroSSL
(does not have to be Coder admin email)
- `coder.example.com`: Domain name you're using for Coder.
- `*.coder.example.com`: Domain name for wildcard apps, commonly used for [dashboard port forwarding](https://coder.com/docs/networking/port-forwarding#dashboard). This is optional and can be removed.
- `*.coder.example.com`: Domain name for wildcard apps, commonly used for
[dashboard port forwarding](../../../networking/port-forwarding.md). This
is optional and can be removed.
1. Start Coder. Set `CODER_ACCESS_URL` and `CODER_WILDCARD_ACCESS_URL` to the domain you're using in your Caddyfile.
1. Start Coder. Set `CODER_ACCESS_URL` and `CODER_WILDCARD_ACCESS_URL` to the
domain you're using in your Caddyfile.
```shell
export CODER_ACCESS_URL=https://coder.example.com
@ -38,28 +46,35 @@ This is an example configuration of how to use Coder with [caddy](https://caddys
### Standalone
1. If you haven't already, [install Coder](https://coder.com/docs/install)
1. If you haven't already, [install Coder](../../../../install/index.md)
2. Install [Caddy Server](https://caddyserver.com/docs/install)
3. Copy our sample [Caddyfile](./Caddyfile) and change the following values:
> If you're installed Caddy as a system package, update the default Caddyfile with `vim /etc/caddy/Caddyfile`
> If you're installed Caddy as a system package, update the default Caddyfile
> with `vim /etc/caddy/Caddyfile`
- `email@example.com`: Email to request certificates from LetsEncrypt/ZeroSSL (does not have to be Coder admin email)
- `email@example.com`: Email to request certificates from LetsEncrypt/ZeroSSL
(does not have to be Coder admin email)
- `coder.example.com`: Domain name you're using for Coder.
- `*.coder.example.com`: Domain name for wildcard apps, commonly used for [dashboard port forwarding](https://coder.com/docs/networking/port-forwarding#dashboard). This is optional and can be removed.
- `localhost:3000`: Address Coder is running on. Modify this if you changed `CODER_HTTP_ADDRESS` in the Coder configuration.
- _DO NOT CHANGE the `ask http://example.com` line! Doing so will result in your certs potentially not being generated._
- `*.coder.example.com`: Domain name for wildcard apps, commonly used for
[dashboard port forwarding](../../../networking/port-forwarding.md). This
is optional and can be removed.
- `localhost:3000`: Address Coder is running on. Modify this if you changed
`CODER_HTTP_ADDRESS` in the Coder configuration.
- _DO NOT CHANGE the `ask http://example.com` line! Doing so will result in
your certs potentially not being generated._
4. [Configure Coder](https://coder.com/docs/admin/configure) and change the following values:
4. [Configure Coder](../../index.md) and change the following values:
- `CODER_ACCESS_URL`: root domain (e.g. `https://coder.example.com`)
- `CODER_WILDCARD_ACCESS_URL`: wildcard domain (e.g. `*.example.com`).
5. Start the Caddy server:
If you're [keeping Caddy running](https://caddyserver.com/docs/running) via a system service:
If you're [keeping Caddy running](https://caddyserver.com/docs/running) via a
system service:
```shell
sudo systemctl restart caddy
@ -71,7 +86,8 @@ This is an example configuration of how to use Coder with [caddy](https://caddys
caddy run
```
6. Optionally, use [ufw](https://wiki.ubuntu.com/UncomplicatedFirewall) or another firewall to disable external traffic outside of Caddy.
6. Optionally, use [ufw](https://wiki.ubuntu.com/UncomplicatedFirewall) or
another firewall to disable external traffic outside of Caddy.
```shell
# Check status of UncomplicatedFirewall
@ -91,21 +107,39 @@ This is an example configuration of how to use Coder with [caddy](https://caddys
sudo ufw enable
```
7. Navigate to your Coder URL! A TLS certificate should be auto-generated on your first visit.
7. Navigate to your Coder URL! A TLS certificate should be auto-generated on
your first visit.
## Generating wildcard certificates
By default, this configuration uses Caddy's [on-demand TLS](https://caddyserver.com/docs/caddyfile/options#on-demand-tls) to generate a certificate for each subdomain (e.g. `app1.coder.example.com`, `app2.coder.example.com`). When users visit new subdomains, such as accessing [ports on a workspace](../../../docs/networking/port-forwarding.md), the request will take an additional 5-30 seconds since a new certificate is being generated.
By default, this configuration uses Caddy's
[on-demand TLS](https://caddyserver.com/docs/caddyfile/options#on-demand-tls) to
generate a certificate for each subdomain (e.g. `app1.coder.example.com`,
`app2.coder.example.com`). When users visit new subdomains, such as accessing
[ports on a workspace](../../../networking/port-forwarding.md), the request will
take an additional 5-30 seconds since a new certificate is being generated.
For production deployments, we recommend configuring Caddy to generate a wildcard certificate, which requires an explicit DNS challenge and additional Caddy modules.
For production deployments, we recommend configuring Caddy to generate a
wildcard certificate, which requires an explicit DNS challenge and additional
Caddy modules.
1. Install a custom Caddy build that includes the [caddy-dns](https://github.com/caddy-dns) module for your DNS provider (e.g. CloudFlare, Route53).
1. Install a custom Caddy build that includes the
[caddy-dns](https://github.com/caddy-dns) module for your DNS provider (e.g.
CloudFlare, Route53).
- Docker: [Build an custom Caddy image](https://github.com/docker-library/docs/tree/master/caddy#adding-custom-caddy-modules) with the module for your DNS provider. Be sure to reference the new image in the `docker-compose.yaml`.
- Docker:
[Build an custom Caddy image](https://github.com/docker-library/docs/tree/master/caddy#adding-custom-caddy-modules)
with the module for your DNS provider. Be sure to reference the new image
in the `docker-compose.yaml`.
- Standalone: [Download a custom Caddy build](https://caddyserver.com/download) with the module for your DNS provider. If you're using Debian/Ubuntu, you [can configure the Caddy package](https://caddyserver.com/docs/build#package-support-files-for-custom-builds-for-debianubunturaspbian) to use the new build.
- Standalone:
[Download a custom Caddy build](https://caddyserver.com/download) with the
module for your DNS provider. If you're using Debian/Ubuntu, you
[can configure the Caddy package](https://caddyserver.com/docs/build#package-support-files-for-custom-builds-for-debianubunturaspbian)
to use the new build.
2. Edit your `Caddyfile` and add the necessary credentials/API tokens to solve the DNS challenge for wildcard certificates.
2. Edit your `Caddyfile` and add the necessary credentials/API tokens to solve
the DNS challenge for wildcard certificates.
For example, for AWS Route53:
@ -127,11 +161,14 @@ For production deployments, we recommend configuring Caddy to generate a wildcar
}
```
> Configuration reference from [caddy-dns/route53](https://github.com/caddy-dns/route53).
> Configuration reference from
> [caddy-dns/route53](https://github.com/caddy-dns/route53).
And for CloudFlare:
Generate a [token](https://dash.cloudflare.com/profile/api-tokens) with the following permissions:
Generate a
[token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token)
with the following permissions:
- Zone:Zone:Edit
@ -146,4 +183,5 @@ For production deployments, we recommend configuring Caddy to generate a wildcar
}
```
> Configuration reference from [caddy-dns/cloudflare](https://github.com/caddy-dns/cloudflare).
> Configuration reference from
> [caddy-dns/cloudflare](https://github.com/caddy-dns/cloudflare).

36
examples/web-server/nginx/README.md → docs/admin/setup/web-server/nginx/index.md
View File

@ -2,7 +2,8 @@
## Requirements
1. Start a Coder deployment and be sure to set the following [configuration values](https://coder.com/docs/admin/configure):
1. Start a Coder deployment and be sure to set the following
[configuration values](../../index.md):
```env
CODER_HTTP_ADDRESS=127.0.0.1:3000
@ -10,11 +11,16 @@
CODER_WILDCARD_ACCESS_URL=*.coder.example.com
```
Throughout the guide, be sure to replace `coder.example.com` with the domain you intend to use with Coder.
Throughout the guide, be sure to replace `coder.example.com` with the domain
you intend to use with Coder.
2. Configure your DNS provider to point your coder.example.com and \*.coder.example.com to your server's public IP address.
2. Configure your DNS provider to point your coder.example.com and
\*.coder.example.com to your server's public IP address.
> For example, to use `coder.example.com` as your subdomain, configure `coder.example.com` and `*.coder.example.com` to point to your server's public ip. This can be done by adding A records in your DNS provider's dashboard.
> For example, to use `coder.example.com` as your subdomain, configure
> `coder.example.com` and `*.coder.example.com` to point to your server's
> public ip. This can be done by adding A records in your DNS provider's
> dashboard.
3. Install NGINX (assuming you're on Debian/Ubuntu):
@ -30,7 +36,8 @@
## Adding Coder deployment subdomain
> This example assumes Coder is running locally on `127.0.0.1:3000` and that you're using `coder.example.com` as your subdomain.
> This example assumes Coder is running locally on `127.0.0.1:3000` and that
> you're using `coder.example.com` as your subdomain.
1. Create NGINX configuration for this app:
@ -46,17 +53,25 @@
## Install and configure LetsEncrypt Certbot
1. Install LetsEncrypt Certbot: Refer to the [CertBot documentation](https://certbot.eff.org/instructions?ws=apache&os=ubuntufocal&tab=wildcard). Be sure to pick the wildcard tab and select your DNS provider for instructions to install the necessary DNS plugin.
1. Install LetsEncrypt Certbot: Refer to the
[CertBot documentation](https://certbot.eff.org/instructions?ws=apache&os=ubuntufocal&tab=wildcard).
Be sure to pick the wildcard tab and select your DNS provider for
instructions to install the necessary DNS plugin.
## Create DNS provider credentials
> This example assumes you're using CloudFlare as your DNS provider. For other providers, refer to the [CertBot documentation](https://eff-certbot.readthedocs.io/en/stable/using.html#dns-plugins).
> This example assumes you're using CloudFlare as your DNS provider. For other
> providers, refer to the
> [CertBot documentation](https://eff-certbot.readthedocs.io/en/stable/using.html#dns-plugins).
1. Create an API token for the DNS provider you're using: e.g. [CloudFlare](https://dash.cloudflare.com/profile/api-tokens) with the following permissions:
1. Create an API token for the DNS provider you're using: e.g.
[CloudFlare](https://developers.cloudflare.com/fundamentals/api/get-started/create-token)
with the following permissions:
- Zone - DNS - Edit
2. Create a file in `.secrets/certbot/cloudflare.ini` with the following content:
2. Create a file in `.secrets/certbot/cloudflare.ini` with the following
content:
```ini
dns_cloudflare_api_token = YOUR_API_TOKEN
@ -160,4 +175,5 @@
sudo systemctl restart nginx
```
And that's it, you should now be able to access Coder at your sub(domain) e.g. `https://coder.example.com`.
And that's it, you should now be able to access Coder at your sub(domain) e.g.
`https://coder.example.com`.

164
docs/admin/templates/creating-templates.md Normal file
View File

@ -0,0 +1,164 @@
# Creating Templates
Users with the `Template Administrator` role or above can create templates
within Coder.
## From a starter template
In most cases, it is best to start with a starter template.
<div class="tabs">
### Web UI
After navigating to the Templates page in the Coder dashboard, choose
`Create Template > Choose a starter template`.
![Create a template](../../images/admin/templates/create-template.png)
From there, select a starter template for desired underlying infrastructure for
workspaces.
![Starter templates](../../images/admin/templates/starter-templates.png)
Give your template a name, description, and icon and press `Create template`.
![Name and icon](../../images/admin/templates/import-template.png)
> **⚠️ Note**: If template creation fails, Coder is likely not authorized to
> deploy infrastructure in the given location. Learn how to configure
> [provisioner authentication](#TODO).
### CLI
You can the [Coder CLI](../../install/cli.md) to manage templates for Coder.
After [logging in](#TODO) to your deployment, create a folder to store your
templates:
```sh
# This snippet applies to macOS and Linux only
mkdir $HOME/coder-templates
cd $HOME/coder-templates
```
Use the [`templates init`](../../reference/cli/templates_init.md) command to
pull a starter template:
```sh
coder templates init
```
After pulling the template to your local machine (e.g. `aws-linux`), you can
rename it:
```sh
# This snippet applies to macOS and Linux only
mv aws-linux universal-template
cd universal-template
```
Next, push it to Coder with the
[`templates push`](../../reference/cli/templates_push.md) command:
```sh
coder templates push
```
> ⚠️ Note: If `template push` fails, Coder is likely not authorized to deploy
> infrastructure in the given location. Learn how to configure
> [provisioner authentication](../provisioners.md).
You can edit the metadata of the template such as the display name with the
[`templates edit`](../../reference/cli/templates_edit.md) command:
```sh
coder templates edit universal-template \
--display-name "Universal Template" \
--description "Virtual machine configured with Java, Python, Typescript, IntelliJ IDEA, and Ruby. Use this for starter projects. " \
--icon "/emojis/2b50.png"
```
### CI/CD
Follow the [change management](./managing-templates/change-management.md) guide
to manage templates via GitOps.
</div>
## From an existing template
You can duplicate an existing template in your Coder deployment. This will copy
the template code and metadata, allowing you to make changes without affecting
the original template.
<div class="tabs">
### Web UI
After navigating to the page for a template, use the dropdown menu on the right
to `Duplicate`.
![Duplicate menu](../../images/admin/templates/duplicate-menu.png)
Give the new template a name, icon, and description.
![Duplicate page](../../images/admin/templates/duplicate-page.png)
Press `Create template`. After the build, you will be taken to the new template
page.
![New template](../../images/admin/templates/new-duplicate-template.png)
### CLI
First, ensure you are logged in to the control plane as a user with permissions
to read and write permissions.
```console
coder login
```
You can list the available templates with the following CLI invocation.
```console
coder templates list
```
After identified the template you'd like to work from, clone it into a directory
with a name you'd like to assign to the new modified template.
```console
coder templates pull <template-name> ./<new-template-name>
```
Then, you can make modifications to the existing template in this directory and
push them to the control plane using the `-d` flag to specify the directory.
```console
coder templates push <new-template-name> -d ./<new-template-name>
```
You will then see your new template in the dashboard.
</div>
## From scratch (advanced)
There may be cases where you want to create a template from scratch. You can use
[any Terraform provider](https://registry.terraform.com) with Coder to create
templates for additional clouds (e.g. Hetzner, Alibaba) or orchestrators
(VMware, Proxmox) that we do not provide example templates for.
Refer to the following resources:
- [Tutorial: Create a template from scratch](../../tutorials/template-from-scratch.md)
- [Extending templates](./extending-templates/index.md): Features and concepts
around templates (agents, parameters, variables, etc)
- [Coder Registry](https://registry.coder.com/templates): Official and community
templates for Coder
- [Coder Terraform Provider Reference](https://registry.terraform.io/providers/coder/coder)
### Next steps
- [Extending templates](./extending-templates/index.md)
- [Managing templates](./managing-templates/index.md)

12
docs/templates/agent-metadata.md → docs/admin/templates/extending-templates/agent-metadata.md
View File

@ -1,6 +1,6 @@
# Agent metadata
![agent-metadata](../images/agent-metadata.png)
![agent-metadata](../../../images/admin/templates/agent-metadata-ui.png)
You can show live operational metrics to workspace users with agent metadata. It
is the dynamic complement of [resource metadata](./resource-metadata.md).
@ -15,14 +15,14 @@ All of these examples use
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 examples use the [`coder stat`](../reference/cli/stat.md) command.
This is useful for determining CPU and memory usage of the VM or container that
the workspace is running in, which is more accurate than resource usage about
the workspace's host.
Some of the examples use the [`coder stat`](../../../reference/cli/stat.md)
command. This is useful for determining CPU and memory usage of the VM or
container that the workspace is running in, which is more accurate than resource
usage about the workspace's host.
Here's a standard set of metadata snippets for Linux agents:
```hcl
```tf
resource "coder_agent" "main" {
os = "linux"
...

12
docs/templates/docker-in-workspaces.md → docs/admin/templates/extending-templates/docker-in-workspaces.md
View File

@ -23,7 +23,7 @@ inside Coder workspaces. See [Systemd in Docker](#systemd-in-docker).
After [installing Sysbox](https://github.com/nestybox/sysbox#installation) on
the Coder host, modify your template to use the sysbox-runc runtime:
```hcl
```tf
resource "docker_container" "workspace" {
# ...
name = "coder-${data.coder_workspace.me.owner}-${lower(data.coder_workspace.me.name)}"
@ -55,7 +55,7 @@ After
modify your template to use the sysbox-runc RuntimeClass. This requires the
Kubernetes Terraform provider version 2.16.0 or greater.
```hcl
```tf
terraform {
required_providers {
coder = {
@ -175,7 +175,7 @@ $ kubectl create secret docker-registry <name> \
--docker-email=<service-account-email>
```
```hcl
```tf
env {
name = "CODER_IMAGE_PULL_SECRET"
value_from {
@ -278,7 +278,7 @@ your nodes cannot run Sysbox.
### Use a privileged sidecar container in Docker-based templates
```hcl
```tf
resource "coder_agent" "main" {
os = "linux"
arch = "amd64"
@ -315,7 +315,7 @@ resource "docker_container" "workspace" {
### Use a privileged sidecar container in Kubernetes-based templates
```hcl
```tf
terraform {
required_providers {
coder = {
@ -387,7 +387,7 @@ After
modify your template to use the sysbox-runc RuntimeClass. This requires the
Kubernetes Terraform provider version 2.16.0 or greater.
```hcl
```tf
terraform {
required_providers {
coder = {

96
docs/admin/templates/extending-templates/external-auth.md Normal file
View File

@ -0,0 +1,96 @@
# External Authentication
Coder integrates with any OpenID Connect provider to automate away the need for
developers to authenticate with external services within their workspace. This
can be used to authenticate with git providers, private registries, or any other
service that requires authentication.
## External Auth Providers
External auth providers are configured using environment variables in the Coder
Control Plane. See
## Git Providers
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/external-auth.mp4?raw=true" type="video/mp4">
Your browser does not support the video tag.
</video>
### 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:
![Git authentication in template](../../../images/admin/git-auth-template.png)
### Native git authentication will auto-refresh tokens
<blockquote class="info">
<p>
This is the preferred authentication method.
</p>
</blockquote>
By default, the coder agent will configure native `git` authentication via the
`GIT_ASKPASS` environment variable. Meaning, with no additional configuration,
external authentication will work with native `git` commands.
To check the auth token being used **from inside a running workspace**, run:
```shell
# If the exit code is non-zero, then the user is not authenticated with the
# external provider.
coder external-auth access-token <external-auth-id>
```
Note: Some IDE's override the `GIT_ASKPASS` environment variable and need to be
configured.
**VSCode**
Use the
[Coder](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote)
extension to automatically configure these settings for you!
Otherwise, you can manually configure the following settings:
- Set `git.terminalAuthentication` to `false`
- Set `git.useIntegratedAskPass` to `false`
### Hard coded tokens do not auto-refresh
If the token is required to be inserted into the workspace, for example
[GitHub cli](https://cli.github.com/), the auth token can be inserted from the
template. This token will not auto-refresh. The following example will
authenticate via GitHub and auto-clone a repo into the `~/coder` directory.
```tf
data "coder_external_auth" "github" {
# Matches the ID of the external auth provider in Coder.
id = "github"
}
resource "coder_agent" "dev" {
os = "linux"
arch = "amd64"
dir = "~/coder"
env = {
GITHUB_TOKEN : data.coder_external_auth.github.access_token
}
startup_script = <<EOF
if [ ! -d ~/coder ]; then
git clone https://github.com/coder/coder
fi
EOF
}
```
See the
[Terraform provider documentation](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/external_auth)
for all available options.

10
docs/templates/icons.md → docs/admin/templates/extending-templates/icons.md
View File

@ -1,7 +1,5 @@
# Icons
---
Coder uses icons in several places, including ones that can be configured
throughout the app, or specified in your Terraform. They're specified by a URL,
which can be to an image hosted on a CDN of your own, or one of the icons that
@ -24,7 +22,7 @@ come bundled with your Coder deployment.
These can all be configured to use an icon by setting the `icon` field.
```hcl
```tf
data "coder_parameter" "my_parameter" {
icon = "/icon/coder.svg"
@ -34,7 +32,7 @@ come bundled with your Coder deployment.
}
```
- [**Authentication Providers**](https://coder.com/docs/v2/latest/admin/external-auth):
- [**Authentication Providers**](https://coder.com/docs/admin/external-auth):
- Use icons for external authentication providers to make them recognizable.
You can set an icon for each provider by setting the
@ -46,7 +44,7 @@ come bundled with your Coder deployment.
CODER_EXTERNAL_AUTH_1_ICON=/icon/google.svg
```
- [**Support Links**](../admin/appearance.md#support-links):
- [**Support Links**](../../setup/appearance.md#support-links):
- Use icons for support links to make them recognizable. You can set the
`icon` field for each link in `CODER_SUPPORT_LINKS` array.
@ -62,7 +60,7 @@ You can also view the entire list, with search and previews, by navigating to
/icons on your Coder deployment. E.g. [https://coder.example.com/icons](#). This
can be particularly useful in airgapped deployments.
![The icon gallery](../images/icons-gallery.png)
![The icon gallery](../../../images/icons-gallery.png)
## External icons

93
docs/admin/templates/extending-templates/index.md Normal file
View File

@ -0,0 +1,93 @@
# Extending templates
There are a variety of Coder-native features to extend the configuration of your
development environments. Many of the following features are defined in your
templates using the
[Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs).
The provider docs will provide code examples for usage; alternatively, you can
view our
[example templates](https://github.com/coder/coder/tree/main/examples/templates)
to get started.
## Workspace agents
For users to connect to a workspace, the template must include a
[`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent).
The associated agent will facilitate
[workspace connections](../../../user-guides/workspace-access/index.md) via SSH,
port forwarding, and IDEs. The agent may also display real-time
[workspace metadata](./agent-metadata.md) like resource usage.
```tf
resource "coder_agent" "dev" {
os = "linux"
arch = "amd64"
dir = "/workspace"
display_apps {
vscode = true
}
}
```
You can also leverage [resource metadata](./resource-metadata.md) to display
static resource information from your template.
Templates must include some computational resource to start the agent. All
processes on the workspace are then spawned from the agent. It also provides all
information displayed in the dashboard's workspace view.
![A healthy workspace agent](../../../images/templates/healthy-workspace-agent.png)
Multiple agents may be used in a single template or even a single resource. Each
agent may have it's own apps, startup script, and metadata. This can be used to
associate multiple containers or VMs with a workspace.
## Resource persistence
The resources you define in a template may be _ephemeral_ or _persistent_.
Persistent resources stay provisioned when workspaces are stopped, where as
ephemeral resources are destroyed and recreated on restart. All resources are
destroyed when a workspace is deleted.
> You can read more about how resource behavior and workspace state in the
> [workspace lifecycle documentation](../../../user-guides/workspace-lifecycle.md).
Template resources follow the
[behavior of Terraform resources](https://developer.hashicorp.com/terraform/language/resources/behavior#how-terraform-applies-a-configuration)
and can be further configured  using the
[lifecycle argument](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle).
A common configuration is a template whose only persistent resource is the home
directory. This allows the developer to retain their work while ensuring the
rest of their environment is consistently up-to-date on each workspace restart.
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)
> and
> [ignore-changes](https://www.terraform.io/language/meta-arguments/lifecycle#ignore_changes)
> meta-arguments can be used to prevent accidental data loss.
## Coder apps
Additional IDEs, documentation, or services can be associated to your workspace
using the
[`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app)
resource.
![Coder Apps in the dashboard](../../../images/admin/templates/coder-apps-ui.png)
Note that some apps are associated to the agent by default as
[`display_apps`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#nested-schema-for-display_apps)
and can be hidden directly in the
[`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent)
resource. You can arrange the display orientation of Coder apps in your template
using [resource ordering](./resource-ordering.md).
Check out our [module registry](https://registry.coder.com/modules) for
additional Coder apps from the team and our OSS community.
<children></children>

29
docs/templates/modules.md → docs/admin/templates/extending-templates/modules.md
View File

@ -8,7 +8,7 @@ You can store these modules externally from your Coder deployment, like in a git
repository or a Terraform registry. This example shows how to reference a module
from your template:
```hcl
```tf
data "coder_workspace" "me" {}
module "coder-base" {
@ -82,7 +82,7 @@ to resolve modules via [Artifactory](https://jfrog.com/artifactory/).
5. Create a file `.terraformrc` with following content and mount at
`/home/coder/.terraformrc` within the Coder provisioner.
```hcl
```tf
provider_installation {
direct {
exclude = ["registry.terraform.io/*/*"]
@ -95,7 +95,7 @@ to resolve modules via [Artifactory](https://jfrog.com/artifactory/).
6. Update module source as,
```hcl
```tf
module "module-name" {
source = "https://example.jfrog.io/tf__coder/module-name/coder"
version = "1.0.0"
@ -111,14 +111,16 @@ Based on the instructions
#### Example template
We have an example template [here](../../examples/jfrog/remote/main.tf) that
uses our [JFrog Docker](../../examples/jfrog/docker/main.tf) template as the
underlying module.
We have an example template
[here](https://github.com/coder/coder/blob/main/examples/jfrog/remote/main.tf)
that uses our
[JFrog Docker](https://github.com/coder/coder/blob/main/examples/jfrog/docker/main.tf)
template as the underlying module.
### Private git repository
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
[provisioner](../../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 access limited to the repository and no extra permissions.
In GitHub, you can generate a
@ -188,12 +190,9 @@ coder:
readOnly: true
```
### Next up
### Next steps
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](../guides/artifactory-integration.md).
- Coder Module Registry [here](https://registry.coder.com/modules)
- JFrog's
[Terraform Registry support](https://jfrog.com/help/r/jfrog-artifactory-documentation/terraform-registry)
- [Configuring the JFrog toolchain inside a workspace](../../integrations/jfrog-artifactory.md)
- [Coder Module Registry](https://registry.coder.com/modules)

28
docs/templates/parameters.md → docs/admin/templates/extending-templates/parameters.md
View File

@ -4,7 +4,7 @@ A template can prompt the user for additional information when creating
workspaces with
[_parameters_](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter).
![Parameters in Create Workspace screen](../images/parameters.png)
![Parameters in Create Workspace screen](../../../images/parameters.png)
The user can set parameters in the dashboard UI and CLI.
@ -14,7 +14,7 @@ parameters like instance size, geographical location, repository URL, etc.
This example lets a developer choose a Docker host for the workspace:
```hcl
```tf
data "coder_parameter" "docker_host" {
name = "Region"
description = "Which region would you like to deploy to?"
@ -44,7 +44,7 @@ data "coder_parameter" "docker_host" {
From there, a template can refer to a parameter's value:
```hcl
```tf
provider "docker" {
host = data.coder_parameter.docker_host.value
}
@ -56,7 +56,7 @@ A Coder parameter can have one of these types:
- `string`
- `bool`
- `number`.
- `number`
- `list(string)`
To specify a default value for a parameter with the `list(string)` type, use a
@ -64,7 +64,7 @@ JSON array and the Terraform
[jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode)
function. For example:
```hcl
```tf
data "coder_parameter" "security_groups" {
name = "Security groups"
icon = "/icon/aws.png"
@ -83,7 +83,7 @@ data "coder_parameter" "security_groups" {
A `string` parameter can provide a set of options to limit the user's choices:
```hcl
```tf
data "coder_parameter" "docker_host" {
name = "Region"
description = "Which region would you like to deploy to?"
@ -145,7 +145,7 @@ Example:
A parameter is _required_ if it doesn't have the `default` property. The user
**must** provide a value to this parameter before creating a workspace:
```hcl
```tf
data "coder_parameter" "account_name" {
name = "Account name"
description = "Cloud account name"
@ -156,7 +156,7 @@ data "coder_parameter" "account_name" {
If a parameter contains the `default` property, Coder will use this value if the
user does not specify any:
```hcl
```tf
data "coder_parameter" "base_image" {
name = "Base image"
description = "Base machine image to download"
@ -167,7 +167,7 @@ data "coder_parameter" "base_image" {
Admins can also set the `default` property to an empty value so that the
parameter field can remain empty:
```hcl
```tf
data "coder_parameter" "dotfiles_url" {
name = "dotfiles URL"
description = "Git repository with dotfiles"
@ -189,7 +189,7 @@ resources like volumes, regions, and so on.
Example:
```hcl
```tf
data "coder_parameter" "region" {
name = "Region"
description = "Region where the workspace is hosted"
@ -212,7 +212,7 @@ project without using cache.
Since these parameters are ephemeral in nature, subsequent builds proceed in the
standard manner:
```hcl
```tf
data "coder_parameter" "force_rebuild" {
name = "force_rebuild"
type = "bool"
@ -236,7 +236,7 @@ You can also specify its monotonicity as `increasing` or `decreasing` to verify
the current and new values. Use the `monotonic` attribute for resources that
can't be shrunk or grown without implications, like disk volume size.
```hcl
```tf
data "coder_parameter" "instances" {
name = "Instances"
type = "number"
@ -253,7 +253,7 @@ It is possible to override the default `error` message for a `number` parameter,
along with its associated `min` and/or `max` properties. The following message
placeholders are available `{min}`, `{max}`, and `{value}`.
```hcl
```tf
data "coder_parameter" "instances" {
name = "Instances"
type = "number"
@ -276,7 +276,7 @@ validations such as `monotonic`.
You can validate a `string` parameter to match a regular expression. The `regex`
property requires a corresponding `error` property.
```hcl
```tf
data "coder_parameter" "project_id" {
name = "Project ID"
description = "Alpha-numeric project ID"

4
docs/templates/process-logging.md → docs/admin/templates/extending-templates/process-logging.md
View File

@ -16,8 +16,8 @@ monitoring stack, such as CloudWatch, for further analysis or long-term storage.
Please note that these logs are not recorded or captured by the Coder
organization in any way, shape, or form.
> This is an [Enterprise](https://coder.com/docs/v2/latest/enterprise) feature.
> To learn more about Coder Enterprise, please
> This is an [Premium or Enterprise](https://coder.com/pricing) feature. To
> learn more about Coder Enterprise, please
> [contact sales](https://coder.com/contact).
## How this works

0
docs/templates/authentication.md → docs/admin/templates/extending-templates/provider-authentication.md
View File

12
docs/templates/resource-metadata.md → docs/admin/templates/extending-templates/resource-metadata.md
View File

@ -8,10 +8,10 @@ You can use `coder_metadata` to show Terraform resource attributes like these:
- Compute resources
- IP addresses
- [Secrets](../secrets.md#displaying-secrets)
- [Secrets](../../security/secrets.md#displaying-secrets)
- Important file paths
![ui](../images/metadata-ui.png)
![ui](../../../images/admin/templates/coder-metadata-ui.png)
<blockquote class="info">
Coder automatically generates the <code>type</code> metadata.
@ -25,7 +25,7 @@ You can also present automatically updating, dynamic values with
Expose the disk size, deployment name, and persistent directory in a Kubernetes
template with:
```hcl
```tf
resource "kubernetes_persistent_volume_claim" "root" {
...
}
@ -64,7 +64,7 @@ Some resources don't need to be exposed in the dashboard's UI. This helps keep
the workspace view clean for developers. To hide a resource, use the `hide`
attribute:
```hcl
```tf
resource "coder_metadata" "hide_serviceaccount" {
count = data.coder_workspace.me.start_count
resource_id = kubernetes_service_account.user_data.id
@ -81,7 +81,7 @@ resource "coder_metadata" "hide_serviceaccount" {
To use custom icons for your resource metadata, use the `icon` attribute. It
must be a valid path or URL.
```hcl
```tf
resource "coder_metadata" "resource_with_icon" {
count = data.coder_workspace.me.start_count
resource_id = kubernetes_service_account.user_data.id
@ -107,5 +107,5 @@ how to use the builtin icons [here](./icons.md).
## Up next
- [Secrets](../secrets.md)
- [Secrets](../../security/secrets.md)
- [Agent metadata](./agent-metadata.md)

12
docs/templates/resource-ordering.md → docs/admin/templates/extending-templates/resource-ordering.md
View File

@ -16,7 +16,7 @@ The `order` property of `coder_parameter` resource allows specifying the order
of parameters in UI forms. In the below example, `project_id` will appear
_before_ `account_id`:
```hcl
```tf
data "coder_parameter" "project_id" {
name = "project_id"
display_name = "Project ID"
@ -37,7 +37,7 @@ data "coder_parameter" "account_id" {
Agent resources within the UI left pane are sorted based on the `order`
property, followed by `name`, ensuring a consistent and intuitive arrangement.
```hcl
```tf
resource "coder_agent" "primary" {
...
@ -59,7 +59,7 @@ The `coder_agent` exposes metadata to present operational metrics in the UI.
Metrics defined with Terraform `metadata` blocks can be ordered using additional
`order` property; otherwise, they are sorted by `key`.
```hcl
```tf
resource "coder_agent" "main" {
...
@ -107,7 +107,7 @@ workspace view.
Only template defined applications can be arranged. _VS Code_ or _Terminal_
buttons are static.
```hcl
```tf
resource "coder_app" "code-server" {
agent_id = coder_agent.main.id
slug = "code-server"
@ -135,7 +135,7 @@ The options for Coder parameters maintain the same order as in the file
structure. This simplifies management and ensures consistency between
configuration files and UI presentation.
```hcl
```tf
data "coder_parameter" "database_region" {
name = "database_region"
display_name = "Database Region"
@ -166,7 +166,7 @@ In cases where multiple item properties exist, the order is inherited from the
file, facilitating seamless integration between a Coder template and UI
presentation.
```hcl
```tf
resource "coder_metadata" "attached_volumes" {
resource_id = docker_image.main.id

8
docs/templates/resource-persistence.md → docs/admin/templates/extending-templates/resource-persistence.md
View File

@ -24,7 +24,7 @@ meta-argument.
In this example, Coder will provision or tear down the `docker_container`
resource:
```hcl
```tf
data "coder_workspace" "me" {
}
@ -39,7 +39,7 @@ resource "docker_container" "workspace" {
Take this example resource:
```hcl
```tf
data "coder_workspace" "me" {
}
@ -57,7 +57,7 @@ To prevent this, use immutable IDs:
- `coder_workspace.me.owner_id`
- `coder_workspace.me.id`
```hcl
```tf
data "coder_workspace" "me" {
}
@ -78,7 +78,7 @@ You can prevent Terraform from recreating a 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
```tf
data "coder_workspace" "me" {
}

4
docs/templates/variables.md → docs/admin/templates/extending-templates/variables.md
View File

@ -6,7 +6,7 @@ construction of customizable templates. Unlike parameters, which are primarily
for workspace customization, template variables remain under the control of the
template author, ensuring workspace users cannot modify them.
```hcl
```tf
variable "CLOUD_API_KEY" {
type = string
description = "API key for the service"
@ -53,7 +53,7 @@ variables, you can employ a straightforward solution:
1. Create a `terraform.tfvars` file in in the template directory:
```hcl
```tf
coder_image = newimage:tag
```

141
docs/ides/web-ides.md → docs/admin/templates/extending-templates/web-ides.md
View File

@ -1,22 +1,11 @@
# Web IDEs
By default, Coder workspaces allow connections via:
- Web terminal
- SSH (plus any [SSH-compatible IDE](../ides.md))
It's common to also let developers to connect via web IDEs for uses cases like
zero trust networks, data science, contractors, and infrequent code
contributors.
![Row of IDEs](../images/ide-row.png)
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:
```hcl
```tf
# Add button to open Portainer in the workspace dashboard
# Note: Portainer must be already running in the workspace
resource "coder_app" "portainer" {
@ -34,33 +23,6 @@ resource "coder_app" "portainer" {
}
```
## External URLs
Any URL external to the Coder deployment is accessible as a `coder_app`. e.g.,
Dropbox, Slack, Discord, GitHub
```hcl
resource "coder_app" "pubslack" {
agent_id = coder_agent.coder.id
display_name = "Coder Public Slack"
slug = "pubslack"
url = "https://coder-com.slack.com/"
icon = "/icon/slack.svg"
external = true
}
resource "coder_app" "discord" {
agent_id = coder_agent.coder.id
display_name = "Coder Discord"
slug = "discord"
url = "https://discord.com/invite/coder"
icon = "/icon/discord.svg"
external = true
}
```
![External URLs](../images/external-apps.png)
## code-server
[code-server](https://github.com/coder/coder) is our supported method of running
@ -73,7 +35,7 @@ cd your-template/
vim main.tf
```
```hcl
```tf
resource "coder_agent" "main" {
arch = "amd64"
os = "linux"
@ -113,7 +75,7 @@ RUN code-server --install-extension eamodio.gitlens
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
```tf
resource "coder_app" "code-server" {
agent_id = coder_agent.main.id
slug = "code-server"
@ -131,7 +93,7 @@ resource "coder_app" "code-server" {
}
```
![code-server in a workspace](../images/code-server-ide.png)
![code-server in a workspace](../../../images/code-server-ide.png)
## VS Code Web
@ -142,7 +104,7 @@ command. To add VS Code web as a web IDE, you have two options.
[vscode-web module](https://registry.coder.com/modules/vscode-web) from the
coder registry.
```hcl
```tf
module "vscode-web" {
source = "registry.coder.com/modules/vscode-web/coder"
version = "1.0.14"
@ -154,7 +116,7 @@ command. To add VS Code web as a web IDE, you have two options.
2. Install and start in your `startup_script` and create a corresponding
`coder_app`
```hcl
```tf
resource "coder_agent" "main" {
arch = "amd64"
os = "linux"
@ -175,7 +137,7 @@ command. To add VS Code web as a web IDE, you have two options.
You also need to add a `coder_app` resource for this.
```hcl
```tf
# VS Code Web
resource "coder_app" "vscode-web" {
agent_id = coder_agent.coder.id
@ -188,12 +150,28 @@ command. To add VS Code web as a web IDE, you have two options.
}
```
## Jupyter Notebook
To use Jupyter Notebook in your workspace, you can install it by using the
[Jupyter Notebook module](https://registry.coder.com/modules/jupyter-notebook)
from the Coder registry:
```tf
module "jupyter-notebook" {
source = "registry.coder.com/modules/jupyter-notebook/coder"
version = "1.0.19"
agent_id = coder_agent.example.id
}
```
![Jupyter Notebook in Coder](../../../images/jupyter-notebook.png)
## JupyterLab
Configure your agent and `coder_app` like so to use Jupyter. Notice the
`subdomain=true` configuration:
```hcl
```tf
data "coder_workspace" "me" {}
resource "coder_agent" "coder" {
@ -223,24 +201,31 @@ resource "coder_app" "jupyter" {
}
```
Or Alternatively, you can use the JupyterLab module from the Coder registry:
```tf
module "jupyter" {
source = "registry.coder.com/modules/jupyter-lab/coder"
version = "1.0.0"
agent_id = coder_agent.main.id
}
```
If you cannot enable a
[wildcard subdomain](https://coder.com/docs/admin/configure#wildcard-access-url),
you can configure the template to run Jupyter on a path. There is however
[security risk](https://coder.com/docs/cli/server#--dangerous-allow-path-app-sharing)
[wildcard subdomain](../../../admin/setup/index.md#wildcard-access-url), you can
configure the template to run Jupyter on a path. There is however
[security risk](../../../reference/cli/server.md#--dangerous-allow-path-app-sharing)
running an app on a path and the template code is more complicated with coder
value substitution to recreate the path structure.
[This](https://github.com/sharkymark/v2-templates/tree/main/src/pod-with-jupyter-path)
is a community template example.
![JupyterLab in Coder](../images/jupyter.png)
![JupyterLab in Coder](../../../images/jupyter.png)
## RStudio
Configure your agent and `coder_app` like so to use RStudio. Notice the
`subdomain=true` configuration:
```hcl
```tf
resource "coder_agent" "coder" {
os = "linux"
arch = "amd64"
@ -252,7 +237,6 @@ resource "coder_agent" "coder" {
EOT
}
# rstudio
resource "coder_app" "rstudio" {
agent_id = coder_agent.coder.id
slug = "rstudio"
@ -274,21 +258,21 @@ If you cannot enable a
[wildcard subdomain](https://coder.com/docs/admin/configure#wildcard-access-url),
you can configure the template to run RStudio on a path using an NGINX reverse
proxy in the template. There is however
[security risk](https://coder.com/docs/cli/server#--dangerous-allow-path-app-sharing)
[security risk](https://coder.com/docs/reference/cli/server#--dangerous-allow-path-app-sharing)
running an app on a path and the template code is more complicated with coder
value substitution to recreate the path structure.
[This](https://github.com/sempie/coder-templates/tree/main/rstudio) is a
community template example.
![RStudio in Coder](../images/rstudio-port-forward.png)
![RStudio in Coder](../../../images/rstudio-port-forward.png)
## Airflow
Configure your agent and `coder_app` like so to use Airflow. Notice the
`subdomain=true` configuration:
```hcl
```tf
resource "coder_agent" "coder" {
os = "linux"
arch = "amd64"
@ -305,7 +289,7 @@ resource "coder_app" "airflow" {
agent_id = coder_agent.coder.id
slug = "airflow"
display_name = "Airflow"
icon = "https://upload.wikimedia.org/wikipedia/commons/d/de/AirflowLogo.png"
icon = "/icon/airflow.svg"
url = "http://localhost:8080"
subdomain = true
share = "owner"
@ -318,13 +302,28 @@ resource "coder_app" "airflow" {
}
```
![Airflow in Coder](../images/airflow-port-forward.png)
or use the [Airflow module](https://registry.coder.com/modules/apache-airflow)
from the Coder registry:
```tf
module "airflow" {
source = "registry.coder.com/modules/airflow/coder"
version = "1.0.13"
agent_id = coder_agent.main.id
}
```
![Airflow in Coder](../../../images/airflow-port-forward.png)
## File Browser
To access the contents of a workspace directory in a browser, you can use File
Browser. File Browser is a lightweight file manager that allows you to view and
manipulate files in a web browser.
Show and manipulate the contents of the `/home/coder` directory in a browser.
```hcl
```tf
resource "coder_agent" "coder" {
os = "linux"
arch = "amd64"
@ -355,11 +354,23 @@ resource "coder_app" "filebrowser" {
}
```
![File Browser](../images/file-browser.png)
Or alternatively, you can use the
[`filebrowser`](https://registry.coder.com/modules/filebrowser) module from the
Coder registry:
```tf
module "filebrowser" {
source = "registry.coder.com/modules/filebrowser/coder"
version = "1.0.8"
agent_id = coder_agent.main.id
}
```
![File Browser](../../../images/file-browser.png)
## SSH Fallback
If you prefer to run web IDEs in localhost, you can port forward using
[SSH](../ides.md#ssh) or the Coder CLI `port-forward` sub-command. Some web IDEs
may not support URL base path adjustment so port forwarding is the only
approach.
[SSH](../../../user-guides/workspace-access/index.md#ssh) or the Coder CLI
`port-forward` sub-command. Some web IDEs may not support URL base path
adjustment so port forwarding is the only approach.

2
docs/templates/workspace-tags.md → docs/admin/templates/extending-templates/workspace-tags.md
View File

@ -14,7 +14,7 @@ can enable dynamic tag selection and modify static template tags.
Here is a sample `coder_workspace_tags` data resource with a few workspace tags
specified:
```hcl
```tf
data "coder_workspace_tags" "custom_workspace_tags" {
tags = {
"zone" = "developers"

62
docs/admin/templates/index.md Normal file
View File

@ -0,0 +1,62 @@
# Template
Templates are written in
[Terraform](https://developer.hashicorp.com/terraform/intro) and define the
underlying infrastructure that all Coder workspaces run on.
![Starter templates](../../images/admin/templates/starter-templates.png)
<small>The "Starter Templates" page within the Coder dashboard.</small>
## Learn the concepts
While templates are written in standard Terraform, it's important to learn the
Coder-specific concepts behind templates. The best way to learn the concepts is
by
[creating a basic template from scratch](../../tutorials/template-from-scratch.md).
If you are unfamiliar with Terraform, see
[Hashicorp's Tutorials](https://developer.hashicorp.com/terraform/tutorials) for
common cloud providers.
## Starter templates
After learning the basics, use starter templates to import a template with
sensible defaults for popular platforms (e.g. AWS, Kubernetes, Docker, etc).
Docs:
[Create a template from a starter template](./creating-templates.md#from-a-starter-template).
## Extending templates
It's often necessary to extend the template to make it generally useful to end
users. Common modifications are:
- Your image(s) (e.g. a Docker image with languages and tools installed). Docs:
[Image management](./managing-templates/image-management.md).
- Additional parameters (e.g. disk size, instance type, or region). Docs:
[Template parameters](./extending-templates/parameters.md).
- Additional IDEs (e.g. JetBrains) or features (e.g. dotfiles, RDP). Docs:
[Adding IDEs and features](./extending-templates/index.md).
Learn more about the various ways you can
[extend your templates](./extending-templates/index.md).
## Best Practices
We recommend starting with a universal template that can be used for basic
tasks. As your Coder deployment grows, you can create more templates to meet the
needs of different teams.
- [Image management](./managing-templates/image-management.md): Learn how to
create and publish images for use within Coder workspaces & templates.
- [Dev Container support](./managing-templates/devcontainers.md): Enable dev
containers to allow teams to bring their own tools into Coder workspaces.
- [Template hardening](./extending-templates/resource-persistence.md#-bulletproofing):
Configure your template to prevent certain resources from being destroyed
(e.g. user disks).
- [Manage templates with Ci/Cd pipelines](./managing-templates/change-management.md):
Learn how to source control your templates and use GitOps to ensure template
changes are reviewed and tested.
- [Permissions and Policies](./template-permissions.md): Control who may access
and modify your template.
<children></children>

14
docs/templates/change-management.md → docs/admin/templates/managing-templates/change-management.md
View File

@ -5,7 +5,7 @@ automating the creation of new versions in CI/CD pipelines.
These pipelines will require tokens for your deployment. To cap token lifetime
on creation,
[configure Coder server to set a shorter max token lifetime](../reference/cli/server.md#--max-token-lifetime).
[configure Coder server to set a shorter max token lifetime](../../../reference/cli/server.md#--max-token-lifetime).
## coderd Terraform Provider
@ -16,7 +16,7 @@ pipelines. To run the provider in a CI/CD pipeline, and to prevent drift, you'll
need to store the Terraform state
[remotely](https://developer.hashicorp.com/terraform/language/backend).
```hcl
```tf
terraform {
required_providers {
coderd = {
@ -62,8 +62,8 @@ For an example, see how we push our development image and template
## Coder CLI
You can also [install Coder](../install/) to automate pushing new template
versions in CI/CD pipelines.
You can also [install Coder](../../../install/cli.md) to automate pushing new
template versions in CI/CD pipelines.
```console
# Install the Coder CLI
@ -87,3 +87,9 @@ coder templates push --yes $CODER_TEMPLATE_NAME \
--directory $CODER_TEMPLATE_DIR \
--name=$CODER_TEMPLATE_VERSION # Version name is optional
```
### Next steps
- [Coder CLI Reference](../../../reference/cli/templates.md)
- [Coderd Terraform Provider Reference](https://registry.terraform.io/providers/coder/coderd/latest/docs)
- [Coderd API Reference](../../../reference/index.md)

4
docs/templates/dependencies.md → docs/admin/templates/managing-templates/dependencies.md
View File

@ -91,8 +91,8 @@ inside a folder containing the Terraform source code for a given template.
This will create a new file named `.terraform.lock.hcl` in the current
directory. When you next run
[`coder templates push`](../reference/cli/templates_push.md), the lock file will
be stored alongside with the other template source code.
[`coder templates push`](../../../reference/cli/templates_push.md), the lock
file will be stored alongside with the other template source code.
> Note: Terraform best practices also recommend checking in your
> `.terraform.lock.hcl` into Git or other VCS.

12
docs/templates/dev-containers.md → docs/admin/templates/managing-templates/devcontainers.md
View File

@ -20,10 +20,10 @@ Coder:
## How it works
A Coder admin adds a devcontainer-compatible template to Coder (envbuilder).
Then 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.
Then developers enter their repository URL as a
[parameter](../extending-templates/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.
When using the [Envbuilder Terraform provider](#provider), a previously built
and cached image can be re-used directly, allowing instantaneous dev container
@ -47,10 +47,10 @@ iterate on their development environments.
Docker socket from the VM inside the container to enable Docker inside the
workspace.
![Devcontainer parameter screen](../images/templates/devcontainers.png)
![Devcontainer parameter screen](../../../images/templates/devcontainers.png)
Your template can prompt the user for a repo URL with
[Parameters](./parameters.md).
[Parameters](../extending-templates/parameters.md).
## Authentication

73
docs/admin/templates/managing-templates/image-management.md Normal file
View File

@ -0,0 +1,73 @@
# Image Management
While Coder provides example
[base container images](https://github.com/coder/enterprise-images) for
workspaces, it's often best to create custom images that matches the needs of
your users. This document serves a guide to operational maturity with some best
practices around managing workspaces images for Coder.
1. Create a minimal base image
2. Create golden image(s) with standard tooling
3. Allow developers to bring their own images and customizations with Dev
Containers
> Note: An image is just one of the many properties defined within the template.
> Templates can pull images from a public image registry (e.g. Docker Hub) or an
> internal one., thanks to Terraform.
## Create a minimal base image
While you may not use this directly in Coder templates, it's useful to have a
minimal base image is a small image that contains only the necessary
dependencies to work in your network and work with Coder. Here are some things
to consider:
- `curl`, `wget`, or `busybox` is required to download and run
[the agent](https://github.com/coder/coder/blob/main/provisionersdk/scripts/bootstrap_linux.sh)
- `git` is recommended so developers can clone repositories
- If the Coder server is using a certificate from an internal certificate
authority (CA), you'll need to add or mount these into your image
- Other generic utilities that will be required by all users, such as `ssh`,
`docker`, `bash`, `jq`, and/or internal tooling
- Consider creating (and starting the container with) a non-root user
> See Coder's
> [example base image](https://github.com/coder/enterprise-images/tree/main/images/minimal)
> for reference.
## Create general-purpose golden image(s) with standard tooling
It's often practical to have a few golden images that contain standard tooling
for developers. These images should contain a number of languages (e.g. Python,
Java, TypeScript), IDEs (VS Code, JetBrains, PyCharm), and other tools (e.g.
`docker`). Unlike project-specific images (which are also important), general
purpose images are great for:
- **Scripting:** Developers may just want to hop in a Coder workspace to run
basic scripts or queries.
- **Day 1 Onboarding:** New developers can quickly get started with a familiar
environment without having to browse through (or create) an image
- **Basic Projects:** Developers can use these images for simple projects that
don't require any specific tooling outside of the standard libraries. As the
project gets more complex, its best to move to a project-specific image.
- **"Golden Path" Projects:** If your developer platform offers specific tech
stacks and types of projects, the golden image can be a good starting point
for those projects.
> This is often referred to as a "sandbox" or "kitchen sink" image. Since large
> multi-purpose container images can quickly become difficult to maintain, it's
> important to keep the number of general-purpose images to a minimum (2-3 in
> most cases) with a well-defined scope.
Examples:
- [Universal Dev Containers Image](https://github.com/devcontainers/images/tree/main/src/universal)
## Allow developers to bring their own images and customizations with Dev Containers
While golden images are great for general use cases, developers will often need
specific tooling for their projects. The [Dev Container](https://containers.dev)
specification allows developers to define their projects dependencies within a
`devcontainer.json` in their Git repository.
- [Learn how to integrate Dev Containers with Coder](./devcontainers.md)

95
docs/admin/templates/managing-templates/index.md Normal file
View File

@ -0,0 +1,95 @@
# Working with templates
You create and edit Coder templates as [Terraform](../../../start/coder-tour.md)
configuration files (`.tf`) and any supporting files, like a README or
configuration files for other services.
## Who creates templates?
The [Template Admin](../../../admin/users/groups-roles.md#roles) role (and
above) can create templates. End users, like developers, create workspaces from
them. Templates can also be [managed with git](./change-management.md), allowing
any developer to propose changes to a template.
You can give different users and groups access to templates with
[role-based access control](../template-permissions.md).
## Starter templates
We provide starter templates for common cloud providers, like AWS, and
orchestrators, like Kubernetes. From there, you can modify them to use your own
images, VPC, cloud credentials, and so on. Coder supports all Terraform
resources and properties, so fear not if your favorite cloud provider isn't
here!
![Starter templates](../../../images/start/starter-templates.png)
If you prefer to use Coder on the
[command line](../../../reference/cli/index.md), `coder templates init`.
> Coder starter templates are also available on our
> [GitHub repo](https://github.com/coder/coder/tree/main/examples/templates).
## Community Templates
As well as Coder's starter templates, you can see a list of community templates
by our users
[here](https://github.com/coder/coder/blob/main/examples/templates/community-templates.md).
## Editing templates
Our starter templates are meant to be modified for your use cases. You can edit
any template's files directly in the Coder dashboard.
![Editing a template](../../../images/templates/choosing-edit-template.gif)
If you'd prefer to use the CLI, use `coder templates pull`, edit the template
files, then `coder templates push`.
> Even if you are a Terraform expert, we suggest reading our
> [guided tour of a template](../../../tutorials/template-from-scratch.md).
## Updating templates
Coder tracks a template's versions, keeping all developer workspaces up-to-date.
When you publish a new version, developers are notified to get the latest
infrastructure, software, or security patches. Learn more about
[change management](./change-management.md).
![Updating a template](../../../images/templates/update.png)
### Template update policies (enterprise) (premium)
Enterprise template admins may want workspaces to always remain on the latest
version of their parent template. To do so, enable **Template Update Policies**
in the template's general settings. All non-admin users of the template will be
forced to update their workspaces before starting them once the setting is
applied. Workspaces which leverage autostart or start-on-connect will be
automatically updated on the next startup.
![Template update policies](../../../images/templates/update-policies.png)
## Delete templates
You can delete a template using both the coder CLI and UI. Only
[template admins and owners](../../users/groups-roles.md#roles) can delete a
template, and the template must not have any running workspaces associated to
it.
In the UI, navigate to the template you want to delete, and select the dropdown
in the right-hand corner of the page to delete the template.
![delete-template](../../../images/delete-template.png)
Using the CLI, login to Coder and run the following command to delete a
template:
```shell
coder templates delete <template-name>
```
## Next steps
- [Image management](./image-management.md)
- [Devcontainer templates](./devcontainers.md)
- [Change management](./change-management.md)

103
docs/admin/templates/managing-templates/schedule.md Normal file
View File

@ -0,0 +1,103 @@
# Workspace Scheduling
You can configure a template to control how workspaces are started and stopped.
You can also manage the lifecycle of failed or inactive workspaces.
![Schedule screen](../../../images/admin/templates/schedule/template-schedule-settings.png)
## Schedule
Template [admins](../../users/index.md) may define these default values:
- [**Default autostop**](../../../user-guides/workspace-scheduling.md#autostop):
How long a workspace runs without user activity before Coder automatically
stops it.
- [**Autostop requirement**](#autostop-requirement-enterprise-premium): Enforce
mandatory workspace restarts to apply template updates regardless of user
activity.
- **Activity bump**: The duration of inactivity that must pass before a
workspace is automatically stopped.
- **Dormancy**: This allows automatic deletion of unused workspaces to reduce
spend on idle resources.
## Allow users scheduling
For templates where a uniform autostop duration is not appropriate, admins may
allow users to define their own autostart and autostop schedules. Admins can
restrict the days of the week a workspace should automatically start to help
manage infrastructure costs.
## Failure cleanup (enterprise) (premium)
Failure cleanup defines how long a workspace is permitted to remain in the
failed state prior to being automatically stopped. Failure cleanup is an
enterprise-only feature.
## Dormancy threshold (enterprise) (premium)
Dormancy Threshold defines how long Coder allows a workspace to remain inactive
before being moved into a dormant state. A workspace's inactivity is determined
by the time elapsed since a user last accessed the workspace. A workspace in the
dormant state is not eligible for autostart and must be manually activated by
the user before being accessible. Coder stops workspaces during their transition
to the dormant state if they are detected to be running. Dormancy Threshold is
an enterprise-only feature.
## Dormancy auto-deletion (enterprise) (premium)
Dormancy Auto-Deletion allows a template admin to dictate how long a workspace
is permitted to remain dormant before it is automatically deleted. Dormancy
Auto-Deletion is an enterprise-only feature.
## Autostop requirement (enterprise) (premium)
Autostop requirement is a template setting that determines how often workspaces
using the template must automatically stop. Autostop requirement ignores any
active connections, and ensures that workspaces do not run in perpetuity when
connections are left open inadvertently.
Workspaces will apply the template autostop requirement on the given day in the
user's timezone and specified quiet hours (see below). This ensures that
workspaces will not be stopped during work hours.
The available options are "Days", which can be set to "Daily", "Saturday" or
"Sunday", and "Weeks", which can be set to any number from 1 to 16.
"Days" governs which days of the week workspaces must stop. If you select
"daily", workspaces must be automatically stopped every day at the start of the
user's defined quiet hours. When using "Saturday" or "Sunday", workspaces will
be automatically stopped on Saturday or Sunday in the user's timezone and quiet
hours.
"Weeks" determines how many weeks between required stops. It cannot be changed
from the default of 1 if you have selected "Daily" for "Days". When using a
value greater than 1, workspaces will be automatically stopped every N weeks on
the day specified by "Days" and the user's quiet hours. The autostop week is
synchronized for all workspaces on the same template.
Autostop requirement is disabled when the template is using the deprecated max
lifetime feature. Templates can choose to use a max lifetime or an autostop
requirement during the deprecation period, but only one can be used at a time.
## User quiet hours (enterprise) (premium)
User quiet hours can be configured in the user's schedule settings page.
Workspaces on templates with an autostop requirement will only be forcibly
stopped due to the policy at the start of the user's quiet hours.
![User schedule settings](../../../images/admin/templates/schedule/user-quiet-hours.png)
Admins can define the default quiet hours for all users with the
`--default-quiet-hours-schedule` flag or `CODER_DEFAULT_QUIET_HOURS_SCHEDULE`
environment variable. The value should be a cron expression such as
`CRON_TZ=America/Chicago 30 2 * * *` which would set the default quiet hours to
2:30 AM in the America/Chicago timezone. The cron schedule can only have a
minute and hour component. The default schedule is UTC 00:00. It is recommended
to set the default quiet hours to a time when most users are not expected to be
using Coder.
Admins can force users to use the default quiet hours with the
[CODER_ALLOW_CUSTOM_QUIET_HOURS](../../../reference/cli/server.md#allow-custom-quiet-hours)
environment variable. Users will still be able to see the page, but will be
unable to set a custom time or timezone. If users have already set a custom
quiet hours schedule, it will be ignored and the default will be used instead.

8
docs/templates/open-in-coder.md → docs/admin/templates/open-in-coder.md
View File

@ -15,8 +15,8 @@ approach for "Open in Coder" flows.
### 1. Set up git authentication
See [External Authentication](../admin/external-auth.md) to set up git
authentication in your Coder deployment.
See [External Authentication](../external-auth.md) to set up git authentication
in your Coder deployment.
### 2. Modify your template to auto-clone repos
@ -53,7 +53,7 @@ resource "coder_agent" "dev" {
> - `coder` (relative to the home directory)
If you want the template to support any repository via
[parameters](./parameters.md)
[parameters](./extending-templates/parameters.md)
```hcl
# Require external authentication to use this template
@ -104,7 +104,7 @@ This can be used to pre-fill the git repo URL, disk size, image, etc.
[![Open in Coder](https://YOUR_ACCESS_URL/open-in-coder.svg)](https://YOUR_ACCESS_URL/templates/YOUR_TEMPLATE/workspace?param.git_repo=https://github.com/coder/slog&param.home_disk_size%20%28GB%29=20)
```
![Pre-filled parameters](../images/templates/pre-filled-parameters.png)
![Pre-filled parameters](../../images/templates/pre-filled-parameters.png)
### 5. Optional: disable specific parameter fields by including their names as

8
docs/templates/permissions.md → docs/admin/templates/template-permissions.md
View File

@ -1,6 +1,8 @@
# Permissions
# Permissions (enterprise) (premium)
![Template Permissions](../images/templates/permissions.png)
Licensed Coder administrators can control who can use and modify the template.
![Template Permissions](../../images/templates/permissions.png)
Permissions allow you to control who can use and modify the template. Both
individual user and groups can be added to the access list for a template.
@ -14,6 +16,6 @@ By default the `Everyone` group is assigned to each template meaning any Coder
user can use the template to create a workspace. To prevent this, disable the
`Allow everyone to use the template` setting when creating a template.
![Create Template Permissions](../images/templates/create-template-permissions.png)
![Create Template Permissions](../../images/templates/create-template-permissions.png)
Permissions is an enterprise-only feature.

4
docs/templates/troubleshooting.md → docs/admin/templates/troubleshooting.md
View File

@ -21,7 +21,7 @@ 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)
[access URL](../../admin/setup/index.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`
@ -31,7 +31,7 @@ practices:
`/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)
[Read our reverse-proxy docs](../../admin/setup/index.md#tls--reverse-proxy)
## Startup script issues

84
docs/admin/users/github-auth.md Normal file
View File

@ -0,0 +1,84 @@
## GitHub
### 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:
- **Homepage URL**: Set to your Coder deployments
[`CODER_ACCESS_URL`](../../reference/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 the Client ID and Client Secret generated by GitHub. You will use these
values in the next step.
Coder will need permission to access user email addresses. Find the "Account
Permissions" settings for your app and select "read-only" for "Email addresses".
### Step 2: Configure Coder with the OAuth credentials
Navigate to your Coder host and run the following command to start up the Coder
server:
```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.
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:
```env
CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05"
CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c"
```
**Note:** To allow everyone to signup using GitHub, set:
```env
CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
```
Once complete, run `sudo service coder restart` to reboot Coder.
If deploying Coder via Helm, you can set the above environment variables in the
`values.yaml` file as such:
```yaml
coder:
env:
- name: CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS
value: "true"
- name: CODER_OAUTH2_GITHUB_CLIENT_ID
value: "533...des"
- name: CODER_OAUTH2_GITHUB_CLIENT_SECRET
value: "G0CSP...7qSM"
# If setting allowed orgs, comment out CODER_OAUTH2_GITHUB_ALLOW_EVERYONE and its value
- name: CODER_OAUTH2_GITHUB_ALLOWED_ORGS
value: "your-org"
# If allowing everyone, comment out CODER_OAUTH2_GITHUB_ALLOWED_ORGS and it's value
#- name: CODER_OAUTH2_GITHUB_ALLOW_EVERYONE
# value: "true"
```
To upgrade Coder, run:
```shell
helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml
```
> We recommend requiring and auditing MFA usage for all users in your GitHub
> organizations. This can be enforced from the organization settings page in the
> "Authentication security" sidebar tab.

44
docs/admin/users/groups-roles.md Normal file
View File

@ -0,0 +1,44 @@
# Groups and Roles
Groups and roles can be manually assigned in Coder. For production deployments,
these can also be [managed and synced by the identity provider](./idp-sync.md).
## Groups
Groups are logical segmentations of users in Coder and can be used to control
which templates developers can use. For example:
- Users within the `devops` group can access the `AWS-VM` template
- Users within the `data-science` group can access the `Jupyter-Kubernetes`
template
## Roles
Roles determine which actions users can take within the platform.
| | Auditor | User Admin | Template Admin | Owner |
| --------------------------------------------------------------- | ------- | ---------- | -------------- | ----- |
| Add and remove Users | | ✅ | | ✅ |
| Manage groups (enterprise) (premium) | | ✅ | | ✅ |
| Change User roles | | | | ✅ |
| Manage **ALL** Templates | | | ✅ | ✅ |
| View **ALL** Workspaces | | | ✅ | ✅ |
| Update and delete **ALL** Workspaces | | | | ✅ |
| Run [external provisioners](../provisioners.md) | | | ✅ | ✅ |
| Execute and use **ALL** Workspaces | | | | ✅ |
| View all user operation [Audit Logs](../security/audit-logs.md) | ✅ | | | ✅ |
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).
In low-trust environments, we do not recommend giving users direct access to
edit templates. Instead, use
[CI/CD pipelines to update templates](../templates/managing-templates/change-management.md)
with proper security scans and code reviews in place.

31
docs/admin/users/headless-auth.md Normal file
View File

@ -0,0 +1,31 @@
# Headless Authentication
Headless user accounts that cannot use the web UI to log in to Coder. This is
useful for creating accounts for automated systems, such as CI/CD pipelines or
for users who only consume Coder via another client/API.
> You must have the User Admin role or above to create headless users.
## Create a headless user
<div class="tabs">
## CLI
```sh
coder users create \
--email="coder-bot@coder.com" \
--username="coder-bot" \
--login-type="none \
```
## UI
Navigate to the `Users` > `Create user` in the topbar
![Create a user via the UI](../../images/admin/users/headless-user.png)
</div>
To make API or CLI requests on behalf of the headless user, learn how to
[generate API tokens on behalf of a user](./sessions-tokens.md#generate-a-long-lived-api-token-on-behalf-of-another-user).

280
docs/admin/auth.md → docs/admin/users/idp-sync.md
View File

@ -1,260 +1,11 @@
# Authentication
By default, Coder is accessible via password authentication. Coder does not
recommend using password authentication in production, and recommends using an
authentication provider with properly configured multi-factor authentication
(MFA). It is your responsibility to ensure the auth provider enforces MFA
correctly.
The following steps explain how to set up GitHub OAuth or OpenID Connect.
## GitHub
### 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:
- **Homepage URL**: Set to your Coder deployments
[`CODER_ACCESS_URL`](../reference/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 the Client ID and Client Secret generated by GitHub. You will use these
values in the next step.
Coder will need permission to access user email addresses. Find the "Account
Permissions" settings for your app and select "read-only" for "Email addresses".
### Step 2: Configure Coder with the OAuth credentials
Navigate to your Coder host and run the following command to start up the Coder
server:
```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.
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:
```env
CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05"
CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c"
```
**Note:** To allow everyone to signup using GitHub, set:
```env
CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
```
Once complete, run `sudo service coder restart` to reboot Coder.
If deploying Coder via Helm, you can set the above environment variables in the
`values.yaml` file as such:
```yaml
coder:
env:
- name: CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS
value: "true"
- name: CODER_OAUTH2_GITHUB_CLIENT_ID
value: "533...des"
- name: CODER_OAUTH2_GITHUB_CLIENT_SECRET
value: "G0CSP...7qSM"
# If setting allowed orgs, comment out CODER_OAUTH2_GITHUB_ALLOW_EVERYONE and its value
- name: CODER_OAUTH2_GITHUB_ALLOWED_ORGS
value: "your-org"
# If allowing everyone, comment out CODER_OAUTH2_GITHUB_ALLOWED_ORGS and it's value
#- name: CODER_OAUTH2_GITHUB_ALLOW_EVERYONE
# value: "true"
```
To upgrade Coder, run:
```shell
helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml
```
> We recommend requiring and auditing MFA usage for all users in your GitHub
> organizations. This can be enforced from the organization settings page in the
> "Authentication security" sidebar tab.
## OpenID Connect
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
Your OIDC provider will ask you for the following parameter:
- **Redirect URI**: Set to `https://coder.domain.com/api/v2/users/oidc/callback`
### Step 2: Configure Coder with the OpenID Connect credentials
Navigate to your Coder host and run the following command to start up the Coder
server:
```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:
```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"
CODER_OIDC_CLIENT_SECRET="G0CSP...7qSM"
```
Once complete, run `sudo service coder restart` to reboot Coder.
If deploying Coder via Helm, you can set the above environment variables in the
`values.yaml` file as such:
```yaml
coder:
env:
- name: CODER_OIDC_ISSUER_URL
value: "https://issuer.corp.com"
- name: CODER_OIDC_EMAIL_DOMAIN
value: "your-domain-1,your-domain-2"
- name: CODER_OIDC_CLIENT_ID
value: "533...des"
- name: CODER_OIDC_CLIENT_SECRET
value: "G0CSP...7qSM"
```
To upgrade Coder, run:
```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.
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`.
### 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.
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.
### 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
provider, Coder will validate that its value is `true`. If needed, you can
disable this behavior with the following setting:
```env
CODER_OIDC_IGNORE_EMAIL_VERIFIED=true
```
> **Note:** This will cause Coder to implicitly treat all OIDC emails as
> "verified", regardless of what the upstream identity provider says.
### 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.
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`).
> To avoid conflicts, Coder may also append a random word to the resulting
> username.
## OIDC Login Customization
If you'd like to change the OpenID Connect button text and/or icon, you can
configure them like so:
```env
CODER_OIDC_SIGN_IN_TEXT="Sign in with Gitea"
CODER_OIDC_ICON_URL=https://gitea.io/images/gitea.png
```
To change the icon and text above the OpenID Connect button, see application
name and logo url in [appearance](./appearance.md) settings.
## Disable Built-in Authentication
To remove email and password login, set the following environment variable on
your Coder deployment:
```env
CODER_DISABLE_PASSWORD_AUTH=true
```
## SCIM (enterprise) (premium)
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.
```env
CODER_SCIM_AUTH_HEADER="your-api-key"
```
## TLS
If your OpenID Connect provider requires client TLS certificates for
authentication, you can configure them like so:
```env
CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
```
## Group Sync (enterprise) (premium)
# IDP Sync (enterprise) (premium)
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 being sent by your OpenID
provider. You might need to request an additional
[scope](../reference/cli/server.md#--oidc-scopes) or additional configuration on
the OpenID provider side.
[scope](../../reference/cli/server.md#--oidc-scopes) or additional configuration
on the OpenID provider side.
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
@ -283,7 +34,8 @@ the OIDC provider. See
> ones include `groups`, `memberOf`, and `roles`.
Next configure the Coder server to read groups from the claim name with the
[OIDC group field](../reference/cli/server.md#--oidc-group-field) server flag:
[OIDC group field](../../reference/cli/server.md#--oidc-group-field) server
flag:
```sh
# as an environment variable
@ -301,7 +53,7 @@ names in Coder and removed from groups that the user no longer belongs to.
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 with the
[OIDC group mapping](../reference/cli/server.md#--oidc-group-mapping) server
[OIDC group mapping](../../reference/cli/server.md#--oidc-group-mapping) server
flag.
```sh
@ -339,7 +91,7 @@ For deployments with multiple [organizations](./organizations.md), you must
configure group sync at the organization level. In future Coder versions, you
will be able to configure this in the UI. For now, you must use CLI commands.
First confirm you have the [Coder CLI](../install/index.md) installed and are
First confirm you have the [Coder CLI](../../install/index.md) installed and are
logged in with a user who is an Owner or Organization Admin role. Next, confirm
that your OIDC provider is sending a groups claim by logging in with OIDC and
visiting the following URL:
@ -420,7 +172,7 @@ coder organizations settings set group-sync \
Visit the Coder UI to confirm these changes:
![IDP Sync](../images/admin/organizations/group-sync.png)
![IDP Sync](../../images/admin/users/organizations/group-sync.png)
</div>
@ -430,7 +182,7 @@ You can limit which groups from your identity provider can log in to Coder with
[CODER_OIDC_ALLOWED_GROUPS](https://coder.com/docs/cli/server#--oidc-allowed-groups).
Users who are not in a matching group will see the following error:
![Unauthorized group error](../images/admin/group-allowlist.png)
![Unauthorized group error](../../images/admin/group-allowlist.png)
## Role sync (enterprise) (premium)
@ -460,10 +212,10 @@ the OIDC provider. See
> Depending on the OIDC provider, this claim may be named differently.
Next configure the Coder server to read groups from the claim name with the
[OIDC role field](../reference/cli/server.md#--oidc-user-role-field) server
[OIDC role field](../../reference/cli/server.md#--oidc-user-role-field) server
flag:
Set the following in your Coder server [configuration](./configure.md).
Set the following in your Coder server [configuration](../setup/index.md).
```env
# Depending on your identity provider configuration, you may need to explicitly request a "roles" scope
@ -546,7 +298,7 @@ coder organizations settings set role-sync \
Visit the Coder UI to confirm these changes:
![IDP Sync](../images/admin/organizations/role-sync.png)
![IDP Sync](../../images/admin/users/organizations/role-sync.png)
</div>
@ -575,7 +327,7 @@ the OIDC provider. See
> ones include `groups`, `memberOf`, and `roles`.
Next configure the Coder server to read groups from the claim name with the
[OIDC organization field](../reference/cli/server.md#--oidc-organization-field)
[OIDC organization field](../../reference/cli/server.md#--oidc-organization-field)
server flag:
```sh
@ -589,7 +341,7 @@ Next, fetch the corresponding organization IDs using the following endpoint:
https://[coder.example.com]/api/v2/organizations
```
Set the following in your Coder server [configuration](./configure.md).
Set the following in your Coder server [configuration](../setup/index.md).
```env
CODER_OIDC_ORGANIZATION_MAPPING='{"data-scientists":["d8d9daef-e273-49ff-a832-11fe2b2d4ab1", "70be0908-61b5-4fb5-aba4-4dfb3a6c5787"]}'
@ -614,8 +366,8 @@ Some common issues when enabling group/role sync.
If you are running into issues with group/role sync, is best to view your Coder
server logs and enable
[verbose mode](https://coder.com/docs/v2/v2.5.1/cli#-v---verbose). To reduce
noise, you can filter for only logs related to group/role sync:
[verbose mode](../../reference/cli/index.md#-v---verbose). To reduce noise, you
can filter for only logs related to group/role sync:
```sh
CODER_VERBOSE=true

63
docs/admin/users.md → docs/admin/users/index.md
View File

@ -1,48 +1,33 @@
# Users
This article walks you through the user roles available in Coder and creating
and managing users.
By default, Coder is accessible via password authentication. For production
deployments, we recommend using an SSO authentication provider with multi-factor
authentication (MFA). It is your responsibility to ensure the auth provider
enforces MFA correctly.
## Configuring SSO
- [OpenID Connect](./oidc-auth.md) (e.g. Okta, KeyCloak, PingFederate, Azure AD)
- [GitHub](./github-auth.md) (or GitHub Enterprise)
## Groups
Multiple users can be organized into logical groups to control which templates
they can use. While groups can be manually created in Coder, we recommend
syncing them from your identity provider.
- [Learn more about Groups](./groups-roles.md)
- [Group & Role Sync](./idp-sync.md)
## Roles
Coder offers these user roles in the community edition:
Roles determine which actions users can take within the platform. Typically,
most developers in your organization have the `Member` role, allowing them to
create workspaces. Other roles have administrative capabilities such as
auditing, managing users, and managing templates.
| | Auditor | User Admin | Template Admin | Owner |
| ----------------------------------------------------- | ------- | ---------- | -------------- | ----- |
| Add and remove Users | | ✅ | | ✅ |
| Manage groups (premium) | | ✅ | | ✅ |
| Change User roles | | | | ✅ |
| Manage **ALL** Templates | | | ✅ | ✅ |
| View **ALL** Workspaces | | | ✅ | ✅ |
| Update and delete **ALL** Workspaces | | | | ✅ |
| Run [external provisioners](./provisioners.md) | | | ✅ | ✅ |
| 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.
## Custom Roles (Premium) (Beta)
Coder v2.16+ deployments can configure custom roles on the
[Organization](./organizations.md) level.
![Custom roles](../images/admin/organizations/custom-roles.png)
> Note: This requires a Premium license.
> [Contact your account team](https://coder.com/contact) for more details.
## 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).
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.
- [Learn more about Roles](./groups-roles.md)
- [Group & Role Sync](./idp-sync.md)
## User status

158
docs/admin/users/oidc-auth.md Normal file
View File

@ -0,0 +1,158 @@
# OpenID Connect
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
Your OIDC provider will ask you for the following parameter:
- **Redirect URI**: Set to `https://coder.domain.com/api/v2/users/oidc/callback`
## Step 2: Configure Coder with the OpenID Connect credentials
Navigate to your Coder host and run the following command to start up the Coder
server:
```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:
```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"
CODER_OIDC_CLIENT_SECRET="G0CSP...7qSM"
```
Once complete, run `sudo service coder restart` to reboot Coder.
If deploying Coder via Helm, you can set the above environment variables in the
`values.yaml` file as such:
```yaml
coder:
env:
- name: CODER_OIDC_ISSUER_URL
value: "https://issuer.corp.com"
- name: CODER_OIDC_EMAIL_DOMAIN
value: "your-domain-1,your-domain-2"
- name: CODER_OIDC_CLIENT_ID
value: "533...des"
- name: CODER_OIDC_CLIENT_SECRET
value: "G0CSP...7qSM"
```
To upgrade Coder, run:
```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.
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`.
### 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.
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.
### 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
provider, Coder will validate that its value is `true`. If needed, you can
disable this behavior with the following setting:
```env
CODER_OIDC_IGNORE_EMAIL_VERIFIED=true
```
> **Note:** This will cause Coder to implicitly treat all OIDC emails as
> "verified", regardless of what the upstream identity provider says.
### 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.
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`).
> To avoid conflicts, Coder may also append a random word to the resulting
> username.
## OIDC Login Customization
If you'd like to change the OpenID Connect button text and/or icon, you can
configure them like so:
```env
CODER_OIDC_SIGN_IN_TEXT="Sign in with Gitea"
CODER_OIDC_ICON_URL=https://gitea.io/images/gitea.png
```
To change the icon and text above the OpenID Connect button, see application
name and logo url in [appearance](../setup/appearance.md) settings.
## Disable Built-in Authentication
To remove email and password login, set the following environment variable on
your Coder deployment:
```env
CODER_DISABLE_PASSWORD_AUTH=true
```
## SCIM (enterprise) (premium)
Coder supports user provisioning and deprovisioning via SCIM 2.0 with header
authentication. Upon deactivation, users are
[suspended](./index.md#suspend-a-user) and are not deleted.
[Configure](../setup/index.md) your SCIM application with an auth key and supply
it the Coder server.
```env
CODER_SCIM_AUTH_HEADER="your-api-key"
```
## TLS
If your OpenID Connect provider requires client TLS certificates for
authentication, you can configure them like so:
```env
CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
```
### Next steps
- [Group Sync](./idp-sync.md)
- [Groups & Roles](./groups-roles.md)

40
docs/admin/organizations.md → docs/admin/users/organizations.md
View File

@ -1,7 +1,8 @@
# Organizations (Premium)
> Note: Organizations requires a [Premium license](../licensing.md). For more
> details, [contact your account team](https://coder.com/contact).
> Note: Organizations requires a
> [Premium license](https://coder.com/pricing#compare-plans). For more details,
> [contact your account team](https://coder.com/contact).
Organizations can be used to segment and isolate resources inside a Coder
deployment for different user groups or projects.
@ -11,7 +12,7 @@ deployment for different user groups or projects.
Here is an example of how one could use organizations to run a Coder deployment
with multiple platform teams, all with unique resources:
![Organizations Example](../images/admin/organizations/diagram.png)
![Organizations Example](../../images/admin/users/organizations/diagram.png)
## The default organization
@ -20,21 +21,21 @@ All Coder deployments start with one organization called `Coder`.
To edit the organization details, navigate to `Deployment -> Organizations` in
the top bar:
![Organizations Menu](../images/admin/organizations/deployment-organizations.png)
![Organizations Menu](../../images/admin/users/organizations/deployment-organizations.png)
From there, you can manage the name, icon, description, users, and groups:
![Organization Settings](../images/admin/organizations/default-organization.png)
![Organization Settings](../../images/admin/users/organizations/default-organization.png)
## Additional organizations
Any additional organizations have unique admins, users, templates, provisioners,
groups, and workspaces. Each organization must have at least one
[provisioner](./provisioners.md) as the built-in provisioner only applies to the
default organization.
[provisioner](../provisioners.md) as the built-in provisioner only applies to
the default organization.
You can configure [organization/role/group sync](./auth.md) from your identity
provider to avoid manually assigning users to organizations.
You can configure [organization/role/group sync](./idp-sync.md) from your
identity provider to avoid manually assigning users to organizations.
## Creating an organization
@ -49,17 +50,16 @@ provider to avoid manually assigning users to organizations.
Within the sidebar, click `New organization` to create an organization. In this
example, we'll create the `data-platform` org.
![New Organization](../images/admin/organizations/new-organization.png)
![New Organization](../../images/admin/users/organizations/new-organization.png)
From there, let's deploy a provisioner and template for this organization.
### 2. Deploy a provisioner
[Provisioners](../admin/provisioners.md) are organization-scoped and are
responsible for executing Terraform/OpenTofu to provision the infrastructure for
workspaces and testing templates. Before creating templates, we must deploy at
least one provisioner as the built-in provisioners are scoped to the default
organization.
[Provisioners](../provisioners.md) are organization-scoped and are responsible
for executing Terraform/OpenTofu to provision the infrastructure for workspaces
and testing templates. Before creating templates, we must deploy at least one
provisioner as the built-in provisioners are scoped to the default organization.
Using Coder CLI, run the following command to create a key that will be used to
authenticate the provisioner:
@ -74,7 +74,7 @@ Successfully created provisioner key data-cluster! Save this authentication toke
Next, start the provisioner with the key on your desired platform. In this
example, we'll start it using the Coder CLI on a host with Docker. For
instructions on using other platforms like Kubernetes, see our
[provisioner documentation](../admin/provisioners.md).
[provisioner documentation](../provisioners.md).
```sh
export CODER_URL=https://<your-coder-url>
@ -87,24 +87,24 @@ coder provisionerd start --org <org-name>
Once you've started a provisioner, you can create a template. You'll notice the
"Create Template" screen now has an organization dropdown:
![Template Org Picker](../images/admin/organizations/template-org-picker.png)
![Template Org Picker](../../images/admin/users/organizations/template-org-picker.png)
### 5. Add members
Navigate to `Deployment->Organizations` to add members to your organization.
Once added, they will be able to see the organization-specific templates.
![Add members](../images/admin/organizations/organization-members.png)
![Add members](../../images/admin/users/organizations/organization-members.png)
### 6. Create a workspace
Now, users in the data platform organization will see the templates related to
their organization. Users can be in multiple organizations.
![Workspace List](../images/admin/organizations/workspace-list.png)
![Workspace List](../../images/admin/users/organizations/workspace-list.png)
## Beta
Organizations is in beta. If you encounter any issues, please
As of v2.16.0, Organizations is in beta. If you encounter any issues, please
[file an issue](https://github.com/coder/coder/issues/new) or contact your
account team.

27
docs/admin/users/password-auth.md Normal file
View File

@ -0,0 +1,27 @@
# Password Authentication
Coder has password authentication enabled by default. The account created during
setup is a username/password account.
## Disable password authentication
To disable password authentication, use the
[`CODER_DISABLE_PASSWORD_AUTH`](../../reference/cli/server.md#--disable-password-auth)
flag on the Coder server.
## Restore the `Owner` user
If you remove the admin user account (or forget the password), you can run the
[`coder server create-admin-user`](../../reference/cli/server_create-admin-user.md)command
on your server.
> Note: You must run this command on the same machine running the Coder server.
> If you are running Coder on Kubernetes, this means using
> [kubectl exec](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_exec/)
> to exec into the pod.
## Reset a user's password
An admin must reset passwords on behalf of users. This can be done in the web UI
in the Users page or CLI:
[`coder reset-password`](../../reference/cli/reset-password.md)

10
docs/admin/quotas.md → docs/admin/users/quotas.md
View File

@ -9,7 +9,8 @@ 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).
Quotas are scoped to [Groups](./groups-roles.md) in Enterprise and
[organizations](./organizations.md) in Premium.
## Definitions
@ -70,7 +71,7 @@ unused workspaces and freeing up compute in the cluster.
Each group has a configurable Quota Allowance. A user's budget is calculated as
the sum of their allowances.
![group-settings](../images/admin/quota-groups.png)
![group-settings](../../images/admin/users/quotas/quota-groups.png)
For example:
@ -98,8 +99,9 @@ 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)
![build-log](../../images/admin/quota-buildlog.png)
## Up next
- [Configuring](./configure.md)
- [Group Sync](./idp-sync.md)
- [Control plane configuration](../setup/index.md)

64
docs/admin/users/sessions-tokens.md Normal file
View File

@ -0,0 +1,64 @@
# API & Session Tokens
Users can generate tokens to make API requests on behalf of themselves.
## Short-Lived Tokens (Sessions)
The [Coder CLI](../../install/cli.md) and [Backstage Plugin](#TODO) use
short-lived token to authenticate. To generate a short-lived session token on
behalf of your account, visit the following URL:
`https://coder.example.com/cli-auth`
### Session Durations
By default, sessions last 24 hours and are automatically refreshed. You can
configure
[`CODER_SESSION_DURATION`](../../reference/cli/server.md#--session-duration) to
change the duration and
[`CODER_DISABLE_SESSION_EXPIRY_REFRESH`](../../reference/cli/server.md#--disable-session-expiry-refresh)
to configure this behavior.
## Long-Lived Tokens (API Tokens)
Users can create long lived tokens. We refer to these as "API tokens" in the
product.
### Generate a long-lived API token on behalf of yourself
<div class="tabs">
#### UI
Visit your account settings in the top right of the dashboard or by navigating
to `https://coder.example.com/settings/account`
Navigate to the tokens page in the sidebar and create a new token:
![Create an API token](../../images/admin/users/create-token.png)
#### CLI
Use the following command:
```sh
coder tokens create --name=my-token --lifetime=720h
```
See the help docs for
[`coder tokens create`](../../reference/cli/tokens_create.md) for more info.
</div>
### Generate a long-lived API token on behalf of another user
Today, you must use the REST API to generate a token on behalf of another user.
You must have the `Owner` role to do this. Use our API reference for more
information:
[Create token API key](https://coder.com/docs/reference/api/users#create-token-api-key)
### Set max token length
You can use the
[`CODER_MAX_TOKEN_LIFETIME`](https://coder.com/docs/reference/cli/server#--max-token-lifetime)
server flag to set the maximum duration for long-lived tokens in your
deployment.

393
docs/architecture/architecture.md
View File

@ -1,393 +0,0 @@
# Architecture
The Coder deployment model is flexible and offers various components that
platform administrators can deploy and scale depending on their use case. This
page describes possible deployments, challenges, and risks associated with them.
## Primary components
### 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.
It offers:
- Dashboard (UI)
- HTTP API
- Dev URLs (HTTP reverse proxy to workspaces)
- Workspace Web Applications (e.g for easy access to `code-server`)
- Agent registration
### provisionerd
_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.
### 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.
It offers the following services along with much more:
- SSH
- Port forwarding
- Liveness checks
- `startup_script` automation
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:
- Reducing global client latency (distribute coderd and centralize database)
- Achieving greater availability and efficiency (horizontally scale individual
services)
### Workspaces
At the highest level, a workspace is a set of cloud resources. These resources
can be VMs, Kubernetes clusters, storage buckets, or whatever else Terraform
lets you dream up.
The resources that run the agent are described as _computational resources_,
while those that don't are called _peripheral resources_.
Each resource may also be _persistent_ or _ephemeral_ depending on whether
they're destroyed on workspace stop.
## Deployment models
### Single region architecture
![Architecture Diagram](../images/architecture-single-region.png)
#### Components
This architecture consists of a single load balancer, several _coderd_ replicas,
and _Coder workspaces_ deployed in the same region.
##### Workload resources
- Deploy at least one _coderd_ replica per availability zone with _coderd_
instances and provisioners. High availability is recommended but not essential
for small deployments.
- Single replica deployment is a special case that can address a
tiny/small/proof-of-concept installation on a single virtual machine. If you
are serving more than 100 users/workspaces, you should add more replicas.
**Coder workspace**
- For small deployments consider a lightweight workspace runtime like the
[Sysbox](https://github.com/nestybox/sysbox) container runtime. Learn more how
to enable
[docker-in-docker using Sysbox](https://asciinema.org/a/kkTmOxl8DhEZiM2fLZNFlYzbo?speed=2).
**HA Database**
- Monitor node status and resource utilization metrics.
- Implement robust backup and disaster recovery strategies to protect against
data loss.
##### Workload supporting resources
**Load balancer**
- Distributes and load balances traffic from agents and clients to _Coder
Server_ replicas across availability zones.
- Layer 7 load balancing. The load balancer can decrypt SSL traffic, and
re-encrypt using an internal certificate.
- Session persistence (sticky sessions) can be disabled as _coderd_ instances
are stateless.
- WebSocket and long-lived connections must be supported.
**Single sign-on**
- Integrate with existing Single Sign-On (SSO) solutions used within the
organization via the supported OAuth 2.0 or OpenID Connect standards.
- Learn more about [Authentication in Coder](../admin/auth.md).
### Multi-region architecture
![Architecture Diagram](../images/architecture-multi-region.png)
#### Components
This architecture is for globally distributed developer teams using Coder
workspaces on daily basis. It features a single load balancer with regionally
deployed _Workspace Proxies_, several _coderd_ replicas, and _Coder workspaces_
provisioned in different regions.
Note: The _multi-region architecture_ assumes the same deployment principles as
the _single region architecture_, but it extends them to multi region deployment
with workspace proxies. Proxies are deployed in regions closest to developers to
offer the fastest developer experience.
##### Workload resources
**Workspace proxy**
- Workspace proxy offers developers the option to establish a fast relay
connection when accessing their workspace via SSH, a workspace application, or
port forwarding.
- Dashboard connections, API calls (e.g. _list workspaces_) are not served over
proxies.
- Proxies do not establish connections to the database.
- Proxy instances do not share authentication tokens between one another.
##### Workload supporting resources
**Proxy load balancer**
- Distributes and load balances workspace relay traffic in a single region
across availability zones.
- Layer 7 load balancing. The load balancer can decrypt SSL traffic, and
re-encrypt using internal certificate.
- Session persistence (sticky sessions) can be disabled as _coderd_ instances
are stateless.
- WebSocket and long-lived connections must be supported.
### Multi-cloud architecture
By distributing Coder workspaces across different cloud providers, organizations
can mitigate the risk of downtime caused by provider-specific outages or
disruptions. Additionally, multi-cloud deployment enables organizations to
leverage the unique features and capabilities offered by each cloud provider,
such as region availability and pricing models.
![Architecture Diagram](../images/architecture-multi-cloud.png)
#### Components
The deployment model comprises:
- `coderd` instances deployed within a single region of the same cloud provider,
with replicas strategically distributed across availability zones.
- Workspace provisioners deployed in each cloud, communicating with `coderd`
instances.
- Workspace proxies running in the same locations as provisioners to optimize
user connections to workspaces for maximum speed.
Due to the relatively large overhead of cross-regional communication, it is not
advised to set up multi-cloud control planes. It is recommended to keep coderd
replicas and the database within the same cloud-provider and region.
Note: The _multi-cloud architecture_ follows the deployment principles outlined
in the _multi-region architecture_. However, it adapts component selection based
on the specific cloud provider. Developers can initiate workspaces based on the
nearest region and technical specifications provided by the cloud providers.
##### Workload resources
**Workspace provisioner**
- _Security recommendation_: Create a long, random pre-shared key (PSK) and add
it to the regional secret store, so that local _provisionerd_ can access it.
Remember to distribute it using safe, encrypted communication channel. The PSK
must also be added to the _coderd_ configuration.
**Workspace proxy**
- _Security recommendation_: Use `coder` CLI to create
[authentication tokens for every workspace proxy](../admin/workspace-proxies.md#requirements),
and keep them in regional secret stores. Remember to distribute them using
safe, encrypted communication channel.
**Managed database**
- For AWS: _Amazon RDS for PostgreSQL_
- For Azure: _Azure Database for PostgreSQL - Flexible Server_
- For GCP: _Cloud SQL for PostgreSQL_
##### Workload supporting resources
**Kubernetes platform (optional)**
- For AWS: _Amazon Elastic Kubernetes Service_
- For Azure: _Azure Kubernetes Service_
- For GCP: _Google Kubernetes Engine_
See here for an example deployment of
[Coder on Azure Kubernetes Service](https://github.com/ericpaulsen/coder-aks).
Learn more about [security requirements](../install/kubernetes.md) for deploying
Coder on Kubernetes.
**Load balancer**
- For AWS:
- _AWS Network Load Balancer_
- Level 4 load balancing
- For Kubernetes deployment: annotate service with
`service.beta.kubernetes.io/aws-load-balancer-type: "nlb"`, preserve the
client source IP with `externalTrafficPolicy: Local`
- _AWS Classic Load Balancer_
- Level 7 load balancing
- For Kubernetes deployment: set `sessionAffinity` to `None`
- For Azure:
- _Azure Load Balancer_
- Level 7 load balancing
- Azure Application Gateway
- Deploy Azure Application Gateway when more advanced traffic routing
policies are needed for Kubernetes applications.
- Take advantage of features such as WebSocket support and TLS termination
provided by Azure Application Gateway, enhancing the capabilities of
Kubernetes deployments on Azure.
- For GCP:
- _Cloud Load Balancing_ with SSL load balancer:
- Layer 4 load balancing, SSL enabled
- _Cloud Load Balancing_ with HTTPS load balancer:
- Layer 7 load balancing
- For Kubernetes deployment: annotate service (with ingress enabled) with
`kubernetes.io/ingress.class: "gce"`, leverage the `NodePort` service
type.
- Note: HTTP load balancer rejects DERP upgrade, Coder will fallback to
WebSockets
**Single sign-on**
- For AWS:
[AWS IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html)
- For Azure:
[Microsoft Entra ID Sign-On](https://learn.microsoft.com/en-us/entra/identity/app-proxy/)
- For GCP:
[Google Cloud Identity Platform](https://cloud.google.com/architecture/identity/single-sign-on)
### Air-gapped architecture
The air-gapped deployment model refers to the setup of Coder's development
environment within a restricted network environment that lacks internet
connectivity. This deployment model is often required for organizations with
strict security policies or those operating in isolated environments, such as
government agencies or certain enterprise setups.
The key features of the air-gapped architecture include:
- _Offline installation_: Deploy workspaces without relying on an external
internet connection.
- _Isolated package/plugin repositories_: Depend on local repositories for
software installation, updates, and security patches.
- _Secure data transfer_: Enable encrypted communication channels and robust
access controls to safeguard sensitive information.
Learn more about [offline deployments](../install/offline.md) of Coder.
![Architecture Diagram](../images/architecture-air-gapped.png)
#### Components
The deployment model includes:
- _Workspace provisioners_ with direct access to self-hosted package and plugin
repositories and restricted internet access.
- _Mirror of Terraform Registry_ with multiple versions of Terraform plugins.
- _Certificate Authority_ with all TLS certificates to build secure
communication channels.
The model is compatible with various infrastructure models, enabling deployment
across multiple regions and diverse cloud platforms.
##### Workload resources
**Workspace provisioner**
- Includes Terraform binary in the container or system image.
- Checks out Terraform plugins from self-hosted _Registry_ mirror.
- Deploys workspace images stored in the self-hosted _Container Registry_.
**Coder server**
- Update checks are disabled (`CODER_UPDATE_CHECK=false`).
- Telemetry data is not collected (`CODER_TELEMETRY_ENABLE=false`).
- Direct connections are not possible, workspace traffic is relayed through
control plane's DERP proxy.
##### Workload supporting resources
**Self-hosted Database**
- In the air-gapped deployment model, _Coderd_ instance is unable to download
Postgres binaries from the internet, so external database must be provided.
**Container Registry**
- Since the _Registry_ is isolated from the internet, platform engineers are
responsible for maintaining Workspace container images and conducting periodic
updates of base Docker images.
- It is recommended to keep [Dev Containers](../templates/dev-containers.md) up
to date with the latest released
[Envbuilder](https://github.com/coder/envbuilder) runtime.
**Mirror of Terraform Registry**
- Stores all necessary Terraform plugin dependencies, ensuring successful
workspace provisioning and maintenance without internet access.
- Platform engineers are responsible for periodically updating the mirrored
Terraform plugins, including
[terraform-provider-coder](https://github.com/coder/terraform-provider-coder).
**Certificate Authority**
- Manages and issues TLS certificates to facilitate secure communication
channels within the infrastructure.
### Dev Containers
This architecture enhances a Coder workspace with a
[development container](https://containers.dev/) setup built using the
[envbuilder](https://github.com/coder/envbuilder) project. Workspace users have
the flexibility to extend generic, base developer environments with custom,
project-oriented [features](https://containers.dev/features) without requiring
platform administrators to push altered Docker images.
Learn more about
[Dev containers support](https://coder.com/docs/templates/dev-containers) in
Coder.
![Architecture Diagram](../images/architecture-devcontainers.png)
#### Components
The deployment model includes:
- _Workspace_ built using Coder template with _envbuilder_ enabled to set up the
developer environment accordingly to the dev container spec.
- _Container Registry_ for Docker images used by _envbuilder_, maintained by
Coder platform engineers or developer productivity engineers.
Since this model is strictly focused on workspace nodes, it does not affect the
setup of regional infrastructure. It can be deployed alongside other deployment
models, in multiple regions, or across various cloud platforms.
##### Workload resources
**Coder workspace**
- Docker and Kubernetes based templates are supported.
- The `docker_container` resource uses `ghcr.io/coder/envbuilder` as the base
image.
_Envbuilder_ checks out the base Docker image from the container registry and
installs selected features as specified in the `devcontainer.json` on top.
Eventually, it starts the container with the developer environment.
##### Workload supporting resources
**Container Registry (optional)**
- Workspace nodes need access to the Container Registry to check out images. To
shorten the provisioning time, it is recommended to deploy registry mirrors in
the same region as the workspace nodes.

0
docs/changelogs/README.md → docs/changelogs/index.md
View File

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

@ -61,12 +61,16 @@ ben@coder.com!
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/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/admin/auth#group-sync-enterprise-premium)
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)
<!-- markdown-link-check-disable -->
- [OIDC Role Sync](https://coder.com/docs/admin/users/oidc-auth.md#group-sync-enterprise-premium)
(Enterprise): Sync roles from your OIDC provider to Coder roles (e.g.
`Template Admin`) (#8595) (@Emyrk)
<!-- markdown-link-check-enable -->
- 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)
@ -82,7 +86,7 @@ ben@coder.com!
- CLI: Added `--var` shorthand for `--variable` in
`coder templates <create/push>` CLI (#8710) (@ammario)
- Sever logs: Added fine-grained
[filtering](https://coder.com/docs/cli/server#-l---log-filter) with
[filtering](https://coder.com/docs/reference/cli/server#-l---log-filter) with
Regex (#8748) (@ammario)
- d3991fac2 feat(coderd): add parameter insights to template insights (#8656)
(@mafredri)

9
docs/changelogs/v2.1.5.md
View File

@ -17,7 +17,7 @@
[display apps](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#nested-schema-for-display_apps)
in your template, such as VS Code (Insiders), web terminal, SSH, etc. (#9100)
(@sreya) To add VS Code insiders into your template, you can set:
```hcl
```tf
display_apps {
vscode_insiders = true
}
@ -51,9 +51,12 @@
### Documentation
<!-- markdown-link-check-disable -->
- Add
[JetBrains Gateway Offline Mode](https://coder.com/docs/ides/gateway#jetbrains-gateway-in-an-offline-environment)
config steps (#9388) (@ericpaulsen)
[JetBrains Gateway Offline Mode](https://coder.com/docs/user-guides/workspace-access/jetbrains.md#jetbrains-gateway-in-an-offline-environment)
config steps (#9388) (@ericpaulsen)
<!-- markdown-link-check-enable -->
- Describe
[dynamic options and locals for parameters](https://github.com/coder/coder/tree/main/examples/parameters-dynamic-options)
(#9429) (@mtojek)

2
docs/changelogs/v2.9.0.md
View File

@ -133,7 +133,7 @@ The following features are hidden or disabled by default as we don't guarantee s
### Documentation
- Fix /audit & /insights params (#12043) (@ericpaulsen)
- Fix jetbrains reconnect faq (#12073) (@ericpaulsen)
- Fix JetBrains gateway reconnect faq (#12073) (@ericpaulsen)
- Update modules documentation (#11911) (@matifali)
- Add kubevirt coder template in list of community templates (#12113) (@sulo1337)
- Describe resource ordering in UI (#12185) (@mtojek)

99
docs/ides.md
View File

@ -1,99 +0,0 @@
# IDEs
The following desktop IDEs have been tested with Coder, though any IDE with SSH
support should work:
- [Visual Studio Code](#visual-studio-code)
- [JetBrains with Gateway](./ides/gateway.md)
- IntelliJ IDEA
- CLion
- GoLand
- PyCharm
- Rider
- RubyMine
- WebStorm
- [JetBrains Fleet](./ides/fleet.md)
- Web IDEs (code-server, JupyterLab, JetBrains Projector)
- Note: These are [configured in the template](./ides/web-ides.md)
- [Emacs](./ides/emacs-tramp.md)
## 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.
![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).
> 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.
```text
ext install coder.coder-remote
```
Alternatively, manually install the VSIX from the
[latest release](https://github.com/coder/vscode-coder/releases/latest).
## SSH configuration
> Before proceeding, run `coder login <accessURL>` if you haven't already to
> authenticate the CLI with the web UI and your workspaces.
To access Coder via SSH, run the following in the terminal:
```shell
coder config-ssh
```
> Run `coder config-ssh --dry-run` if you'd like to see the changes that will be
> made before proceeding.
Confirm that you want to continue by typing **yes** and pressing enter. If
successful, you'll see the following message:
```console
You should now be able to ssh into your workspace.
For example, try running:
$ ssh coder.<workspaceName>
```
Your workspace is now accessible via `ssh coder.<workspace_name>` (e.g.,
`ssh coder.myEnv` if your workspace is named `myEnv`).
## JetBrains Gateway
Gateway operates in a client-server model, using an SSH connection to the remote
host to install and start the server.
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)
| Version | Status | Notes |
| --------- | ------- | -------------------------------------------------------- |
| 2021.3.2 | Working | |
| 2022.1.4 | Working | Windows clients are unable to connect to Linux workspace |
| 2022.2 RC | Working | Version >= 222.3345.108 |
## 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).
## Up next
- Learn about [Port Forwarding](./networking/port-forwarding.md)

25
docs/ides/fleet.md
View File

@ -1,25 +0,0 @@
# JetBrains Fleet
JetBrains Fleet is a code editor and lightweight IDE designed to support various
programming languages and development environments.
[See JetBrains' website to learn about Fleet](https://www.jetbrains.com/fleet/)
Fleet can connect to a Coder workspace by following these steps.
1. [Install Fleet](https://www.jetbrains.com/fleet/download)
2. Install Coder CLI
```shell
curl -L https://coder.com/install.sh | sh
```
3. Login and configure Coder SSH.
```shell
coder login coder.example.com
coder config-ssh
```
4. Connect via SSH with the Host set to `coder.workspace-name`
![Fleet Connect to Coder](../images/fleet/ssh-connect-to-coder.png)
> 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).

Some files were not shown because too many files have changed in this diff Show More