mirror of
https://github.com/coder/coder.git
synced 2026-10-16 14:48:56 +08:00
docs(docs/admin): reformat setup and integrations docs to one sentence per line (#30704)
Reformats the setup and integrations docs under `docs/admin/setup` and `docs/admin/integrations` to one sentence per line, as the [docs style guide](https://github.com/coder/coder/blob/main/docs/.style/style-guide/formatting.md#one-sentence-per-line) requires. Hard-wrapped paragraphs are unwrapped and lines holding several sentences are split, so a later edit to one sentence shows up as a one-line diff. Apart from the exception below, only whitespace inside paragraphs and list items changes, and the rendered pages are the same. Comparing the changed files against `main` word for word, ignoring whitespace and blockquote `>` markers, finds differences only on the reworded lines. `git diff --word-diff` is easier to read than the line diff. 1 lines that already contained an em or en dash were reworded by hand, because `lint/emdash` treats every reflowed line as newly added. Each uses a parenthetical, a separate sentence, or a colon after a lead-in. Dashes on lines the reflow did not touch are left alone. Applied with an in-progress formatter, limited to pages listed in `docs/manifest.json` and excluding generated reference docs. This is one of a batch of PRs that split the docs by area (25 files changed, 380 insertions(+), 572 deletions(-)). --- 🤖 Built with AI assistance.
This commit is contained in:
Nick Vigilante
@@ -2,15 +2,11 @@
|
||||
title: Add an Envbuilder template
|
||||
---
|
||||
|
||||
A Coder administrator adds an Envbuilder-compatible template to Coder. This
|
||||
allows the template to prompt the developer for their dev container repository's
|
||||
URL as a [parameter](../../../templates/extending-templates/parameters.md) when they create
|
||||
their workspace. Envbuilder clones the repo and builds a container from the
|
||||
`devcontainer.json` specified in the repo.
|
||||
A Coder administrator adds an Envbuilder-compatible template to Coder.
|
||||
This allows the template to prompt the developer for their dev container repository's URL as a [parameter](../../../templates/extending-templates/parameters.md) when they create their workspace.
|
||||
Envbuilder clones the repo and builds a container from the `devcontainer.json` specified in the repo.
|
||||
|
||||
You can create template files through the Coder dashboard, CLI, or you can
|
||||
choose a template from the
|
||||
[Coder registry](https://registry.coder.com/templates):
|
||||
You can create template files through the Coder dashboard, CLI, or you can choose a template from the [Coder registry](https://registry.coder.com/templates):
|
||||
|
||||
<div class="tabs">
|
||||
|
||||
@@ -31,8 +27,7 @@ choose a template from the
|
||||
coder template init --id kubernetes-devcontainer
|
||||
```
|
||||
|
||||
A list of available templates is shown in the
|
||||
[templates_init](../../../../reference/cli/templates/index.md) reference.
|
||||
A list of available templates is shown in the [templates_init](../../../../reference/cli/templates/index.md) reference.
|
||||
|
||||
1. `cd` into the directory and push the template to your Coder deployment:
|
||||
|
||||
@@ -40,13 +35,11 @@ choose a template from the
|
||||
cd kubernetes-devcontainer && coder templates push
|
||||
```
|
||||
|
||||
You can also edit the files or make changes to the files before you push them
|
||||
to Coder.
|
||||
You can also edit the files or make changes to the files before you push them to Coder.
|
||||
|
||||
## Registry
|
||||
|
||||
1. Go to the [Coder registry](https://registry.coder.com/templates) and select a
|
||||
dev container-compatible template.
|
||||
1. Go to the [Coder registry](https://registry.coder.com/templates) and select a dev container-compatible template.
|
||||
|
||||
1. Copy the files to your local device, then edit them to fit your needs.
|
||||
|
||||
@@ -62,8 +55,8 @@ choose a template from the
|
||||
|
||||
1. Create a `.zip` of the template files:
|
||||
|
||||
- On Mac or Windows, highlight the files and then right click. A
|
||||
"compress" option is available through the right-click context menu.
|
||||
- On Mac or Windows, highlight the files and then right click.
|
||||
A "compress" option is available through the right-click context menu.
|
||||
|
||||
- To zip the files through the command line:
|
||||
|
||||
@@ -76,27 +69,21 @@ choose a template from the
|
||||
|
||||
|
||||
|
||||
1. Drag the `.zip` file into the **Upload template** section and fill out the
|
||||
details, then select **Create template**.
|
||||
1. Drag the `.zip` file into the **Upload template** section and fill out the details, then select **Create template**.
|
||||
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
To set variables such as the namespace, go to the template in your Coder
|
||||
dashboard and select **Settings** from the **⋮** (vertical ellipsis) menu:
|
||||
To set variables such as the namespace, go to the template in your Coder dashboard and select **Settings** from the **⋮** (vertical ellipsis) menu:
|
||||
|
||||
<img height="255px" src="../../../../images/templates/template-menu-settings.png" alt="Choose Settings from the template's menu" align="center" />
|
||||
|
||||
## Envbuilder Terraform provider
|
||||
|
||||
When using the
|
||||
[Envbuilder Terraform provider](https://registry.terraform.io/providers/coder/envbuilder/latest/docs),
|
||||
a previously built and cached image can be reused directly, allowing dev
|
||||
containers to start instantaneously.
|
||||
When using the [Envbuilder Terraform provider](https://registry.terraform.io/providers/coder/envbuilder/latest/docs), a previously built and cached image can be reused directly, allowing dev containers to start instantaneously.
|
||||
|
||||
Developers can edit the `devcontainer.json` in their workspace to customize
|
||||
their development environments:
|
||||
Developers can edit the `devcontainer.json` in their workspace to customize their development environments:
|
||||
|
||||
```json
|
||||
# …
|
||||
@@ -117,17 +104,14 @@ their development environments:
|
||||
| [Google Compute Engine dev container](../../../../../examples/templates/gcp-devcontainer) | Runs a development container inside a single GCP instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |
|
||||
| [AWS EC2 dev container](../../../../../examples/templates/aws-devcontainer) | Runs a development container inside a single EC2 instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |
|
||||
|
||||
Your template can prompt the user for a repo URL with
|
||||
[parameters](../../../templates/extending-templates/parameters.md):
|
||||
Your template can prompt the user for a repo URL with [parameters](../../../templates/extending-templates/parameters.md):
|
||||
|
||||
|
||||
|
||||
## Dev container lifecycle scripts
|
||||
|
||||
The `onCreateCommand`, `updateContentCommand`, `postCreateCommand`, and
|
||||
`postStartCommand` lifecycle scripts are run each time the container is started.
|
||||
This could be used, for example, to fetch or update project dependencies before
|
||||
a user begins using the workspace.
|
||||
The `onCreateCommand`, `updateContentCommand`, `postCreateCommand`, and `postStartCommand` lifecycle scripts are run each time the container is started.
|
||||
This could be used, for example, to fetch or update project dependencies before a user begins using the workspace.
|
||||
|
||||
Lifecycle scripts are managed by project developers.
|
||||
|
||||
|
||||
+5
-12
@@ -7,21 +7,14 @@ title: Envbuilder releases and known issues
|
||||
Envbuilder provides two release channels:
|
||||
|
||||
- **Stable**
|
||||
- Available at
|
||||
[`ghcr.io/coder/envbuilder`](https://github.com/coder/envbuilder/pkgs/container/envbuilder).
|
||||
- Available at [`ghcr.io/coder/envbuilder`](https://github.com/coder/envbuilder/pkgs/container/envbuilder).
|
||||
Tags `>=1.0.0` are considered stable.
|
||||
- **Preview**
|
||||
- Available at
|
||||
[`ghcr.io/coder/envbuilder-preview`](https://github.com/coder/envbuilder/pkgs/container/envbuilder-preview).
|
||||
Built from the tip of `main`, and should be considered experimental and
|
||||
prone to breaking changes.
|
||||
- Available at [`ghcr.io/coder/envbuilder-preview`](https://github.com/coder/envbuilder/pkgs/container/envbuilder-preview).
|
||||
Built from the tip of `main`, and should be considered experimental and prone to breaking changes.
|
||||
|
||||
Refer to the
|
||||
[Envbuilder GitHub repository](https://github.com/coder/envbuilder/) for more
|
||||
information and to submit feature requests or bug reports.
|
||||
Refer to the [Envbuilder GitHub repository](https://github.com/coder/envbuilder/) for more information and to submit feature requests or bug reports.
|
||||
|
||||
## Known issues
|
||||
|
||||
Visit the
|
||||
[Envbuilder repository](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md)
|
||||
for a full list of supported features and known issues.
|
||||
Visit the [Envbuilder repository](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md) for a full list of supported features and known issues.
|
||||
|
||||
@@ -2,65 +2,47 @@
|
||||
title: Envbuilder security and caching
|
||||
---
|
||||
|
||||
Ensure Envbuilder can only pull pre-approved images and artifacts by configuring
|
||||
it with your existing HTTP proxies, firewalls, and artifact managers.
|
||||
Ensure Envbuilder can only pull pre-approved images and artifacts by configuring it with your existing HTTP proxies, firewalls, and artifact managers.
|
||||
|
||||
## Configure registry authentication
|
||||
|
||||
You may need to authenticate to your container registry, such as Artifactory, or
|
||||
Git provider such as GitLab, to use Envbuilder. See the
|
||||
[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/container-registry-auth.md)
|
||||
for more information.
|
||||
You may need to authenticate to your container registry, such as Artifactory, or Git provider such as GitLab, to use Envbuilder.
|
||||
See the [Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/container-registry-auth.md) for more information.
|
||||
|
||||
## Layer and image caching
|
||||
|
||||
To improve build times, dev containers can be cached. There are two main forms
|
||||
of caching:
|
||||
To improve build times, dev containers can be cached.
|
||||
There are two main forms of caching:
|
||||
|
||||
- **Layer caching**
|
||||
|
||||
- Caches individual layers and pushes them to a remote registry. When building
|
||||
the image, Envbuilder will check the remote registry for pre-existing layers
|
||||
These will be fetched and extracted to disk instead of building the layers
|
||||
from scratch.
|
||||
- Caches individual layers and pushes them to a remote registry.
|
||||
When building the image, Envbuilder will check the remote registry for pre-existing layers These will be fetched and extracted to disk instead of building the layers from scratch.
|
||||
|
||||
- **Image caching**
|
||||
|
||||
- Caches the entire image, skipping the build process completely (except for
|
||||
post-build
|
||||
[lifecycle scripts](./add-envbuilder.md#dev-container-lifecycle-scripts)).
|
||||
- Caches the entire image, skipping the build process completely (except for post-build [lifecycle scripts](./add-envbuilder.md#dev-container-lifecycle-scripts)).
|
||||
|
||||
Note that caching requires push access to a registry, and may require approval
|
||||
from relevant infrastructure team(s).
|
||||
Note that caching requires push access to a registry, and may require approval from relevant infrastructure team(s).
|
||||
|
||||
Refer to the
|
||||
[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/caching.md)
|
||||
for more information about Envbuilder and caching.
|
||||
Refer to the [Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/caching.md) for more information about Envbuilder and caching.
|
||||
|
||||
Visit the
|
||||
[speed up templates](../../../../tutorials/best-practices/speed-up-templates.md)
|
||||
best practice documentation for more ways that you can speed up build times.
|
||||
Visit the [speed up templates](../../../../tutorials/best-practices/speed-up-templates.md) best practice documentation for more ways that you can speed up build times.
|
||||
|
||||
### Image caching
|
||||
|
||||
To support resuming from a cached image, use the
|
||||
[Envbuilder Terraform Provider](https://github.com/coder/terraform-provider-envbuilder)
|
||||
in your template. The provider will:
|
||||
To support resuming from a cached image, use the [Envbuilder Terraform Provider](https://github.com/coder/terraform-provider-envbuilder) in your template.
|
||||
The provider will:
|
||||
|
||||
1. Clone the remote Git repository,
|
||||
1. Perform a "dry-run" build of the dev container in the same manner as
|
||||
Envbuilder would,
|
||||
1. Check for the presence of a previously built image in the provided cache
|
||||
repository,
|
||||
1. Perform a "dry-run" build of the dev container in the same manner as Envbuilder would,
|
||||
1. Check for the presence of a previously built image in the provided cache repository,
|
||||
1. Output the image remote reference in SHA256 form, if it finds one.
|
||||
|
||||
The example templates listed above will use the provider if a remote cache
|
||||
repository is provided.
|
||||
The example templates listed above will use the provider if a remote cache repository is provided.
|
||||
|
||||
If you are building your own Dev container template, you can consult the
|
||||
[provider documentation](https://registry.terraform.io/providers/coder/envbuilder/latest/docs/resources/cached_image).
|
||||
You may also wish to consult a
|
||||
[documented example usage of the `envbuilder_cached_image` resource](https://github.com/coder/terraform-provider-envbuilder/blob/main/examples/resources/envbuilder_cached_image/envbuilder_cached_image_resource.tf).
|
||||
If you are building your own Dev container template, you can consult the [provider documentation](https://registry.terraform.io/providers/coder/envbuilder/latest/docs/resources/cached_image).
|
||||
You may also wish to consult a [documented example usage of the `envbuilder_cached_image` resource](https://github.com/coder/terraform-provider-envbuilder/blob/main/examples/resources/envbuilder_cached_image/envbuilder_cached_image_resource.tf).
|
||||
|
||||
## Next steps
|
||||
|
||||
|
||||
@@ -2,52 +2,34 @@
|
||||
title: Envbuilder
|
||||
---
|
||||
|
||||
Envbuilder is an open-source tool that builds development environments from
|
||||
[dev container](https://containers.dev/implementors/spec/) configuration files.
|
||||
Unlike the [Dev Containers integration](../integration.md),
|
||||
Envbuilder transforms the workspace image itself rather than running containers
|
||||
inside the workspace.
|
||||
Envbuilder is an open-source tool that builds development environments from [dev container](https://containers.dev/implementors/spec/) configuration files.
|
||||
Unlike the [Dev Containers integration](../integration.md), Envbuilder transforms the workspace image itself rather than running containers inside the workspace.
|
||||
|
||||
Envbuilder is well-suited for Kubernetes-native deployments without privileged
|
||||
containers, environments where Docker is unavailable or restricted, and
|
||||
workflows where administrators need infrastructure-level control over image
|
||||
builds, caching, and security scanning. For workspaces with Docker available,
|
||||
the [Dev Containers Integration](../integration.md) offers container management
|
||||
with dashboard visibility and multi-container support.
|
||||
Envbuilder is well-suited for Kubernetes-native deployments without privileged containers, environments where Docker is unavailable or restricted, and workflows where administrators need infrastructure-level control over image builds, caching, and security scanning.
|
||||
For workspaces with Docker available, the [Dev Containers Integration](../integration.md) offers container management with dashboard visibility and multi-container support.
|
||||
|
||||
Dev containers provide developers with increased autonomy and control over their
|
||||
Coder cloud development environments.
|
||||
Dev containers provide developers with increased autonomy and control over their Coder cloud development environments.
|
||||
|
||||
By using dev containers, developers can customize their workspaces with tools
|
||||
pre-approved by platform teams in registries like
|
||||
[JFrog Artifactory](../../jfrog-artifactory.md). This simplifies
|
||||
workflows, reduces the need for tickets and approvals, and promotes greater
|
||||
independence for developers.
|
||||
By using dev containers, developers can customize their workspaces with tools pre-approved by platform teams in registries like [JFrog Artifactory](../../jfrog-artifactory.md).
|
||||
This simplifies workflows, reduces the need for tickets and approvals, and promotes greater independence for developers.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
An administrator should construct or choose a base image and create a template
|
||||
that includes a `devcontainer_builder` image before a developer team configures
|
||||
dev containers.
|
||||
An administrator should construct or choose a base image and create a template that includes a `devcontainer_builder` image before a developer team configures dev containers.
|
||||
|
||||
## Devcontainer Features
|
||||
|
||||
[Dev container Features](https://containers.dev/implementors/features/) allow
|
||||
owners of a project to specify self-contained units of code and runtime
|
||||
configuration that can be composed together on top of an existing base image.
|
||||
This is a good place to install project-specific tools, such as
|
||||
language-specific runtimes and compilers.
|
||||
[Dev container Features](https://containers.dev/implementors/features/) allow owners of a project to specify self-contained units of code and runtime configuration that can be composed together on top of an existing base image.
|
||||
This is a good place to install project-specific tools, such as language-specific runtimes and compilers.
|
||||
|
||||
## Coder Envbuilder
|
||||
|
||||
[Envbuilder](https://github.com/coder/envbuilder/) is an open-source project
|
||||
maintained by Coder that runs dev containers via Coder templates and your
|
||||
underlying infrastructure. Envbuilder can run on Docker or Kubernetes.
|
||||
[Envbuilder](https://github.com/coder/envbuilder/) is an open-source project maintained by Coder that runs dev containers via Coder templates and your underlying infrastructure.
|
||||
Envbuilder can run on Docker or Kubernetes.
|
||||
|
||||
It is independently packaged and versioned from the centralized Coder
|
||||
open-source project. This means that Envbuilder can be used with Coder, but it
|
||||
is not required. It also means that dev container builds can scale independently
|
||||
of the Coder control plane and even run within a CI/CD pipeline.
|
||||
It is independently packaged and versioned from the centralized Coder open-source project.
|
||||
This means that Envbuilder can be used with Coder, but it is not required.
|
||||
It also means that dev container builds can scale independently of the Coder control plane and even run within a CI/CD pipeline.
|
||||
|
||||
## Next steps
|
||||
|
||||
|
||||
@@ -2,28 +2,25 @@
|
||||
title: Dev Containers
|
||||
---
|
||||
|
||||
Dev containers allow developers to define their development environment
|
||||
as code using the [Dev Container specification](https://containers.dev/).
|
||||
Configuration lives in a `devcontainer.json` file alongside source code,
|
||||
enabling consistent, reproducible environments.
|
||||
Dev containers allow developers to define their development environment as code using the [Dev Container specification](https://containers.dev/).
|
||||
Configuration lives in a `devcontainer.json` file alongside source code, enabling consistent, reproducible environments.
|
||||
|
||||
By adopting dev containers, organizations can:
|
||||
|
||||
- **Standardize environments**: Eliminate "works on my machine" issues while
|
||||
still allowing developers to customize their tools within approved boundaries.
|
||||
- **Scale efficiently**: Let developers maintain their own environment
|
||||
definitions, reducing the burden on platform teams.
|
||||
- **Improve security**: Use hardened base images and controlled package
|
||||
registries to enforce security policies while enabling developer self-service.
|
||||
- **Standardize environments**:
|
||||
Eliminate "works on my machine" issues while still allowing developers to customize their tools within approved boundaries.
|
||||
- **Scale efficiently**:
|
||||
Let developers maintain their own environment definitions, reducing the burden on platform teams.
|
||||
- **Improve security**:
|
||||
Use hardened base images and controlled package registries to enforce security policies while enabling developer self-service.
|
||||
|
||||
Coder supports two approaches for running dev containers. Choose based on your
|
||||
infrastructure and workflow requirements.
|
||||
Coder supports two approaches for running dev containers.
|
||||
Choose based on your infrastructure and workflow requirements.
|
||||
|
||||
## Dev Containers Integration
|
||||
|
||||
The Dev Containers Integration uses the standard `@devcontainers/cli` and Docker
|
||||
to run containers inside your workspace. This is the recommended approach for
|
||||
most use cases.
|
||||
The Dev Containers Integration uses the standard `@devcontainers/cli` and Docker to run containers inside your workspace.
|
||||
This is the recommended approach for most use cases.
|
||||
|
||||
**Best for:**
|
||||
|
||||
@@ -33,14 +30,12 @@ most use cases.
|
||||
|
||||
[Configure Dev Containers Integration](./integration.md)
|
||||
|
||||
For user documentation, see the
|
||||
[Dev Containers user guide](../../../user-guides/devcontainers/index.md).
|
||||
For user documentation, see the [Dev Containers user guide](../../../user-guides/devcontainers/index.md).
|
||||
|
||||
## Envbuilder
|
||||
|
||||
Envbuilder transforms the workspace image itself from a `devcontainer.json`,
|
||||
rather than running containers inside the workspace. It does not require
|
||||
a Docker daemon.
|
||||
Envbuilder transforms the workspace image itself from a `devcontainer.json`, rather than running containers inside the workspace.
|
||||
It does not require a Docker daemon.
|
||||
|
||||
**Best for:**
|
||||
|
||||
|
||||
@@ -2,12 +2,10 @@
|
||||
title: Configure a template for Dev Containers
|
||||
---
|
||||
|
||||
This guide covers the Dev Containers Integration, which uses Docker. For
|
||||
environments without Docker, see [Envbuilder](./envbuilder/index.md) as an
|
||||
alternative.
|
||||
This guide covers the Dev Containers Integration, which uses Docker.
|
||||
For environments without Docker, see [Envbuilder](./envbuilder/index.md) as an alternative.
|
||||
|
||||
To enable Dev Containers in workspaces, configure your template with the Dev Containers
|
||||
modules and configurations outlined in this doc.
|
||||
To enable Dev Containers in workspaces, configure your template with the Dev Containers modules and configurations outlined in this doc.
|
||||
|
||||
Dev Containers are currently not supported in Windows or macOS workspaces.
|
||||
|
||||
@@ -17,8 +15,8 @@ There are two approaches to configuring Dev Containers in Coder:
|
||||
|
||||
### Manual Configuration
|
||||
|
||||
Use the [`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer) Terraform resource to explicitly define which Dev
|
||||
Containers should be started in your workspace. This approach provides:
|
||||
Use the [`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer) Terraform resource to explicitly define which Dev Containers should be started in your workspace.
|
||||
This approach provides:
|
||||
|
||||
- Predictable behavior and explicit control
|
||||
- Clear template configuration
|
||||
@@ -33,14 +31,11 @@ Alternatively, enable automatic discovery of Dev Containers in Git repositories.
|
||||
The agent scans for `devcontainer.json` files and surfaces them in the Coder UI.
|
||||
See [Environment Variables](#environment-variables) for configuration options.
|
||||
|
||||
This approach is useful when developers frequently switch between repositories
|
||||
or work with many projects, as it reduces template maintenance overhead.
|
||||
This approach is useful when developers frequently switch between repositories or work with many projects, as it reduces template maintenance overhead.
|
||||
|
||||
## Install the Dev Containers CLI
|
||||
|
||||
Use the
|
||||
[devcontainers-cli](https://registry.coder.com/modules/devcontainers-cli) module
|
||||
to ensure the `@devcontainers/cli` is installed in your workspace:
|
||||
Use the [devcontainers-cli](https://registry.coder.com/modules/devcontainers-cli) module to ensure the `@devcontainers/cli` is installed in your workspace:
|
||||
|
||||
```tf
|
||||
module "devcontainers-cli" {
|
||||
@@ -54,10 +49,7 @@ Alternatively, install the devcontainer CLI manually in your base image.
|
||||
|
||||
## Configure Automatic Dev Container Startup
|
||||
|
||||
The
|
||||
[`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer)
|
||||
resource automatically starts a Dev Container in your workspace, ensuring it's
|
||||
ready when you access the workspace:
|
||||
The [`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer) resource automatically starts a Dev Container in your workspace, ensuring it's ready when you access the workspace:
|
||||
|
||||
```tf
|
||||
resource "coder_devcontainer" "my-repository" {
|
||||
@@ -67,23 +59,18 @@ resource "coder_devcontainer" "my-repository" {
|
||||
}
|
||||
```
|
||||
|
||||
The `workspace_folder` attribute must point to a valid project folder containing
|
||||
a `devcontainer.json` file. Consider using the
|
||||
[`git-clone`](https://registry.coder.com/modules/git-clone) module to ensure
|
||||
your repository is cloned and ready for automatic startup.
|
||||
The `workspace_folder` attribute must point to a valid project folder containing a `devcontainer.json` file.
|
||||
Consider using the [`git-clone`](https://registry.coder.com/modules/git-clone) module to ensure your repository is cloned and ready for automatic startup.
|
||||
|
||||
For multi-repo workspaces, define multiple `coder_devcontainer` resources, each
|
||||
pointing to a different repository. Each one runs as a separate sub-agent with
|
||||
its own terminal and apps in the dashboard.
|
||||
For multi-repo workspaces, define multiple `coder_devcontainer` resources, each pointing to a different repository.
|
||||
Each one runs as a separate sub-agent with its own terminal and apps in the dashboard.
|
||||
|
||||
## Enable Dev Containers Integration
|
||||
|
||||
Dev Containers integration is **enabled by default** in Coder 2.24.0 and later.
|
||||
You don't need to set any environment variables unless you want to change the
|
||||
default behavior.
|
||||
You don't need to set any environment variables unless you want to change the default behavior.
|
||||
|
||||
If you need to explicitly disable Dev Containers, set the
|
||||
`CODER_AGENT_DEVCONTAINERS_ENABLE` environment variable to `false`:
|
||||
If you need to explicitly disable Dev Containers, set the `CODER_AGENT_DEVCONTAINERS_ENABLE` environment variable to `false`:
|
||||
|
||||
```tf
|
||||
resource "docker_container" "workspace" {
|
||||
@@ -97,16 +84,12 @@ resource "docker_container" "workspace" {
|
||||
}
|
||||
```
|
||||
|
||||
See the [Environment Variables](#environment-variables) section below for more
|
||||
details on available configuration options.
|
||||
See the [Environment Variables](#environment-variables) section below for more details on available configuration options.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
The following environment variables control Dev Container behavior in your
|
||||
workspace. Both `CODER_AGENT_DEVCONTAINERS_ENABLE` and
|
||||
`CODER_AGENT_DEVCONTAINERS_PROJECT_DISCOVERY_ENABLE` are **enabled by default**,
|
||||
so you typically don't need to set them unless you want to explicitly disable
|
||||
the feature.
|
||||
The following environment variables control Dev Container behavior in your workspace.
|
||||
Both `CODER_AGENT_DEVCONTAINERS_ENABLE` and `CODER_AGENT_DEVCONTAINERS_PROJECT_DISCOVERY_ENABLE` are **enabled by default**, so you typically don't need to set them unless you want to explicitly disable the feature.
|
||||
|
||||
### CODER_AGENT_DEVCONTAINERS_ENABLE
|
||||
|
||||
@@ -114,8 +97,8 @@ the feature.
|
||||
|
||||
Enables the Dev Containers integration in the Coder agent.
|
||||
|
||||
The Dev Containers feature is enabled by default. You can explicitly disable it
|
||||
by setting this to `false`.
|
||||
The Dev Containers feature is enabled by default.
|
||||
You can explicitly disable it by setting this to `false`.
|
||||
|
||||
### CODER_AGENT_DEVCONTAINERS_PROJECT_DISCOVERY_ENABLE
|
||||
|
||||
@@ -123,15 +106,12 @@ by setting this to `false`.
|
||||
|
||||
Enables automatic discovery of Dev Containers in Git repositories.
|
||||
|
||||
When enabled, the agent scans the configured working directory (set via the
|
||||
`directory` attribute in `coder_agent`, typically the user's home directory) for
|
||||
Git repositories. If the directory itself is a Git repository, it searches that
|
||||
project. Otherwise, it searches immediate subdirectories for Git repositories.
|
||||
When enabled, the agent scans the configured working directory (set via the `directory` attribute in `coder_agent`, typically the user's home directory) for Git repositories.
|
||||
If the directory itself is a Git repository, it searches that project.
|
||||
Otherwise, it searches immediate subdirectories for Git repositories.
|
||||
|
||||
For each repository found, the agent looks for `devcontainer.json` files in the
|
||||
[standard locations](../../../user-guides/devcontainers/index.md#add-a-devcontainerjson)
|
||||
and surfaces discovered Dev Containers in the Coder UI. Discovery respects
|
||||
`.gitignore` patterns.
|
||||
For each repository found, the agent looks for `devcontainer.json` files in the [standard locations](../../../user-guides/devcontainers/index.md#add-a-devcontainerjson) and surfaces discovered Dev Containers in the Coder UI.
|
||||
Discovery respects `.gitignore` patterns.
|
||||
|
||||
Set to `false` if you prefer explicit configuration via `coder_devcontainer`.
|
||||
|
||||
@@ -141,19 +121,13 @@ Set to `false` if you prefer explicit configuration via `coder_devcontainer`.
|
||||
|
||||
Automatically starts Dev Containers discovered via project discovery.
|
||||
|
||||
When enabled, discovered Dev Containers will be automatically built and started
|
||||
during workspace initialization. This only applies to Dev Containers found via
|
||||
project discovery. Dev Containers defined with the `coder_devcontainer` resource
|
||||
always auto-start regardless of this setting.
|
||||
When enabled, discovered Dev Containers will be automatically built and started during workspace initialization.
|
||||
This only applies to Dev Containers found via project discovery.
|
||||
Dev Containers defined with the `coder_devcontainer` resource always auto-start regardless of this setting.
|
||||
|
||||
## Attach Resources to Dev Containers
|
||||
|
||||
You can attach
|
||||
[`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app),
|
||||
[`coder_script`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script),
|
||||
and [`coder_env`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/env)
|
||||
resources to a `coder_devcontainer` by referencing its `subagent_id` attribute
|
||||
as the `agent_id`:
|
||||
You can attach [`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app), [`coder_script`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script), and [`coder_env`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/env) resources to a `coder_devcontainer` by referencing its `subagent_id` attribute as the `agent_id`:
|
||||
|
||||
```tf
|
||||
resource "coder_devcontainer" "my-repository" {
|
||||
@@ -181,53 +155,40 @@ resource "coder_env" "my-var" {
|
||||
}
|
||||
```
|
||||
|
||||
This also enables using [Coder registry](https://registry.coder.com) modules
|
||||
that depend on these resources inside dev containers, by passing the
|
||||
`subagent_id` as the module's `agent_id`.
|
||||
This also enables using [Coder registry](https://registry.coder.com) modules that depend on these resources inside dev containers, by passing the `subagent_id` as the module's `agent_id`.
|
||||
|
||||
### Terraform-managed dev containers
|
||||
|
||||
When a `coder_devcontainer` has any `coder_app`, `coder_script`, or `coder_env`
|
||||
resource attached, it becomes a **terraform-managed** dev container. This
|
||||
changes how Coder handles the sub-agent:
|
||||
When a `coder_devcontainer` has any `coder_app`, `coder_script`, or `coder_env` resource attached, it becomes a **terraform-managed** dev container.
|
||||
This changes how Coder handles the sub-agent:
|
||||
|
||||
- The sub-agent is pre-defined during Terraform provisioning rather than created
|
||||
dynamically.
|
||||
- On dev container configuration changes, Coder updates the sub-agent in-place
|
||||
instead of deleting and recreating it.
|
||||
- The sub-agent is pre-defined during Terraform provisioning rather than created dynamically.
|
||||
- On dev container configuration changes, Coder updates the sub-agent in-place instead of deleting and recreating it.
|
||||
|
||||
### Interaction with devcontainer.json customizations
|
||||
|
||||
Terraform-defined resources and
|
||||
[`devcontainer.json` customizations](../../../user-guides/devcontainers/customizing-dev-containers.md)
|
||||
work together with some limitations. The `displayApps` settings from
|
||||
`devcontainer.json` are applied to terraform-managed dev containers, so you can
|
||||
control built-in app visibility (e.g., hide VS Code Insiders) via
|
||||
`devcontainer.json` even when using Terraform resources.
|
||||
Terraform-defined resources and [`devcontainer.json` customizations](../../../user-guides/devcontainers/customizing-dev-containers.md) work together with some limitations.
|
||||
The `displayApps` settings from `devcontainer.json` are applied to terraform-managed dev containers, so you can control built-in app visibility (e.g., hide VS Code Insiders) via `devcontainer.json` even when using Terraform resources.
|
||||
|
||||
However, custom `apps` defined in `devcontainer.json` are **not applied** to
|
||||
terraform-managed dev containers. If you need custom apps, define them as
|
||||
`coder_app` resources in Terraform instead.
|
||||
However, custom `apps` defined in `devcontainer.json` are **not applied** to terraform-managed dev containers.
|
||||
If you need custom apps, define them as `coder_app` resources in Terraform instead.
|
||||
|
||||
## Per-Container Customizations
|
||||
|
||||
Developers can customize individual dev containers using the `customizations.coder`
|
||||
block in their `devcontainer.json` file. Available options include:
|
||||
Developers can customize individual dev containers using the `customizations.coder` block in their `devcontainer.json` file.
|
||||
Available options include:
|
||||
|
||||
- `ignore` — Hide a dev container from Coder completely
|
||||
- `autoStart` — Control whether the container starts automatically (requires
|
||||
`CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE` to be enabled)
|
||||
- `autoStart`: Control whether the container starts automatically (requires `CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE` to be enabled)
|
||||
- `name` — Set a custom agent name
|
||||
- `displayApps` — Control which built-in apps appear
|
||||
- `apps` — Define custom applications
|
||||
|
||||
For the full reference, see
|
||||
[Customizing dev containers](../../../user-guides/devcontainers/customizing-dev-containers.md).
|
||||
For the full reference, see [Customizing dev containers](../../../user-guides/devcontainers/customizing-dev-containers.md).
|
||||
|
||||
## Complete Template Example
|
||||
|
||||
Here's a simplified template example that uses Dev Containers with manual
|
||||
configuration:
|
||||
Here's a simplified template example that uses Dev Containers with manual configuration:
|
||||
|
||||
```tf
|
||||
terraform {
|
||||
@@ -276,8 +237,8 @@ resource "coder_env" "env" {
|
||||
|
||||
### Alternative: Project Discovery with Autostart
|
||||
|
||||
By default, discovered containers appear in the dashboard but developers must
|
||||
manually start them. To have them start automatically, enable autostart:
|
||||
By default, discovered containers appear in the dashboard but developers must manually start them.
|
||||
To have them start automatically, enable autostart:
|
||||
|
||||
```tf
|
||||
resource "docker_container" "workspace" {
|
||||
@@ -295,22 +256,18 @@ resource "docker_container" "workspace" {
|
||||
|
||||
With autostart enabled:
|
||||
|
||||
- Discovered containers automatically build and start during workspace
|
||||
initialization
|
||||
- Discovered containers automatically build and start during workspace initialization
|
||||
- The `coder_devcontainer` resource is not required
|
||||
- Developers can work with multiple projects seamlessly
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> When using project discovery, you still need to install the devcontainers CLI
|
||||
> using the module or in your base image.
|
||||
> When using project discovery, you still need to install the devcontainers CLI using the module or in your base image.
|
||||
|
||||
## Example Template
|
||||
|
||||
The [Docker (Dev Containers)](../../../../examples/templates/docker-devcontainer)
|
||||
starter template demonstrates Dev Containers integration using Docker-in-Docker.
|
||||
It includes the `devcontainers-cli` module, `git-clone` module, and the
|
||||
`coder_devcontainer` resource.
|
||||
The [Docker (Dev Containers)](../../../../examples/templates/docker-devcontainer) starter template demonstrates Dev Containers integration using Docker-in-Docker.
|
||||
It includes the `devcontainers-cli` module, `git-clone` module, and the `coder_devcontainer` resource.
|
||||
|
||||
## Next Steps
|
||||
|
||||
|
||||
@@ -2,18 +2,15 @@
|
||||
title: DX
|
||||
---
|
||||
|
||||
[DX](https://getdx.com) is a developer intelligence platform used by engineering
|
||||
leaders and platform engineers.
|
||||
[DX](https://getdx.com) is a developer intelligence platform used by engineering leaders and platform engineers.
|
||||
|
||||
DX uses metadata attributes to assign information to individual users.
|
||||
While it's common to segment users by `role`, `level`, or `geo`, it’s become increasingly
|
||||
common to use DX attributes to better understand usage and adoption of tools.
|
||||
While it's common to segment users by `role`, `level`, or `geo`, it’s become increasingly common to use DX attributes to better understand usage and adoption of tools.
|
||||
|
||||
You can create a `Coder` attribute in DX to segment and analyze the impact of Coder usage on a developer’s work, including:
|
||||
|
||||
- Understanding the needs of power users or low Coder usage across the org
|
||||
- Correlate Coder usage with qualitative and quantitative engineering metrics,
|
||||
such as PR throughput, deployment frequency, deep work, dev environment toil, and more.
|
||||
- Correlate Coder usage with qualitative and quantitative engineering metrics, such as PR throughput, deployment frequency, deep work, dev environment toil, and more.
|
||||
- Personalize user experiences
|
||||
|
||||
## Requirements
|
||||
|
||||
@@ -2,13 +2,12 @@
|
||||
title: 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 diagram](../../install/plan/architecture.md) for more details.
|
||||
Coder is highly extensible and is not limited to the platforms outlined in these docs.
|
||||
The control plane can be provisioned on any VM or container compute, and workspaces can include any Terraform resource.
|
||||
See our [architecture diagram](../../install/plan/architecture.md) for more details.
|
||||
|
||||
You can host your deployment on almost any infrastructure. To learn how, read
|
||||
our [installation guides](../../install/index.md).
|
||||
You can host your deployment on almost any infrastructure.
|
||||
To learn how, read our [installation guides](../../install/index.md).
|
||||
|
||||
<children></children>
|
||||
|
||||
|
||||
@@ -11,39 +11,30 @@ April 24, 2024
|
||||
|
||||
---
|
||||
|
||||
[Island](https://www.island.io/) is an enterprise-grade browser, offering a Chromium-based experience
|
||||
similar to popular web browsers like Chrome and Edge. It includes built-in
|
||||
security features for corporate applications and data, aiming to bridge the gap
|
||||
between consumer-focused browsers and the security needs of the enterprise.
|
||||
[Island](https://www.island.io/) is an enterprise-grade browser, offering a Chromium-based experience similar to popular web browsers like Chrome and Edge.
|
||||
It includes built-in security features for corporate applications and data, aiming to bridge the gap between consumer-focused browsers and the security needs of the enterprise.
|
||||
|
||||
Coder natively integrates with Island's feature set, which include data
|
||||
loss protection (DLP), application awareness, browser session recording, and
|
||||
single sign-on (SSO). This guide intends to document these feature categories
|
||||
and how they apply to your Coder deployment.
|
||||
Coder natively integrates with Island's feature set, which include data loss protection (DLP), application awareness, browser session recording, and single sign-on (SSO).
|
||||
This guide intends to document these feature categories and how they apply to your Coder deployment.
|
||||
|
||||
## General Configuration
|
||||
|
||||
### Create an Application Group for Coder
|
||||
|
||||
We recommend creating an Application Group specific to Coder in the Island
|
||||
Management console. This Application Group object will be referenced when
|
||||
creating browser policies.
|
||||
We recommend creating an Application Group specific to Coder in the Island Management console.
|
||||
This Application Group object will be referenced when creating browser policies.
|
||||
|
||||
[See the Island documentation for creating an Application Group](https://documentation.island.io/docs/create-and-configure-an-application-group-object).
|
||||
|
||||
## Advanced Data Loss Protection
|
||||
|
||||
Integrate Island's advanced data loss prevention (DLP) capabilities with
|
||||
Coder's cloud development environment (CDE), enabling you to control the
|
||||
"last mile" between developers' CDE and their local devices,
|
||||
ensuring that sensitive IP remains in your centralized environment.
|
||||
Integrate Island's advanced data loss prevention (DLP) capabilities with Coder's cloud development environment (CDE), enabling you to control the "last mile" between developers' CDE and their local devices, ensuring that sensitive IP remains in your centralized environment.
|
||||
|
||||
### Block cut, copy, paste, printing, screen share
|
||||
|
||||
1. [Create a Data Sandbox Profile](https://documentation.island.io/docs/create-and-configure-a-data-sandbox-profile).
|
||||
|
||||
1. Configure the following actions to allow/block (based on your security
|
||||
requirements).
|
||||
1. Configure the following actions to allow/block (based on your security requirements).
|
||||
|
||||
- Screenshot and Screen Share
|
||||
- Printing
|
||||
@@ -54,17 +45,19 @@ ensuring that sensitive IP remains in your centralized environment.
|
||||
|
||||
1. Define the Coder Application group as the Destination Object.
|
||||
|
||||
1. Define the Data Sandbox Profile as the Action in the Last Mile Protection
|
||||
section.
|
||||
1. Define the Data Sandbox Profile as the Action in the Last Mile Protection section.
|
||||
|
||||
### Conditionally allow copy on Coder's CLI authentication page
|
||||
|
||||
1. [Create a URL Object](https://documentation.island.io/docs/create-and-configure-a-policy-rule-general) with the following configuration.
|
||||
|
||||
- **Include**
|
||||
- **URL type**: Wildcard
|
||||
- **URL address**: `coder.example.com/cli-auth`
|
||||
- **Casing**: Insensitive
|
||||
- **URL type**:
|
||||
Wildcard
|
||||
- **URL address**:
|
||||
`coder.example.com/cli-auth`
|
||||
- **Casing**:
|
||||
Insensitive
|
||||
|
||||
1. [Create a Data Sandbox Profile](https://documentation.island.io/docs/create-and-configure-a-data-sandbox-profile).
|
||||
|
||||
@@ -74,8 +67,7 @@ ensuring that sensitive IP remains in your centralized environment.
|
||||
|
||||
1. Define the URL Object you created as the Destination Object.
|
||||
|
||||
1. Define the Data Sandbox Profile as the Action in the Last Mile Protection
|
||||
section.
|
||||
1. Define the Data Sandbox Profile as the Action in the Last Mile Protection section.
|
||||
|
||||
### Prevent file upload/download from the browser
|
||||
|
||||
@@ -88,8 +80,7 @@ ensuring that sensitive IP remains in your centralized environment.
|
||||
|
||||
1. Define the Coder Application group as the Destination Object.
|
||||
|
||||
1. Define the applicable Protection Profile as the Action in the Data Protection
|
||||
section.
|
||||
1. Define the applicable Protection Profile as the Action in the Data Protection section.
|
||||
|
||||
### Scan files for sensitive data
|
||||
|
||||
@@ -103,9 +94,7 @@ ensuring that sensitive IP remains in your centralized environment.
|
||||
|
||||
## Application Awareness and Boundaries
|
||||
|
||||
Ensure that Coder is only accessed through the Island browser, guaranteeing that
|
||||
your browser-level DLP policies are always enforced, and developers can't
|
||||
sidestep such policies simply by using another browser.
|
||||
Ensure that Coder is only accessed through the Island browser, guaranteeing that your browser-level DLP policies are always enforced, and developers can't sidestep such policies simply by using another browser.
|
||||
|
||||
### Configure browser enforcement, conditional access policies
|
||||
|
||||
@@ -119,13 +108,12 @@ Note that the configured IdP must be the same for both Coder and Island.
|
||||
|
||||
## Browser Activity Logging
|
||||
|
||||
Govern and audit in-browser terminal and IDE sessions using Island, such as
|
||||
screenshots, mouse clicks, and keystrokes.
|
||||
Govern and audit in-browser terminal and IDE sessions using Island, such as screenshots, mouse clicks, and keystrokes.
|
||||
|
||||
### Activity Logging Module
|
||||
|
||||
1. [Create an Activity Logging Profile](https://documentation.island.io/docs/create-and-configure-an-activity-logging-profile). Supported browser
|
||||
events include:
|
||||
1. [Create an Activity Logging Profile](https://documentation.island.io/docs/create-and-configure-an-activity-logging-profile).
|
||||
Supported browser events include:
|
||||
|
||||
- Web Navigation
|
||||
- File Download
|
||||
@@ -141,17 +129,13 @@ screenshots, mouse clicks, and keystrokes.
|
||||
|
||||
1. Define the Coder Application group as the Destination Object.
|
||||
|
||||
1. Define the Activity Logging Profile as the Action in the Security &
|
||||
Visibility section.
|
||||
1. Define the Activity Logging Profile as the Action in the Security & Visibility section.
|
||||
|
||||
## Identity-aware logins (SSO)
|
||||
|
||||
Integrate Island's identity management system with Coder's
|
||||
authentication mechanisms to enable identity-aware logins.
|
||||
Integrate Island's identity management system with Coder's authentication mechanisms to enable identity-aware logins.
|
||||
|
||||
### Configure single sign-on (SSO) seamless authentication between Coder and Island
|
||||
|
||||
Configure the same identity provider (IdP) for both your Island and Coder
|
||||
deployment. Upon initial login to the Island browser, the user's session
|
||||
token will automatically be passed to Coder and authenticate their Coder
|
||||
session.
|
||||
Configure the same identity provider (IdP) for both your Island and Coder deployment.
|
||||
Upon initial login to the Island browser, the user's session token will automatically be passed to Coder and authenticate their Coder session.
|
||||
|
||||
@@ -2,16 +2,12 @@
|
||||
title: Integrate Coder with Istio
|
||||
---
|
||||
|
||||
Use Istio service mesh for your Coder workspace traffic to implement access
|
||||
controls, encrypt service-to-service communication, and gain visibility into
|
||||
your workspace network patterns. This guide walks through the required steps to
|
||||
configure the Istio service mesh for use with Coder.
|
||||
Use Istio service mesh for your Coder workspace traffic to implement access controls, encrypt service-to-service communication, and gain visibility into your workspace network patterns.
|
||||
This guide walks through the required steps to configure the Istio service mesh for use with Coder.
|
||||
|
||||
While Istio is platform-independent, this guide assumes you are leveraging
|
||||
Kubernetes. Ensure you have a running Kubernetes cluster with both Coder and
|
||||
Istio installed, and that you have administrative access to configure both
|
||||
systems. Once you have access to your Coder cluster, apply the following
|
||||
manifest:
|
||||
While Istio is platform-independent, this guide assumes you are leveraging Kubernetes.
|
||||
Ensure you have a running Kubernetes cluster with both Coder and Istio installed, and that you have administrative access to configure both systems.
|
||||
Once you have access to your Coder cluster, apply the following manifest:
|
||||
|
||||
```yaml
|
||||
apiVersion: networking.istio.io/v1alpha3
|
||||
|
||||
@@ -2,25 +2,20 @@
|
||||
title: JFrog Artifactory integration
|
||||
---
|
||||
|
||||
Use Coder and JFrog Artifactory together to secure your development environments
|
||||
without disturbing your developers' existing workflows.
|
||||
Use Coder and JFrog Artifactory together to secure your development environments without disturbing your developers' existing workflows.
|
||||
|
||||
This guide will demonstrate how to use JFrog Artifactory as a package registry
|
||||
within a workspace.
|
||||
This guide will demonstrate how to use JFrog Artifactory as a package registry within a workspace.
|
||||
|
||||
## Requirements
|
||||
|
||||
- A JFrog Artifactory instance
|
||||
- 1:1 mapping of users in Coder to users in Artifactory by email address or
|
||||
username
|
||||
- Repositories configured in Artifactory for each package manager you want to
|
||||
use
|
||||
- 1:1 mapping of users in Coder to users in Artifactory by email address or username
|
||||
- Repositories configured in Artifactory for each package manager you want to use
|
||||
|
||||
## Provisioner Authentication
|
||||
|
||||
The most straight-forward way to authenticate your template with Artifactory is
|
||||
by using our official Coder [modules](https://registry.coder.com). We publish
|
||||
two type of modules that automate the JFrog Artifactory and Coder integration.
|
||||
The most straight-forward way to authenticate your template with Artifactory is by using our official Coder [modules](https://registry.coder.com).
|
||||
We publish two type of modules that automate the JFrog Artifactory and Coder integration.
|
||||
|
||||
1. [JFrog-OAuth](https://registry.coder.com/modules/jfrog-oauth)
|
||||
1. [JFrog-Token](https://registry.coder.com/modules/jfrog-token)
|
||||
@@ -43,7 +38,8 @@ To set this up, follow these steps:
|
||||
1. On the **Create New Application Integration** form, set **Application Name** to `Coder`, set **Application Type** to **Custom Integration**, and enter the callback URL.
|
||||
1. Select **Generate Client ID & Secret**.
|
||||
|
||||
**Self-hosted (on-premises)**: First register an integration template in your Helm chart `values.yaml`, then create the application integration in the UI, and select that template as the **Application Type**.
|
||||
**Self-hosted (on-premises)**:
|
||||
First register an integration template in your Helm chart `values.yaml`, then create the application integration in the UI, and select that template as the **Application Type**.
|
||||
Replace `CODER_URL` with your Coder deployment URL:
|
||||
|
||||
```yaml
|
||||
@@ -100,17 +96,16 @@ To set this up, follow these steps:
|
||||
|
||||
### JFrog-Token
|
||||
|
||||
This module makes use of the [Artifactory terraform
|
||||
provider](https://registry.terraform.io/providers/jfrog/artifactory/latest/docs) and an admin-scoped token to create
|
||||
user-scoped tokens for each user by matching their Coder email or username with
|
||||
Artifactory. This can be used for both SaaS and self-hosted (on-premises)
|
||||
Artifactory instances.
|
||||
This module makes use of the [Artifactory terraform provider](https://registry.terraform.io/providers/jfrog/artifactory/latest/docs) and an admin-scoped token to create user-scoped tokens for each user by matching their Coder email or username with Artifactory.
|
||||
This can be used for both SaaS and self-hosted (on-premises) Artifactory instances.
|
||||
|
||||
To set this up, follow these steps:
|
||||
|
||||
1. Get a JFrog access token from your Artifactory instance. The token must be an [admin token](https://registry.terraform.io/providers/jfrog/artifactory/latest/docs#access-token) with scope `applied-permissions/admin`.
|
||||
1. Get a JFrog access token from your Artifactory instance.
|
||||
The token must be an [admin token](https://registry.terraform.io/providers/jfrog/artifactory/latest/docs#access-token) with scope `applied-permissions/admin`.
|
||||
|
||||
1. Create or edit a Coder template and use the [JFrog-Token](https://registry.coder.com/modules/jfrog-token) module to configure the integration and pass the admin token. It is recommended to store the token in a sensitive Terraform variable to prevent it from being displayed in plain text in the terraform state:
|
||||
1. Create or edit a Coder template and use the [JFrog-Token](https://registry.coder.com/modules/jfrog-token) module to configure the integration and pass the admin token.
|
||||
It is recommended to store the token in a sensitive Terraform variable to prevent it from being displayed in plain text in the terraform state:
|
||||
|
||||
```tf
|
||||
variable "artifactory_access_token" {
|
||||
@@ -136,8 +131,8 @@ To set this up, follow these steps:
|
||||
> [!NOTE]
|
||||
> The admin-level access token is used to provision user tokens and is never exposed to developers or stored in workspaces.
|
||||
|
||||
If you don't want to use the official modules, you can read through the [example template](../../../examples/jfrog/docker), which uses Docker as the underlying compute. The
|
||||
same concepts apply to all compute types.
|
||||
If you don't want to use the official modules, you can read through the [example template](../../../examples/jfrog/docker), which uses Docker as the underlying compute.
|
||||
The same concepts apply to all compute types.
|
||||
|
||||
## Air-Gapped Deployments
|
||||
|
||||
@@ -147,5 +142,4 @@ See the [air-gapped deployments](../templates/extending-templates/modules.md#off
|
||||
|
||||
- See the [full example Docker template](../../../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 serve extensions from your own VS Code Marketplace, check out [code-marketplace](https://github.com/coder/code-marketplace#artifactory-storage).
|
||||
|
||||
@@ -2,18 +2,15 @@
|
||||
title: Kubernetes event logs
|
||||
---
|
||||
|
||||
To stream Kubernetes events into your workspace startup logs, you can use
|
||||
Coder's [`coder-logstream-kube`](https://github.com/coder/coder-logstream-kube)
|
||||
tool. `coder-logstream-kube` provides useful information about the workspace pod
|
||||
or deployment, such as:
|
||||
To stream Kubernetes events into your workspace startup logs, you can use Coder's [`coder-logstream-kube`](https://github.com/coder/coder-logstream-kube) tool.
|
||||
`coder-logstream-kube` provides useful information about the workspace pod or deployment, such as:
|
||||
|
||||
- Causes of pod provisioning failures, or why a pod is stuck in a pending state.
|
||||
- Visibility into when pods are OOMKilled, or when they are evicted.
|
||||
|
||||
## Installation
|
||||
|
||||
Install the `coder-logstream-kube` helm chart on the cluster where the
|
||||
deployment is running.
|
||||
Install the `coder-logstream-kube` helm chart on the cluster where the deployment is running.
|
||||
|
||||
```sh
|
||||
helm repo add coder-logstream-kube https://helm.coder.com/logstream-kube
|
||||
@@ -24,8 +21,7 @@ helm install coder-logstream-kube coder-logstream-kube/coder-logstream-kube \
|
||||
|
||||
## Example logs
|
||||
|
||||
Here is an example of the logs you can expect to see in the workspace startup
|
||||
logs:
|
||||
Here is an example of the logs you can expect to see in the workspace startup logs:
|
||||
|
||||
### Normal pod deployment
|
||||
|
||||
@@ -45,13 +41,8 @@ logs:
|
||||
|
||||
## How it works
|
||||
|
||||
Kubernetes provides an
|
||||
[informers](https://pkg.go.dev/k8s.io/client-go/informers) API that streams pod
|
||||
and event data from the API server.
|
||||
Kubernetes provides an [informers](https://pkg.go.dev/k8s.io/client-go/informers) API that streams pod and event data from the API server.
|
||||
|
||||
coder-logstream-kube listens for pod creation events with containers that have
|
||||
the CODER_AGENT_TOKEN environment variable set. All pod events are streamed as
|
||||
logs to the Coder API using the agent token for authentication. For more
|
||||
details, see the
|
||||
[coder-logstream-kube](https://github.com/coder/coder-logstream-kube)
|
||||
repository.
|
||||
coder-logstream-kube listens for pod creation events with containers that have the CODER_AGENT_TOKEN environment variable set.
|
||||
All pod events are streamed as logs to the Coder API using the agent token for authentication.
|
||||
For more details, see the [coder-logstream-kube](https://github.com/coder/coder-logstream-kube) repository.
|
||||
|
||||
@@ -2,17 +2,13 @@
|
||||
title: Additional clusters
|
||||
---
|
||||
|
||||
With Coder, you can deploy workspaces in additional Kubernetes clusters using
|
||||
different
|
||||
[authentication methods](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#authentication)
|
||||
in the Terraform provider.
|
||||
With Coder, you can deploy workspaces in additional Kubernetes clusters using different [authentication methods](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#authentication) in the Terraform provider.
|
||||
|
||||
|
||||
|
||||
## Option 1) Kubernetes contexts and kubeconfig
|
||||
|
||||
First, create a kubeconfig file with
|
||||
[multiple contexts](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/).
|
||||
First, create a kubeconfig file with [multiple contexts](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/).
|
||||
|
||||
```sh
|
||||
kubectl config get-contexts
|
||||
@@ -26,8 +22,7 @@ CURRENT NAME CLUSTER
|
||||
|
||||
If you deployed Coder on Kubernetes, you can attach a kubeconfig as a secret.
|
||||
|
||||
This assumes Coder is deployed on the `coder` namespace and your kubeconfig file
|
||||
is in ~/.kube/config.
|
||||
This assumes Coder is deployed on the `coder` namespace and your kubeconfig file is in ~/.kube/config.
|
||||
|
||||
```sh
|
||||
kubectl create secret generic kubeconfig-secret -n coder --from-file=~/.kube/config
|
||||
@@ -48,21 +43,16 @@ coder:
|
||||
readOnly: true
|
||||
```
|
||||
|
||||
[Upgrade Coder](../../install/server/kubernetes/index.md#upgrade-coder-via-helm) with these
|
||||
new values.
|
||||
[Upgrade Coder](../../install/server/kubernetes/index.md#upgrade-coder-via-helm) with these new values.
|
||||
|
||||
### VM control plane
|
||||
|
||||
If you deployed Coder on a VM, copy the kubeconfig file to
|
||||
`/home/coder/.kube/config`.
|
||||
If you deployed Coder on a VM, copy the kubeconfig file to `/home/coder/.kube/config`.
|
||||
|
||||
### Create a Coder template
|
||||
|
||||
You can start from our
|
||||
[example template](../../../examples/templates/kubernetes).
|
||||
From there, add
|
||||
[template parameters](../templates/extending-templates/parameters.md) to allow
|
||||
developers to pick their desired cluster.
|
||||
You can start from our [example template](../../../examples/templates/kubernetes).
|
||||
From there, add [template parameters](../templates/extending-templates/parameters.md) to allow developers to pick their desired cluster.
|
||||
|
||||
```tf
|
||||
# main.tf
|
||||
@@ -92,19 +82,17 @@ provider "kubernetes" {
|
||||
|
||||
## Option 2) Kubernetes ServiceAccounts
|
||||
|
||||
Alternatively, you can authenticate with remote clusters with ServiceAccount
|
||||
tokens. Coder can store these secrets on your behalf with
|
||||
[managed Terraform variables](../templates/extending-templates/variables.md).
|
||||
Alternatively, you can authenticate with remote clusters with ServiceAccount tokens.
|
||||
Coder can store these secrets on your behalf with [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).
|
||||
|
||||
This guide assumes you have a `coder-workspaces` namespace on your remote
|
||||
cluster. Change the namespace accordingly.
|
||||
This guide assumes you have a `coder-workspaces` namespace on your remote cluster.
|
||||
Change the namespace accordingly.
|
||||
|
||||
### Create a ServiceAccount
|
||||
|
||||
Run this command against your remote cluster to create a ServiceAccount, Role,
|
||||
RoleBinding, and token:
|
||||
Run this command against your remote cluster to create a ServiceAccount, Role, RoleBinding, and token:
|
||||
|
||||
```sh
|
||||
kubectl apply -n coder-workspaces -f - <<EOF
|
||||
@@ -158,8 +146,7 @@ rolebinding.rbac.authorization.k8s.io/coder-v2 created
|
||||
|
||||
### 2. Modify the Kubernetes template
|
||||
|
||||
You can start from our
|
||||
[example template](../../../examples/templates/kubernetes).
|
||||
You can start from our [example template](../../../examples/templates/kubernetes).
|
||||
|
||||
```tf
|
||||
variable "host" {
|
||||
@@ -190,8 +177,8 @@ provider "kubernetes" {
|
||||
|
||||
### Create Coder template with managed variables
|
||||
|
||||
Fetch the values from the secret and pass them to Coder. This should work on
|
||||
macOS and Linux.
|
||||
Fetch the values from the secret and pass them to Coder.
|
||||
This should work on macOS and Linux.
|
||||
|
||||
To get the cluster address:
|
||||
|
||||
@@ -220,8 +207,7 @@ coder templates push \
|
||||
--variable namespace=coder-workspaces
|
||||
```
|
||||
|
||||
If you're on a Windows machine (or if one of the commands fail), try grabbing
|
||||
the values manually:
|
||||
If you're on a Windows machine (or if one of the commands fail), try grabbing the values manually:
|
||||
|
||||
```sh
|
||||
# Get cluster API address
|
||||
|
||||
@@ -9,11 +9,13 @@ The OS routes the redirect back to the registered application without requiring
|
||||
A private-use scheme must name a path or an authority, as in `com.example.app:/callback` or `com.example.app://auth/callback`.
|
||||
The bare form `com.example.app:callback` is rejected.
|
||||
|
||||
The out-of-band URN `urn:ietf:wg:oauth:2.0:oob` is accepted from either client type, for clients that display the authorization code for the user to copy rather than receiving it on a redirect. No other URN is accepted.
|
||||
The out-of-band URN `urn:ietf:wg:oauth:2.0:oob` is accepted from either client type, for clients that display the authorization code for the user to copy rather than receiving it on a redirect.
|
||||
No other URN is accepted.
|
||||
|
||||
The following schemes are blocked for security reasons: `javascript:`, `data:`, `file:`, `ftp:`.
|
||||
|
||||
Public clients (`token_endpoint_auth_method: none`) additionally cannot register `mailto:`, `tel:`, or `sms:` redirect URIs, since those schemes hand off to another app rather than returning an authorization code to the client. Confidential clients are not subject to this restriction.
|
||||
Public clients (`token_endpoint_auth_method: none`) additionally cannot register `mailto:`, `tel:`, or `sms:` redirect URIs, since those schemes hand off to another app rather than returning an authorization code to the client.
|
||||
Confidential clients are not subject to this restriction.
|
||||
|
||||
A cleartext `http://` redirect URI is accepted only for a local host.
|
||||
A confidential client may use `localhost`, `127.0.0.1`, `[::1]`, or a `.localhost` subdomain such as `http://app.localhost/callback`.
|
||||
|
||||
@@ -66,10 +66,16 @@ Treat the setting as a way to stop new authorizations rather than as a way to re
|
||||
1. Navigate to **Deployment Settings** > **OAuth2 Applications**.
|
||||
2. On the **Applications** tab, select **Add application**.
|
||||
3. Fill in the application details:
|
||||
- **Name**: Your application name
|
||||
- **Default callback**: `https://yourapp.example.com/callback` (web) or `myapp://callback` (native/desktop). Select **Add redirect URI** for additional callback URLs.
|
||||
- **Icon**: Optional icon URL
|
||||
- **Allowed scopes**: Optional. Refer to [Scopes](./scopes.md).
|
||||
- **Name**:
|
||||
Your application name
|
||||
- **Default callback**:
|
||||
`https://yourapp.example.com/callback` (web) or `myapp://callback` (native/desktop).
|
||||
Select **Add redirect URI** for additional callback URLs.
|
||||
- **Icon**:
|
||||
Optional icon URL
|
||||
- **Allowed scopes**:
|
||||
Optional.
|
||||
Refer to [Scopes](./scopes.md).
|
||||
4. Select **Create application**.
|
||||
|
||||
Coder creates the application and takes you to its details page, which prompts you to generate a client secret.
|
||||
@@ -95,9 +101,11 @@ curl -X POST \
|
||||
"$CODER_URL/api/v2/oauth2-provider/apps"
|
||||
```
|
||||
|
||||
`callback_url` is still accepted and still returned, but it is deprecated: it is equal to the first entry in `redirect_uris`. New scripts should send and read `redirect_uris` instead.
|
||||
`callback_url` is still accepted and still returned, but it is deprecated: it is equal to the first entry in `redirect_uris`.
|
||||
New scripts should send and read `redirect_uris` instead.
|
||||
|
||||
Update an application with `PUT`. Fetch it first and edit the fields you want to change, then send the result back:
|
||||
Update an application with `PUT`.
|
||||
Fetch it first and edit the fields you want to change, then send the result back:
|
||||
|
||||
```sh
|
||||
curl -X PUT \
|
||||
@@ -126,13 +134,15 @@ curl -X POST \
|
||||
"$CODER_URL/api/v2/oauth2-provider/apps/$APP_ID/secrets"
|
||||
```
|
||||
|
||||
The response includes `client_secret_full`, the plaintext secret. Save it now: later reads of this application return only a truncated version.
|
||||
The response includes `client_secret_full`, the plaintext secret.
|
||||
Save it now: later reads of this application return only a truncated version.
|
||||
|
||||
Every client, whichever method you used to create its application, must complete PKCE (Proof Key for Code Exchange) to exchange a code for a token; refer to [Authorization code flow](./integration-patterns.md#authorization-code-flow) before you start integrating.
|
||||
|
||||
## Dynamic Client Registration
|
||||
|
||||
Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) lets a client register itself against `/oauth2/register` instead of an admin creating the application manually. It's **disabled by default**; an owner must turn it on before any client can self-register.
|
||||
Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) lets a client register itself against `/oauth2/register` instead of an admin creating the application manually.
|
||||
It's **disabled by default**; an owner must turn it on before any client can self-register.
|
||||
|
||||
Change the setting in the web UI:
|
||||
|
||||
@@ -169,9 +179,8 @@ curl -H "Authorization: Bearer $CODER_SESSION_TOKEN" \
|
||||
"$CODER_URL/api/v2/oauth2-provider/settings"
|
||||
```
|
||||
|
||||
Disabling only blocks *new* self-registrations. Applications that already
|
||||
registered while it was enabled keep authorizing and exchanging tokens
|
||||
normally; disabling does not revoke or otherwise affect them.
|
||||
Disabling only blocks *new* self-registrations.
|
||||
Applications that already registered while it was enabled keep authorizing and exchanging tokens normally; disabling does not revoke or otherwise affect them.
|
||||
|
||||
An application may list several `redirect_uris`, whether it registered itself or an admin created it.
|
||||
A request may present any of them, and the code it receives can only be exchanged with that same URI.
|
||||
|
||||
@@ -13,7 +13,8 @@ This page covers how a client proves who it is and completes a login: the suppor
|
||||
|
||||
Coder supports the following OAuth2 client authentication methods at the token endpoint (`/oauth2/tokens`):
|
||||
|
||||
- `client_secret_basic` (recommended): HTTP Basic authentication (RFC 6749 §2.3.1). The username is `client_id` and the password is `client_secret`.
|
||||
- `client_secret_basic` (recommended): HTTP Basic authentication (RFC 6749 §2.3.1).
|
||||
The username is `client_id` and the password is `client_secret`.
|
||||
- `client_secret_post`: Form-based authentication where `client_id` and `client_secret` are sent in the request body.
|
||||
- `none`: No client secret.
|
||||
The client is a public client and authenticates with PKCE alone (RFC 7591 §2, OAuth 2.1 §2.1).
|
||||
@@ -25,11 +26,14 @@ Send `client_secret` in the request body or in the `Authorization` header.
|
||||
`POST /oauth2/tokens` and `POST /oauth2/revoke` reject a `client_secret` value in the URL query string with `invalid_request`, because OAuth 2.1 section 2.4.1 does not allow it there.
|
||||
Refer to ["invalid_request" for `client_secret` in the query string](./troubleshooting.md#invalid_request-for-client_secret-in-the-query-string) for the exceptions and the log line to search for.
|
||||
|
||||
Public clients suit native, mobile, and CLI applications that cannot keep a secret confidential. Note the redirect URI restrictions below before choosing one.
|
||||
Public clients suit native, mobile, and CLI applications that cannot keep a secret confidential.
|
||||
Note the redirect URI restrictions below before choosing one.
|
||||
|
||||
Opening a public client on the **OAuth2 Applications** page shows no client secrets section, since a public client has no secret to display or generate.
|
||||
|
||||
If you use Dynamic Client Registration (RFC 7591) and omit `token_endpoint_auth_method`, clients default to `client_secret_basic`. To request `client_secret_post`, set `token_endpoint_auth_method` to `client_secret_post` in the registration request. To register a public client, set it to `none`: Coder issues no `client_secret`, and the registration response omits that field entirely.
|
||||
If you use Dynamic Client Registration (RFC 7591) and omit `token_endpoint_auth_method`, clients default to `client_secret_basic`.
|
||||
To request `client_secret_post`, set `token_endpoint_auth_method` to `client_secret_post` in the registration request.
|
||||
To register a public client, set it to `none`: Coder issues no `client_secret`, and the registration response omits that field entirely.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Which redirect URI schemes and hosts a client may register, including the loopback host and port rules for public and confidential clients, is a separate restriction from client authentication.
|
||||
@@ -120,9 +124,12 @@ Coder enforces PKCE in compliance with the OAuth 2.1 specification, for both pub
|
||||
|
||||
Coder provides OAuth2 discovery endpoints for programmatic integration:
|
||||
|
||||
- **Authorization Server Metadata**: `GET /.well-known/oauth-authorization-server`
|
||||
- **REST API protected resource metadata**: `GET /.well-known/oauth-protected-resource`
|
||||
- **MCP protected resource metadata**: `GET /.well-known/oauth-protected-resource/api/experimental/mcp/http`
|
||||
- **Authorization Server Metadata**:
|
||||
`GET /.well-known/oauth-authorization-server`
|
||||
- **REST API protected resource metadata**:
|
||||
`GET /.well-known/oauth-protected-resource`
|
||||
- **MCP protected resource metadata**:
|
||||
`GET /.well-known/oauth-protected-resource/api/experimental/mcp/http`
|
||||
|
||||
These endpoints return server capabilities and endpoint URLs according to [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) and [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728).
|
||||
The REST API metadata identifies the deployment URL as its `resource`, while the MCP metadata identifies the full MCP endpoint URL.
|
||||
|
||||
@@ -2,7 +2,8 @@
|
||||
title: OAuth2 provider scopes
|
||||
---
|
||||
|
||||
An access token is bounded by the scope negotiated when the user authorized it, on top of that user's own permissions. A token can never do more than its user can.
|
||||
An access token is bounded by the scope negotiated when the user authorized it, on top of that user's own permissions.
|
||||
A token can never do more than its user can.
|
||||
|
||||
A grant also never exceeds the session that authorizes it: that session must hold every requested scope and an allow list of `*:*`, which every browser session has.
|
||||
Refer to ["invalid_scope" returned to your callback](./troubleshooting.md#invalid_scope-returned-to-your-callback).
|
||||
|
||||
@@ -8,19 +8,26 @@ This page covers security guidance and current limitations.
|
||||
|
||||
## Security considerations
|
||||
|
||||
- **Use HTTPS**: Always use HTTPS in production to protect tokens in transit
|
||||
- **Implement PKCE**: PKCE is mandatory for all authorization code clients (public and confidential)
|
||||
- **Validate redirect URLs**: Only register trusted redirect URIs.
|
||||
- **Use HTTPS**:
|
||||
Always use HTTPS in production to protect tokens in transit
|
||||
- **Implement PKCE**:
|
||||
PKCE is mandatory for all authorization code clients (public and confidential)
|
||||
- **Validate redirect URLs**:
|
||||
Only register trusted redirect URIs.
|
||||
Dangerous schemes (`javascript:`, `data:`, `file:`, `ftp:`) are blocked by the control plane, custom URI schemes for native apps (`myapp://`) are permitted, and public clients additionally cannot use `mailto:`, `tel:`, or `sms:`
|
||||
- **Rotate secrets**: Periodically rotate client secrets using the management API
|
||||
- **Rate limits**: every `/oauth2` endpoint and both `/.well-known` discovery endpoints draw on the login rate limit of 60 requests per minute.
|
||||
- **Rotate secrets**:
|
||||
Periodically rotate client secrets using the management API
|
||||
- **Rate limits**:
|
||||
every `/oauth2` endpoint and both `/.well-known` discovery endpoints draw on the login rate limit of 60 requests per minute.
|
||||
Each endpoint counts on its own, so a caller that exhausts one can still reach the others.
|
||||
Requests with no Coder session are counted per IP address, and the rest are counted per user.
|
||||
A caller over the limit receives HTTP 429 with a `temporarily_unavailable` error body.
|
||||
The limit is fixed.
|
||||
Running the deployment with `--dangerous-disable-rate-limits` turns it off, and a user with the Owner role can bypass it on a single request with the `X-Coder-Bypass-Ratelimit` header
|
||||
- **Refresh tokens are not self-sufficient**: a confidential client must present its `client_secret` to refresh or revoke, so a leaked token alone cannot mint new access tokens or end another client's session
|
||||
- **No CORS on the authorization endpoint**: `/oauth2/authorize` is reached only by browser navigation and sends no CORS headers, as OAuth 2.1 requires.
|
||||
- **Refresh tokens are not self-sufficient**:
|
||||
a confidential client must present its `client_secret` to refresh or revoke, so a leaked token alone cannot mint new access tokens or end another client's session
|
||||
- **No CORS on the authorization endpoint**:
|
||||
`/oauth2/authorize` is reached only by browser navigation and sends no CORS headers, as OAuth 2.1 requires.
|
||||
The token, registration, revocation, and metadata endpoints do allow cross-origin requests so that browser-based clients can call them
|
||||
|
||||
## Limitations
|
||||
|
||||
@@ -2,11 +2,8 @@
|
||||
title: DX PlatformX
|
||||
---
|
||||
|
||||
[DX](https://getdx.com) is a developer intelligence platform used by engineering
|
||||
leaders and platform engineers. Coder notifications can be transformed to
|
||||
[PlatformX](https://getdx.com/platformx) events, allowing platform engineers to
|
||||
measure activity and send pulse surveys to subsets of Coder users to understand
|
||||
their experience.
|
||||
[DX](https://getdx.com) is a developer intelligence platform used by engineering leaders and platform engineers.
|
||||
Coder notifications can be transformed to [PlatformX](https://getdx.com/platformx) events, allowing platform engineers to measure activity and send pulse surveys to subsets of Coder users to understand their experience.
|
||||
|
||||
|
||||
|
||||
@@ -25,14 +22,9 @@ You'll need:
|
||||
|
||||
## coder-platformx-events-middleware
|
||||
|
||||
Coder sends [notifications](../monitoring/notifications/index.md) via webhooks
|
||||
to coder-platformx-events-middleware, which processes and reformats the payload
|
||||
into a structure compatible with [PlatformX by DX](https://help.getdx.com/en/articles/7880779-getting-started).
|
||||
Coder sends [notifications](../monitoring/notifications/index.md) via webhooks to coder-platformx-events-middleware, which processes and reformats the payload into a structure compatible with [PlatformX by DX](https://help.getdx.com/en/articles/7880779-getting-started).
|
||||
|
||||
For more information about coder-platformx-events-middleware and how to
|
||||
integrate it with your Coder deployment and PlatformX events, refer to the
|
||||
[coder-platformx-notifications](https://github.com/coder/coder-platformx-notifications)
|
||||
repository.
|
||||
For more information about coder-platformx-events-middleware and how to integrate it with your Coder deployment and PlatformX events, refer to the [coder-platformx-notifications](https://github.com/coder/coder-platformx-notifications) repository.
|
||||
|
||||
### Supported Notification Types
|
||||
|
||||
@@ -58,7 +50,8 @@ A `.env.sample` file is included:
|
||||
|
||||
### Logging
|
||||
|
||||
Logs are printed to the console and can be adjusted using the `LOG_LEVEL` variable. The available levels are:
|
||||
Logs are printed to the console and can be adjusted using the `LOG_LEVEL` variable.
|
||||
The available levels are:
|
||||
|
||||
| Level | Description |
|
||||
|-----------|---------------------------------------|
|
||||
|
||||
@@ -13,15 +13,13 @@ August 05, 2024
|
||||
|
||||
This guide describes the process of integrating [HashiCorp Vault](https://www.vaultproject.io/) into 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.
|
||||
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.
|
||||
|
||||
## The `vault-github` module
|
||||
|
||||
The [`vault-github`](https://registry.coder.com/modules/vault-github) module is a Terraform module that allows you to
|
||||
authenticate with Vault using a GitHub token. This module uses the existing
|
||||
GitHub [external authentication](../external-auth.md) to get the token and authenticate with Vault.
|
||||
The [`vault-github`](https://registry.coder.com/modules/vault-github) module is a Terraform module that allows you to authenticate with Vault using a GitHub token.
|
||||
This module uses the existing GitHub [external authentication](../external-auth.md) to get the token and authenticate with Vault.
|
||||
|
||||
To use this module, add the following code to your Terraform configuration.
|
||||
|
||||
@@ -37,8 +35,7 @@ module "vault" {
|
||||
|
||||
This module installs and authenticates the `vault` CLI in your Coder workspace.
|
||||
|
||||
Users then can use the `vault` CLI to interact with Vault; for example, to fetch
|
||||
a secret stored in the KV backend.
|
||||
Users then can use the `vault` CLI to interact with Vault; for example, to fetch a secret stored in the KV backend.
|
||||
|
||||
```sh
|
||||
vault kv get -namespace=YOUR_NAMESPACE -mount=MOUNT_NAME SECRET_NAME
|
||||
|
||||
@@ -6,78 +6,66 @@ title: Appearance
|
||||
> Customizing Coder's appearance is a Premium feature.
|
||||
> [Learn more](https://coder.com/pricing#compare-plans).
|
||||
|
||||
Customize the look of your Coder deployment to meet your enterprise
|
||||
requirements.
|
||||
Customize the look of your Coder deployment to meet your enterprise requirements.
|
||||
|
||||
You can access the Appearance settings by navigating to
|
||||
`Deployment > Appearance`.
|
||||
You can access the Appearance settings by navigating to `Deployment > Appearance`.
|
||||
|
||||
|
||||
|
||||
## Application Name
|
||||
|
||||
Specify a custom application name to be displayed on the login page. The default
|
||||
is Coder.
|
||||
Specify a custom application name to be displayed on the login page.
|
||||
The default is Coder.
|
||||
|
||||
## Logo URL
|
||||
|
||||
Specify a custom URL for your enterprise's logo to be displayed on the sign in
|
||||
page and in the top left corner of the dashboard. The default is the Coder logo.
|
||||
Specify a custom URL for your enterprise's logo to be displayed on the sign in page and in the top left corner of the dashboard.
|
||||
The default is the Coder logo.
|
||||
|
||||
## Announcement Banners
|
||||
|
||||
|
||||
|
||||
Announcement Banners let admins post important messages to all site users. Only
|
||||
Site Owners may set the announcement banners.
|
||||
Announcement Banners let admins post important messages to all site users.
|
||||
Only Site Owners may set the announcement banners.
|
||||
|
||||
Example: Use multiple announcement banners for concurrent deployment-wide
|
||||
updates, such as maintenance or new feature rollout.
|
||||
Example: Use multiple announcement banners for concurrent deployment-wide updates, such as maintenance or new feature rollout.
|
||||
|
||||
|
||||
|
||||
Example: Adhere to government network classification requirements and notify
|
||||
users of which network their Coder deployment is on.
|
||||
Example: Adhere to government network classification requirements and notify users of which network their Coder deployment is on.
|
||||
|
||||
|
||||
|
||||
## OIDC Login Button Customization
|
||||
|
||||
[Use environment variables to customize](../users/oidc-auth/index.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/index.md#oidc-login-customization) the text and icon on the OIDC button on the Sign In page.
|
||||
|
||||
## Support Links
|
||||
|
||||
Support links let admins adjust the user dropdown menu to include links
|
||||
referring to internal company resources. The menu section replaces the original
|
||||
menu positions: documentation, report a bug to GitHub, or join the Discord
|
||||
server.
|
||||
Support links let admins adjust the user dropdown menu to include links referring to internal company resources.
|
||||
The menu section replaces the original menu positions: documentation, report a bug to GitHub, or join the Discord server.
|
||||
|
||||
|
||||
|
||||
### Icons
|
||||
|
||||
The link icons are optional, and can be set to any url or
|
||||
[builtin icon](../templates/extending-templates/icons.md#bundled-icons),
|
||||
additionally `bug`, `chat`, `docs`, and `star` are available as special icons.
|
||||
The link icons are optional, and can be set to any url or [builtin icon](../templates/extending-templates/icons.md#bundled-icons), additionally `bug`, `chat`, `docs`, and `star` are available as special icons.
|
||||
|
||||
### Location
|
||||
|
||||
The `location` property is optional and determines where the support link will
|
||||
be displayed:
|
||||
The `location` property is optional and determines where the support link will be displayed:
|
||||
|
||||
- `navbar` - displays the link as a button in the top navigation bar
|
||||
- `dropdown` - displays the link in the user dropdown menu (default)
|
||||
|
||||
If the `location` property is not specified, the link will be displayed in the
|
||||
user dropdown menu.
|
||||
If the `location` property is not specified, the link will be displayed in the user dropdown menu.
|
||||
|
||||
### Configuration
|
||||
|
||||
#### Kubernetes
|
||||
|
||||
To configure support links in your Coder Kubernetes deployment, update your Helm
|
||||
chart values as follows:
|
||||
To configure support links in your Coder Kubernetes deployment, update your Helm chart values as follows:
|
||||
|
||||
```yaml
|
||||
coder:
|
||||
@@ -97,8 +85,7 @@ coder:
|
||||
|
||||
#### System package
|
||||
|
||||
if running as a system service, set an environment variable
|
||||
`CODER_SUPPORT_LINKS` in `/etc/coder.d/coder.env` as follows,
|
||||
if running as a system service, set an environment variable `CODER_SUPPORT_LINKS` in `/etc/coder.d/coder.env` as follows,
|
||||
|
||||
```dotenv
|
||||
CODER_SUPPORT_LINKS='[{"name": "Hello GitHub", "target": "https://github.com/coder/coder", "icon": "bug"}, {"name": "Hello Slack", "target": "https://codercom.slack.com/archives/C014JH42DBJ", "icon": "https://raw.githubusercontent.com/coder/coder/main/site/static/icon/slack.svg"}, {"name": "Hello Discord", "target": "https://discord.gg/coder", "icon": "https://raw.githubusercontent.com/coder/coder/main/site/static/icon/discord.svg", "location": "navbar"}, {"name": "Hello Foobar", "target": "https://discord.gg/coder", "icon": "/emojis/1f3e1.png"}]'
|
||||
|
||||
@@ -26,7 +26,8 @@ CODER_EXPERIMENTS=agent-lifecycle-hooks
|
||||
```
|
||||
|
||||
Without the experiment, an enabled hook configuration is inactive: `coder server` logs a warning at startup and dispatches no hook events.
|
||||
Enabled hook settings are still validated at startup when a hook URL is set. Leaving the URL unset, or setting `CODER_CHAT_HOOK_ENABLED=false`, makes the hook settings inert and skips their validation.
|
||||
Enabled hook settings are still validated at startup when a hook URL is set.
|
||||
Leaving the URL unset, or setting `CODER_CHAT_HOOK_ENABLED=false`, makes the hook settings inert and skips their validation.
|
||||
The experiment list is read at startup, so enabling or disabling it requires a `coder server` restart.
|
||||
|
||||
Set the following deployment options on `coder server`.
|
||||
@@ -46,7 +47,8 @@ Use a dedicated secret and rotate it through your existing secret-management pro
|
||||
Rotation is a hard cutover: Coder signs with exactly one secret, so dispatches fail until the consumer accepts the new value.
|
||||
Rotate during a maintenance window, or temporarily set `CODER_CHAT_HOOK_ENABLED=false` for the cutover if blocked chats are worse than unreviewed ones for your deployment.
|
||||
Coder requires the configured URL to use HTTPS unless `CODER_CHAT_HOOK_ALLOW_INSECURE` is set.
|
||||
Plain HTTP removes more than transport privacy: hook responses are what allow or deny tool calls and can rewrite prompts and tool inputs, so anyone on the network path can forge them. Coder logs a warning at startup when hooks run over plain HTTP.
|
||||
Plain HTTP removes more than transport privacy: hook responses are what allow or deny tool calls and can rewrite prompts and tool inputs, so anyone on the network path can forge them.
|
||||
Coder logs a warning at startup when hooks run over plain HTTP.
|
||||
A TLS terminator can forward the request to a consumer over plain HTTP on a trusted local network.
|
||||
Configure the consumer with the same `CODER_CHAT_HOOK_URL` value, because that URL is the audience Coder signs into every dispatch.
|
||||
The consumer compares the `aud` claim against its configured audience and rejects a mismatch.
|
||||
@@ -144,16 +146,20 @@ Coder dispatches `user_prompt_submit` exactly once per submission, when the prom
|
||||
|
||||
### When tool calls are admitted
|
||||
|
||||
Coder dispatches `pre_tool_use` once per tool call, after the model finishes proposing it and before the assistant message is stored. The stored message therefore carries the input the tool actually runs with, and stored message content is never rewritten afterwards.
|
||||
Coder dispatches `pre_tool_use` once per tool call, after the model finishes proposing it and before the assistant message is stored.
|
||||
The stored message therefore carries the input the tool actually runs with, and stored message content is never rewritten afterwards.
|
||||
|
||||
Two consequences follow:
|
||||
|
||||
- Clients stream the model's proposed tool input while the dispatch is in flight, then converge on the stored input once the message is committed.
|
||||
A rewritten call keeps displaying the original input until the whole batch is admitted, and the row spinner remains after the live **Thinking** indicator clears.
|
||||
Coder dispatches a batch sequentially, so that window is bounded by `CODER_CHAT_HOOK_TIMEOUT` multiplied by the number of tool calls in the step, not by a single timeout.
|
||||
- A tool call that is already in chat history was admitted before it was stored, so Coder executes it with the stored input instead of dispatching a second decision. If a consumer's policy changes between those two points, the change applies to later calls, not to calls already admitted. A call stored before hooks were configured is likewise not admitted retroactively, the same way an earlier prompt isn't.
|
||||
- A tool call that is already in chat history was admitted before it was stored, so Coder executes it with the stored input instead of dispatching a second decision.
|
||||
If a consumer's policy changes between those two points, the change applies to later calls, not to calls already admitted.
|
||||
A call stored before hooks were configured is likewise not admitted retroactively, the same way an earlier prompt isn't.
|
||||
|
||||
The per-chat debug endpoint records what the model proposed, including tool input that a consumer replaced. It reports provider behavior and is not part of the chat transcript.
|
||||
The per-chat debug endpoint records what the model proposed, including tool input that a consumer replaced.
|
||||
It reports provider behavior and is not part of the chat transcript.
|
||||
|
||||
## Plan failure recovery
|
||||
|
||||
@@ -194,7 +200,8 @@ Use event-specific identifiers for logical duplicates:
|
||||
| `user_prompt_submit` | Dispatch occurs before a message ID exists. Avoid non-idempotent external effects because identical prompt content can be submitted twice. |
|
||||
| `pre_compact`, `post_compact`, `stop` | Don't rely on `turn_id` surviving recovery. Make external effects safe to repeat. |
|
||||
|
||||
Rejecting duplicates breaks Coder's retries. Return the same decision whenever the payload identifies the same logical event.
|
||||
Rejecting duplicates breaks Coder's retries.
|
||||
Return the same decision whenever the payload identifies the same logical event.
|
||||
|
||||
After the consumer is healthy, send another message to an existing errored chat to resume it.
|
||||
Coder emits `session_start` when the agent loop starts again, with `source` set to `resume` when the chat already contains an assistant reply and `startup` otherwise.
|
||||
|
||||
@@ -2,20 +2,20 @@
|
||||
title: Data retention
|
||||
---
|
||||
|
||||
Coder supports configurable retention policies that automatically purge old
|
||||
Audit Logs, Connection Logs, Workspace Agent Logs, API keys, and AI Gateway
|
||||
records. These policies help manage database growth by removing records older
|
||||
than a specified duration.
|
||||
Coder supports configurable retention policies that automatically purge old Audit Logs, Connection Logs, Workspace Agent Logs, API keys, and AI Gateway records.
|
||||
These policies help manage database growth by removing records older than a specified duration.
|
||||
|
||||
## Overview
|
||||
|
||||
Large deployments can accumulate significant amounts of data over time.
|
||||
Retention policies help you:
|
||||
|
||||
- **Reduce database size**: Automatically remove old records to free disk space.
|
||||
- **Improve performance**: Smaller tables mean faster queries and backups.
|
||||
- **Meet compliance requirements**: Configure retention periods that align with
|
||||
your organization's data retention policies.
|
||||
- **Reduce database size**:
|
||||
Automatically remove old records to free disk space.
|
||||
- **Improve performance**:
|
||||
Smaller tables mean faster queries and backups.
|
||||
- **Meet compliance requirements**:
|
||||
Configure retention periods that align with your organization's data retention policies.
|
||||
|
||||
> [!NOTE]
|
||||
> Retention policies are disabled by default (set to `0`) to preserve existing behavior.
|
||||
@@ -23,8 +23,7 @@ Retention policies help you:
|
||||
|
||||
## Configuration
|
||||
|
||||
You can configure retention policies using CLI flags, environment variables, or
|
||||
a YAML configuration file.
|
||||
You can configure retention policies using CLI flags, environment variables, or a YAML configuration file.
|
||||
|
||||
### Settings
|
||||
|
||||
@@ -38,13 +37,11 @@ a YAML configuration file.
|
||||
|
||||
> [!NOTE]
|
||||
> AI Gateway retention is configured separately from other retention settings.
|
||||
> See [AI Gateway Setup](../../ai-coder/ai-gateway/setup.md#data-retention) for
|
||||
> detailed configuration options.
|
||||
> See [AI Gateway Setup](../../ai-coder/ai-gateway/setup.md#data-retention) for detailed configuration options.
|
||||
|
||||
### Duration Format
|
||||
|
||||
Retention durations support days (`d`) and weeks (`w`) in addition to standard
|
||||
Go duration units (`h`, `m`, `s`):
|
||||
Retention durations support days (`d`) and weeks (`w`) in addition to standard Go duration units (`h`, `m`, `s`):
|
||||
|
||||
- `7d` - 7 days
|
||||
- `2w` - 2 weeks
|
||||
@@ -90,8 +87,8 @@ ai_gateway:
|
||||
|
||||
### Background Purge Process
|
||||
|
||||
Coder runs a background process that periodically deletes old records. The
|
||||
purge process:
|
||||
Coder runs a background process that periodically deletes old records.
|
||||
The purge process:
|
||||
|
||||
1. Runs approximately every 10 minutes.
|
||||
2. Processes records in batches to avoid database lock contention.
|
||||
@@ -107,7 +104,8 @@ Each retention setting controls its data type independently:
|
||||
|
||||
### API Keys Special Behavior
|
||||
|
||||
API key retention only affects **expired** keys. A key is deleted only when:
|
||||
API key retention only affects **expired** keys.
|
||||
A key is deleted only when:
|
||||
|
||||
1. The key has expired (past its `expires_at` timestamp).
|
||||
2. The key has been expired for longer than the retention period.
|
||||
@@ -115,15 +113,13 @@ API key retention only affects **expired** keys. A key is deleted only when:
|
||||
Setting `--api-keys-retention=7d` deletes keys that expired more than 7 days ago.
|
||||
Active keys are never deleted by the retention policy.
|
||||
|
||||
Keeping expired keys for a short period allows Coder to return a more helpful
|
||||
error message when users attempt to use an expired key.
|
||||
Keeping expired keys for a short period allows Coder to return a more helpful error message when users attempt to use an expired key.
|
||||
|
||||
### Workspace Agent Logs Behavior
|
||||
|
||||
Workspace agent logs are deleted based on when the agent last connected, not the
|
||||
age of the logs themselves. **Logs from the latest build of each workspace are
|
||||
always retained** regardless of when the agent last connected. This ensures you
|
||||
can always debug issues with active workspaces.
|
||||
Workspace agent logs are deleted based on when the agent last connected, not the age of the logs themselves.
|
||||
**Logs from the latest build of each workspace are always retained** regardless of when the agent last connected.
|
||||
This ensures you can always debug issues with active workspaces.
|
||||
|
||||
For non-latest builds, logs are deleted if the agent hasn't connected within the retention period.
|
||||
Setting `--workspace-agent-logs-retention=7d` deletes logs for agents that haven't connected in 7 days (excluding those from the latest build).
|
||||
@@ -133,9 +129,7 @@ Setting `--workspace-agent-logs-retention=7d` deletes logs for agents that haven
|
||||
AI Gateway retention applies to interception records and all related data, including token usage, prompts, and tool invocations.
|
||||
The default of 60 days provides a reasonable balance between storage costs and the ability to analyze usage patterns.
|
||||
|
||||
For details on what data is retained, see the
|
||||
[AI Gateway Data Retention](../../ai-coder/ai-gateway/setup.md#data-retention)
|
||||
documentation.
|
||||
For details on what data is retained, see the [AI Gateway Data Retention](../../ai-coder/ai-gateway/setup.md#data-retention) documentation.
|
||||
|
||||
## Best Practices
|
||||
|
||||
@@ -157,32 +151,30 @@ ai_gateway:
|
||||
### Compliance Considerations
|
||||
|
||||
> [!WARNING]
|
||||
> Audit Logs provide critical security and compliance information. Purging
|
||||
> Audit Logs may impact your organization's ability to investigate security
|
||||
> incidents or meet compliance requirements. Consult your security and
|
||||
> compliance teams before configuring Audit Log retention.
|
||||
> Audit Logs provide critical security and compliance information.
|
||||
> Purging Audit Logs may impact your organization's ability to investigate security incidents or meet compliance requirements.
|
||||
> Consult your security and compliance teams before configuring Audit Log retention.
|
||||
|
||||
Common compliance frameworks have varying retention requirements:
|
||||
|
||||
- **SOC 2**: Typically requires 1 year of audit logs.
|
||||
- **HIPAA**: Requires 6 years for certain records.
|
||||
- **PCI DSS**: Requires 1 year of audit logs, with 3 months immediately available.
|
||||
- **GDPR**: Requires data minimization but does not specify maximum retention.
|
||||
- **SOC 2**:
|
||||
Typically requires 1 year of audit logs.
|
||||
- **HIPAA**:
|
||||
Requires 6 years for certain records.
|
||||
- **PCI DSS**:
|
||||
Requires 1 year of audit logs, with 3 months immediately available.
|
||||
- **GDPR**:
|
||||
Requires data minimization but does not specify maximum retention.
|
||||
|
||||
### External Log Aggregation
|
||||
|
||||
If you use an external log aggregation system (Splunk, Datadog, etc.), you can
|
||||
configure shorter retention periods in Coder since logs are preserved
|
||||
externally. See
|
||||
[Capture and export audit logs](../security/audit-logs.md#capture-and-export-audit-logs)
|
||||
for details on exporting logs.
|
||||
If you use an external log aggregation system (Splunk, Datadog, etc.), you can configure shorter retention periods in Coder since logs are preserved externally.
|
||||
See [Capture and export audit logs](../security/audit-logs.md#capture-and-export-audit-logs) for details on exporting logs.
|
||||
|
||||
### Database Maintenance
|
||||
|
||||
After enabling retention policies, you may want to run a `VACUUM` operation on
|
||||
your PostgreSQL database to reclaim disk space. See
|
||||
[Maintenance Procedures](../security/audit-logs.md#maintenance-procedures-for-the-audit-logs-table)
|
||||
for guidance.
|
||||
After enabling retention policies, you may want to run a `VACUUM` operation on your PostgreSQL database to reclaim disk space.
|
||||
See [Maintenance Procedures](../security/audit-logs.md#maintenance-procedures-for-the-audit-logs-table) for guidance.
|
||||
|
||||
<a id="keeping-data-indefinitely"></a>
|
||||
|
||||
@@ -203,19 +195,13 @@ ai_gateway:
|
||||
|
||||
## Monitoring
|
||||
|
||||
The purge process logs deletion counts at the `DEBUG` level. To monitor
|
||||
retention activity, enable debug logging or search your logs for entries
|
||||
containing the table name (e.g., `audit_logs`, `connection_logs`, `api_keys`).
|
||||
The purge process logs deletion counts at the `DEBUG` level.
|
||||
To monitor retention activity, enable debug logging or search your logs for entries containing the table name (e.g., `audit_logs`, `connection_logs`, `api_keys`).
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Audit Logs](../security/audit-logs.md): Learn about Audit Logs and manual
|
||||
purge procedures.
|
||||
- [Connection Logs](../monitoring/connection-logs.md): Learn about Connection
|
||||
Logs and monitoring.
|
||||
- [AI Gateway](../../ai-coder/ai-gateway/index.md): Learn about AI Gateway for
|
||||
centralized LLM and MCP proxy management.
|
||||
- [AI Gateway Setup](../../ai-coder/ai-gateway/setup.md#data-retention): Configure
|
||||
AI Gateway data retention.
|
||||
- [AI Gateway Monitoring](../../ai-coder/ai-gateway/monitoring.md): Monitor AI
|
||||
Gateway usage and metrics.
|
||||
- [Audit Logs](../security/audit-logs.md): Learn about Audit Logs and manual purge procedures.
|
||||
- [Connection Logs](../monitoring/connection-logs.md): Learn about Connection Logs and monitoring.
|
||||
- [AI Gateway](../../ai-coder/ai-gateway/index.md): Learn about AI Gateway for centralized LLM and MCP proxy management.
|
||||
- [AI Gateway Setup](../../ai-coder/ai-gateway/setup.md#data-retention): Configure AI Gateway data retention.
|
||||
- [AI Gateway Monitoring](../../ai-coder/ai-gateway/monitoring.md): Monitor AI Gateway usage and metrics.
|
||||
|
||||
+32
-53
@@ -2,27 +2,24 @@
|
||||
title: Configure control plane access
|
||||
---
|
||||
|
||||
The control plane'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/index.md).
|
||||
The control plane'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/index.md).
|
||||
|
||||
> [!TIP]
|
||||
> Need to look up an exact environment variable, CLI flag, or YAML key for a
|
||||
> setting? See the [configuration reference](./configuration-reference.md) for
|
||||
> a searchable list of every option.
|
||||
> Need to look up an exact environment variable, CLI flag, or YAML key for a setting?
|
||||
> See the [configuration reference](./configuration-reference.md) for a searchable list of every option.
|
||||
|
||||
## Access URL
|
||||
|
||||
`CODER_ACCESS_URL` is required if you are not using the tunnel. Set this to the
|
||||
external URL that users and workspaces use to connect to Coder (e.g.
|
||||
<https://coder.example.com>). This should not be localhost.
|
||||
`CODER_ACCESS_URL` is required if you are not using the tunnel.
|
||||
Set this to the external URL that users and workspaces use to connect to Coder (e.g. <https://coder.example.com>).
|
||||
This should not be localhost.
|
||||
|
||||
Access URL should be an external IP address or domain with DNS records pointing to Coder.
|
||||
|
||||
### Tunnel
|
||||
|
||||
If an access URL is not specified, Coder will create a publicly accessible URL
|
||||
to reverse proxy your deployment for simple setup.
|
||||
If an access URL is not specified, Coder will create a publicly accessible URL to reverse proxy your deployment for simple setup.
|
||||
|
||||
## Address
|
||||
|
||||
@@ -54,29 +51,20 @@ The suffix form creates application hostnames such as `8080--main--myworkspace--
|
||||
It requires a DNS record and TLS certificate for `*.example.com`.
|
||||
|
||||
> [!NOTE]
|
||||
> We do not recommend using a top-level-domain for Coder wildcard access
|
||||
> (for example `*.workspaces`), even on private networks with split-DNS. Some
|
||||
> browsers consider these "public" domains and will refuse Coder's cookies,
|
||||
> which are vital to the proper operation of this feature.
|
||||
> We do not recommend using a top-level-domain for Coder wildcard access (for example `*.workspaces`), even on private networks with split-DNS.
|
||||
> Some browsers consider these "public" domains and will refuse Coder's cookies, which are vital to the proper operation of this feature.
|
||||
|
||||
If you are providing TLS certificates directly to the control plane, either
|
||||
|
||||
1. Use a single certificate and key for both the root and wildcard domains.
|
||||
1. Configure multiple certificates and keys via
|
||||
[`coder.tls.secretNames`](../../../helm/coder/values.yaml)
|
||||
in the Helm Chart, or
|
||||
[`--tls-cert-file`](../../reference/cli/server/index.md#--tls-cert-file) and
|
||||
[`--tls-key-file`](../../reference/cli/server/index.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).
|
||||
1. Configure multiple certificates and keys via [`coder.tls.secretNames`](../../../helm/coder/values.yaml) in the Helm Chart, or [`--tls-cert-file`](../../reference/cli/server/index.md#--tls-cert-file) and [`--tls-key-file`](../../reference/cli/server/index.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).
|
||||
|
||||
After you enable the wildcard access URL, you should [disable path-based apps](../../tutorials/best-practices/security-best-practices.md#disable-path-based-apps) for security.
|
||||
|
||||
## TLS & Reverse Proxy
|
||||
|
||||
The control plane 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.
|
||||
The control plane 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.
|
||||
|
||||
- [Apache](../../tutorials/reverse-proxy-apache.md)
|
||||
- [Caddy](../../tutorials/reverse-proxy-caddy.md)
|
||||
@@ -84,9 +72,8 @@ reverse-proxy to terminate TLS certificates from LetsEncrypt.
|
||||
|
||||
### Kubernetes TLS configuration
|
||||
|
||||
Below are the steps to configure Coder to terminate TLS when running on
|
||||
Kubernetes. You must have the certificate `.key` and `.crt` files in your
|
||||
working directory prior to step 1.
|
||||
Below are the steps to configure Coder to terminate TLS when running on Kubernetes.
|
||||
You must have the certificate `.key` and `.crt` files in your working directory prior to step 1.
|
||||
|
||||
1. Create the TLS secret in your Kubernetes cluster
|
||||
|
||||
@@ -94,7 +81,8 @@ working directory prior to step 1.
|
||||
kubectl create secret tls coder-tls -n <coder-namespace> --key="tls.key" --cert="tls.crt"
|
||||
```
|
||||
|
||||
You can use a single certificate for the both the access URL and wildcard access URL. The certificate CN must match the wildcard domain, such as `*.example.coder.com`.
|
||||
You can use a single certificate for the both the access URL and wildcard access URL.
|
||||
The certificate CN must match the wildcard domain, such as `*.example.coder.com`.
|
||||
|
||||
1. Reference the TLS secret in your Coder Helm chart values
|
||||
|
||||
@@ -116,17 +104,14 @@ working directory prior to step 1.
|
||||
|
||||
## PostgreSQL Database
|
||||
|
||||
Coder uses a PostgreSQL database to store users, workspace metadata, and other
|
||||
deployment information. Use `CODER_PG_CONNECTION_URL` to set the database that
|
||||
Coder connects to. If unset, PostgreSQL binaries will be downloaded from Maven
|
||||
(<https://repo1.maven.org/maven2>) and store all data in the config root.
|
||||
Coder uses a PostgreSQL database to store users, workspace metadata, and other deployment information.
|
||||
Use `CODER_PG_CONNECTION_URL` to set the database that Coder connects to.
|
||||
If unset, PostgreSQL binaries will be downloaded from Maven (<https://repo1.maven.org/maven2>) and store all data in the config root.
|
||||
|
||||
> [!NOTE]
|
||||
> Postgres 13 is the minimum supported version.
|
||||
|
||||
If you are using the built-in PostgreSQL deployment and need to use `psql` (aka
|
||||
the PostgreSQL interactive terminal), output the connection URL with the
|
||||
following command:
|
||||
If you are using the built-in PostgreSQL deployment and need to use `psql` (aka the PostgreSQL interactive terminal), output the connection URL with the following command:
|
||||
|
||||
```console
|
||||
$ coder server postgres-builtin-url
|
||||
@@ -137,37 +122,31 @@ psql "postgres://coder@localhost:49627/coder?sslmode=disable&password=feU...yI1"
|
||||
|
||||
### Migrate from the built-in database to an external database
|
||||
|
||||
To migrate from the built-in database to an external database, follow these
|
||||
steps:
|
||||
To migrate from the built-in database to an external database, follow these steps:
|
||||
|
||||
1. Stop your Coder deployment.
|
||||
1. Run `coder server postgres-builtin-serve` in a background terminal.
|
||||
1. Run `coder server postgres-builtin-url` and copy its output command.
|
||||
1. Run `pg_dump <built-in-connection-string> > coder.sql` to dump the internal
|
||||
database to a file.
|
||||
1. Restore that content to an external database with
|
||||
`psql <external-connection-string> < coder.sql`.
|
||||
1. Start your Coder deployment with
|
||||
`CODER_PG_CONNECTION_URL=<external-connection-string>`.
|
||||
1. Run `pg_dump <built-in-connection-string> > coder.sql` to dump the internal database to a file.
|
||||
1. Restore that content to an external database with `psql <external-connection-string> < coder.sql`.
|
||||
1. Start your Coder deployment with `CODER_PG_CONNECTION_URL=<external-connection-string>`.
|
||||
|
||||
<a id="configuring-coder-behind-a-proxy"></a>
|
||||
|
||||
## Configure 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 control plane. Lowercase
|
||||
values (e.g. `http_proxy`) are also respected in this case.
|
||||
To configure Coder behind a corporate proxy, set the environment variables `HTTP_PROXY` and `HTTPS_PROXY`.
|
||||
Be sure to restart the control plane.
|
||||
Lowercase values (e.g. `http_proxy`) are also respected in this case.
|
||||
|
||||
## Continue your setup with external authentication
|
||||
|
||||
Coder supports external authentication via OAuth2.0. This allows enabling
|
||||
integrations with Git providers, such as GitHub, GitLab, and Bitbucket.
|
||||
Coder supports external authentication via OAuth2.0.
|
||||
This allows enabling integrations with Git providers, such as GitHub, GitLab, and Bitbucket.
|
||||
|
||||
External authentication can also be used to integrate with external services
|
||||
like JFrog Artifactory and others.
|
||||
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.
|
||||
Please refer to the [external authentication](../external-auth.md) section for more information.
|
||||
|
||||
## Up Next
|
||||
|
||||
|
||||
@@ -5,14 +5,12 @@ title: Telemetry
|
||||
> [!NOTE]
|
||||
> TL;DR: disable telemetry by setting <code>CODER_TELEMETRY_ENABLE=false</code>.
|
||||
|
||||
Coder collects telemetry from all installations by default. We believe our users
|
||||
should have the right to know what we collect, why we collect it, and how we use
|
||||
the data.
|
||||
Coder collects telemetry from all installations by default.
|
||||
We believe our users should have the right to know what we collect, why we collect it, and how we use the data.
|
||||
|
||||
## What we collect
|
||||
|
||||
You can find a full list of the data we collect in our source code
|
||||
[here](../../../coderd/telemetry/telemetry.go).
|
||||
You can find a full list of the data we collect in our source code [here](../../../coderd/telemetry/telemetry.go).
|
||||
In particular, look at the struct types such as `Template` or `Workspace`.
|
||||
|
||||
As a rule, we **do not collect** the following types of information:
|
||||
@@ -20,31 +18,26 @@ As a rule, we **do not collect** the following types of information:
|
||||
- Any data that could make your installation less secure
|
||||
- Any data that could identify individual users, except the administrator.
|
||||
|
||||
For example, we do not collect parameters, environment variables, or user email
|
||||
addresses. We do collect the administrator email.
|
||||
For example, we do not collect parameters, environment variables, or user email addresses.
|
||||
We do collect the administrator email.
|
||||
|
||||
Workspace agent statistics include session counts keyed by normalized application names, which can include custom IDE names that workspace agents report.
|
||||
|
||||
## Why we collect
|
||||
|
||||
Telemetry helps us understand which features are most valuable, what use cases
|
||||
to focus on, and which bugs to fix first.
|
||||
Telemetry helps us understand which features are most valuable, what use cases to focus on, and which bugs to fix first.
|
||||
|
||||
Most cloud-based software products collect far more data than we do. They often
|
||||
offer little transparency and configurability. It's hard to imagine our favorite
|
||||
SaaS products existing without their creators having a detailed understanding of
|
||||
user interactions. We want to wield some of that product development power to
|
||||
build self-hosted, open-source software.
|
||||
Most cloud-based software products collect far more data than we do.
|
||||
They often offer little transparency and configurability.
|
||||
It's hard to imagine our favorite SaaS products existing without their creators having a detailed understanding of user interactions.
|
||||
We want to wield some of that product development power to build self-hosted, open-source software.
|
||||
|
||||
## Security
|
||||
|
||||
In the event we discover a critical security issue with Coder, we will use
|
||||
telemetry to identify affected installations and notify their administrators.
|
||||
In the event we discover a critical security issue with Coder, we will use telemetry to identify affected installations and notify their administrators.
|
||||
|
||||
<a id="toggling"></a>
|
||||
|
||||
## Turn telemetry on or off
|
||||
|
||||
You can turn telemetry on or off using either the
|
||||
`CODER_TELEMETRY_ENABLE=[true|false]` environment variable or the
|
||||
`--telemetry=[true|false]` command-line flag.
|
||||
You can turn telemetry on or off using either the `CODER_TELEMETRY_ENABLE=[true|false]` environment variable or the `--telemetry=[true|false]` command-line flag.
|
||||
|
||||
Reference in New Issue
Block a user