mirror of
https://github.com/coder/coder.git
synced 2025-07-09 11:45:56 +00:00
docs: restructure docs (#14421)
Closes #13434 Supersedes #14182 --------- Co-authored-by: Ethan <39577870+ethanndickson@users.noreply.github.com> Co-authored-by: Ethan Dickson <ethan@coder.com> Co-authored-by: Ben Potter <ben@coder.com> Co-authored-by: Stephen Kirby <58410745+stirby@users.noreply.github.com> Co-authored-by: Stephen Kirby <me@skirby.dev> Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
This commit is contained in:
committed by
GitHub
parent
288df75686
commit
419eba5fb6
1
.github/workflows/typos.toml
vendored
1
.github/workflows/typos.toml
vendored
@ -22,6 +22,7 @@ pn = "pn"
|
|||||||
EDE = "EDE"
|
EDE = "EDE"
|
||||||
# HELO is an SMTP command
|
# HELO is an SMTP command
|
||||||
HELO = "HELO"
|
HELO = "HELO"
|
||||||
|
LKE = "LKE"
|
||||||
|
|
||||||
[files]
|
[files]
|
||||||
extend-exclude = [
|
extend-exclude = [
|
||||||
|
25
.vscode/settings.json
vendored
25
.vscode/settings.json
vendored
@ -6,14 +6,17 @@
|
|||||||
"ASKPASS",
|
"ASKPASS",
|
||||||
"authcheck",
|
"authcheck",
|
||||||
"autostop",
|
"autostop",
|
||||||
|
"autoupdate",
|
||||||
"awsidentity",
|
"awsidentity",
|
||||||
"bodyclose",
|
"bodyclose",
|
||||||
"buildinfo",
|
"buildinfo",
|
||||||
"buildname",
|
"buildname",
|
||||||
|
"Caddyfile",
|
||||||
"circbuf",
|
"circbuf",
|
||||||
"cliflag",
|
"cliflag",
|
||||||
"cliui",
|
"cliui",
|
||||||
"codecov",
|
"codecov",
|
||||||
|
"codercom",
|
||||||
"coderd",
|
"coderd",
|
||||||
"coderdenttest",
|
"coderdenttest",
|
||||||
"coderdtest",
|
"coderdtest",
|
||||||
@ -21,15 +24,19 @@
|
|||||||
"contravariance",
|
"contravariance",
|
||||||
"cronstrue",
|
"cronstrue",
|
||||||
"databasefake",
|
"databasefake",
|
||||||
|
"dbcrypt",
|
||||||
"dbgen",
|
"dbgen",
|
||||||
"dbmem",
|
"dbmem",
|
||||||
"dbtype",
|
"dbtype",
|
||||||
"DERP",
|
"DERP",
|
||||||
"derphttp",
|
"derphttp",
|
||||||
"derpmap",
|
"derpmap",
|
||||||
|
"devcontainers",
|
||||||
"devel",
|
"devel",
|
||||||
"devtunnel",
|
"devtunnel",
|
||||||
"dflags",
|
"dflags",
|
||||||
|
"dogfood",
|
||||||
|
"dotfiles",
|
||||||
"drpc",
|
"drpc",
|
||||||
"drpcconn",
|
"drpcconn",
|
||||||
"drpcmux",
|
"drpcmux",
|
||||||
@ -38,18 +45,22 @@
|
|||||||
"embeddedpostgres",
|
"embeddedpostgres",
|
||||||
"enablements",
|
"enablements",
|
||||||
"enterprisemeta",
|
"enterprisemeta",
|
||||||
|
"Entra",
|
||||||
"errgroup",
|
"errgroup",
|
||||||
"eventsourcemock",
|
"eventsourcemock",
|
||||||
"externalauth",
|
"externalauth",
|
||||||
"Failf",
|
"Failf",
|
||||||
"fatih",
|
"fatih",
|
||||||
|
"filebrowser",
|
||||||
"Formik",
|
"Formik",
|
||||||
"gitauth",
|
"gitauth",
|
||||||
|
"Gitea",
|
||||||
"gitsshkey",
|
"gitsshkey",
|
||||||
"goarch",
|
"goarch",
|
||||||
"gographviz",
|
"gographviz",
|
||||||
"goleak",
|
"goleak",
|
||||||
"gonet",
|
"gonet",
|
||||||
|
"googleclouddns",
|
||||||
"gossh",
|
"gossh",
|
||||||
"gsyslog",
|
"gsyslog",
|
||||||
"GTTY",
|
"GTTY",
|
||||||
@ -63,9 +74,11 @@
|
|||||||
"initialisms",
|
"initialisms",
|
||||||
"ipnstate",
|
"ipnstate",
|
||||||
"isatty",
|
"isatty",
|
||||||
|
"jetbrains",
|
||||||
"Jobf",
|
"Jobf",
|
||||||
"Keygen",
|
"Keygen",
|
||||||
"kirsle",
|
"kirsle",
|
||||||
|
"knowledgebase",
|
||||||
"Kubernetes",
|
"Kubernetes",
|
||||||
"ldflags",
|
"ldflags",
|
||||||
"magicsock",
|
"magicsock",
|
||||||
@ -77,6 +90,7 @@
|
|||||||
"namesgenerator",
|
"namesgenerator",
|
||||||
"namespacing",
|
"namespacing",
|
||||||
"netaddr",
|
"netaddr",
|
||||||
|
"netcheck",
|
||||||
"netip",
|
"netip",
|
||||||
"netmap",
|
"netmap",
|
||||||
"netns",
|
"netns",
|
||||||
@ -93,6 +107,7 @@
|
|||||||
"opty",
|
"opty",
|
||||||
"paralleltest",
|
"paralleltest",
|
||||||
"parameterscopeid",
|
"parameterscopeid",
|
||||||
|
"portsharing",
|
||||||
"pqtype",
|
"pqtype",
|
||||||
"prometheusmetrics",
|
"prometheusmetrics",
|
||||||
"promhttp",
|
"promhttp",
|
||||||
@ -100,6 +115,8 @@
|
|||||||
"provisionerd",
|
"provisionerd",
|
||||||
"provisionerdserver",
|
"provisionerdserver",
|
||||||
"provisionersdk",
|
"provisionersdk",
|
||||||
|
"psql",
|
||||||
|
"ptrace",
|
||||||
"ptty",
|
"ptty",
|
||||||
"ptys",
|
"ptys",
|
||||||
"ptytest",
|
"ptytest",
|
||||||
@ -114,6 +131,7 @@
|
|||||||
"Signup",
|
"Signup",
|
||||||
"slogtest",
|
"slogtest",
|
||||||
"sourcemapped",
|
"sourcemapped",
|
||||||
|
"speedtest",
|
||||||
"spinbutton",
|
"spinbutton",
|
||||||
"Srcs",
|
"Srcs",
|
||||||
"stdbuf",
|
"stdbuf",
|
||||||
@ -154,13 +172,15 @@
|
|||||||
"turnconn",
|
"turnconn",
|
||||||
"typegen",
|
"typegen",
|
||||||
"typesafe",
|
"typesafe",
|
||||||
|
"unauthenticate",
|
||||||
"unconvert",
|
"unconvert",
|
||||||
"Untar",
|
"untar",
|
||||||
"Userspace",
|
"userspace",
|
||||||
"VMID",
|
"VMID",
|
||||||
"walkthrough",
|
"walkthrough",
|
||||||
"weblinks",
|
"weblinks",
|
||||||
"webrtc",
|
"webrtc",
|
||||||
|
"websockets",
|
||||||
"wgcfg",
|
"wgcfg",
|
||||||
"wgconfig",
|
"wgconfig",
|
||||||
"wgengine",
|
"wgengine",
|
||||||
@ -172,6 +192,7 @@
|
|||||||
"workspaceapps",
|
"workspaceapps",
|
||||||
"workspacebuilds",
|
"workspacebuilds",
|
||||||
"workspacename",
|
"workspacename",
|
||||||
|
"workspaceproxies",
|
||||||
"wsjson",
|
"wsjson",
|
||||||
"xerrors",
|
"xerrors",
|
||||||
"xlarge",
|
"xlarge",
|
||||||
|
25
Makefile
25
Makefile
@ -495,9 +495,9 @@ gen: \
|
|||||||
coderd/rbac/object_gen.go \
|
coderd/rbac/object_gen.go \
|
||||||
codersdk/rbacresources_gen.go \
|
codersdk/rbacresources_gen.go \
|
||||||
site/src/api/rbacresourcesGenerated.ts \
|
site/src/api/rbacresourcesGenerated.ts \
|
||||||
docs/admin/prometheus.md \
|
docs/admin/integrations/prometheus.md \
|
||||||
docs/reference/cli/README.md \
|
docs/reference/cli/index.md \
|
||||||
docs/admin/audit-logs.md \
|
docs/admin/security/audit-logs.md \
|
||||||
coderd/apidoc/swagger.json \
|
coderd/apidoc/swagger.json \
|
||||||
.prettierignore.include \
|
.prettierignore.include \
|
||||||
.prettierignore \
|
.prettierignore \
|
||||||
@ -525,9 +525,9 @@ gen/mark-fresh:
|
|||||||
coderd/rbac/object_gen.go \
|
coderd/rbac/object_gen.go \
|
||||||
codersdk/rbacresources_gen.go \
|
codersdk/rbacresources_gen.go \
|
||||||
site/src/api/rbacresourcesGenerated.ts \
|
site/src/api/rbacresourcesGenerated.ts \
|
||||||
docs/admin/prometheus.md \
|
docs/admin/integrations/prometheus.md \
|
||||||
docs/reference/cli/README.md \
|
docs/reference/cli/index.md \
|
||||||
docs/admin/audit-logs.md \
|
docs/admin/security/audit-logs.md \
|
||||||
coderd/apidoc/swagger.json \
|
coderd/apidoc/swagger.json \
|
||||||
.prettierignore.include \
|
.prettierignore.include \
|
||||||
.prettierignore \
|
.prettierignore \
|
||||||
@ -638,21 +638,20 @@ codersdk/rbacresources_gen.go: scripts/rbacgen/codersdk.gotmpl scripts/rbacgen/m
|
|||||||
site/src/api/rbacresourcesGenerated.ts: scripts/rbacgen/codersdk.gotmpl scripts/rbacgen/main.go coderd/rbac/object.go coderd/rbac/policy/policy.go
|
site/src/api/rbacresourcesGenerated.ts: scripts/rbacgen/codersdk.gotmpl scripts/rbacgen/main.go coderd/rbac/object.go coderd/rbac/policy/policy.go
|
||||||
go run scripts/rbacgen/main.go typescript > "$@"
|
go run scripts/rbacgen/main.go typescript > "$@"
|
||||||
|
|
||||||
|
docs/admin/integrations/prometheus.md: scripts/metricsdocgen/main.go scripts/metricsdocgen/metrics
|
||||||
docs/admin/prometheus.md: scripts/metricsdocgen/main.go scripts/metricsdocgen/metrics
|
|
||||||
go run scripts/metricsdocgen/main.go
|
go run scripts/metricsdocgen/main.go
|
||||||
./scripts/pnpm_install.sh
|
./scripts/pnpm_install.sh
|
||||||
pnpm exec prettier --write ./docs/admin/prometheus.md
|
pnpm exec prettier --write ./docs/admin/integrations/prometheus.md
|
||||||
|
|
||||||
docs/reference/cli/README.md: scripts/clidocgen/main.go examples/examples.gen.json $(GO_SRC_FILES)
|
docs/reference/cli/index.md: scripts/clidocgen/main.go examples/examples.gen.json $(GO_SRC_FILES)
|
||||||
CI=true BASE_PATH="." go run ./scripts/clidocgen
|
CI=true BASE_PATH="." go run ./scripts/clidocgen
|
||||||
./scripts/pnpm_install.sh
|
./scripts/pnpm_install.sh
|
||||||
pnpm exec prettier --write ./docs/reference/cli/README.md ./docs/reference/cli/*.md ./docs/manifest.json
|
pnpm exec prettier --write ./docs/reference/cli/index.md ./docs/reference/cli/*.md ./docs/manifest.json
|
||||||
|
|
||||||
docs/admin/audit-logs.md: coderd/database/querier.go scripts/auditdocgen/main.go enterprise/audit/table.go coderd/rbac/object_gen.go
|
docs/admin/security/audit-logs.md: coderd/database/querier.go scripts/auditdocgen/main.go enterprise/audit/table.go coderd/rbac/object_gen.go
|
||||||
go run scripts/auditdocgen/main.go
|
go run scripts/auditdocgen/main.go
|
||||||
./scripts/pnpm_install.sh
|
./scripts/pnpm_install.sh
|
||||||
pnpm exec prettier --write ./docs/admin/audit-logs.md
|
pnpm exec prettier --write ./docs/admin/security/audit-logs.md
|
||||||
|
|
||||||
coderd/apidoc/swagger.json: $(shell find ./scripts/apidocgen $(FIND_EXCLUSIONS) -type f) $(wildcard coderd/*.go) $(wildcard enterprise/coderd/*.go) $(wildcard codersdk/*.go) $(wildcard enterprise/wsproxy/wsproxysdk/*.go) $(DB_GEN_FILES) .swaggo docs/manifest.json coderd/rbac/object_gen.go
|
coderd/apidoc/swagger.json: $(shell find ./scripts/apidocgen $(FIND_EXCLUSIONS) -type f) $(wildcard coderd/*.go) $(wildcard enterprise/coderd/*.go) $(wildcard codersdk/*.go) $(wildcard enterprise/wsproxy/wsproxysdk/*.go) $(DB_GEN_FILES) .swaggo docs/manifest.json coderd/rbac/object_gen.go
|
||||||
./scripts/apidocgen/generate.sh
|
./scripts/apidocgen/generate.sh
|
||||||
|
@ -315,6 +315,9 @@ Breaking changes can be triggered in two ways:
|
|||||||
|
|
||||||
### Security
|
### Security
|
||||||
|
|
||||||
|
> If you find a vulnerability, **DO NOT FILE AN ISSUE**. Instead, send an email
|
||||||
|
> to security@coder.com.
|
||||||
|
|
||||||
The
|
The
|
||||||
[`security`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Asecurity)
|
[`security`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Asecurity)
|
||||||
label can be added to PRs that have, or will be, merged into `main`. Doing so
|
label can be added to PRs that have, or will be, merged into `main`. Doing so
|
||||||
|
@ -1,5 +1,7 @@
|
|||||||
# About Coder
|
# About Coder
|
||||||
|
|
||||||
|
<!-- Warning for docs contributors: The first route in manifest.json must be titled "About" for the static landing page to work correctly. -->
|
||||||
|
|
||||||
Coder is an open-source platform for creating and managing developer workspaces
|
Coder is an open-source platform for creating and managing developer workspaces
|
||||||
on your preferred clouds and servers.
|
on your preferred clouds and servers.
|
||||||
|
|
||||||
@ -7,7 +9,10 @@ on your preferred clouds and servers.
|
|||||||
<img src="./images/hero-image.png">
|
<img src="./images/hero-image.png">
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
By building on top of common development interfaces (SSH) and infrastructure tools (Terraform), Coder aims to make the process of **provisioning** and **accessing** remote workspaces approachable for organizations of various sizes and stages of cloud-native maturity.
|
By building on top of common development interfaces (SSH) and infrastructure
|
||||||
|
tools (Terraform), Coder aims to make the process of **provisioning** and
|
||||||
|
**accessing** remote workspaces approachable for organizations of various sizes
|
||||||
|
and stages of cloud-native maturity.
|
||||||
|
|
||||||
<blockquote class="warning">
|
<blockquote class="warning">
|
||||||
<p>
|
<p>
|
||||||
@ -18,21 +23,28 @@ By building on top of common development interfaces (SSH) and infrastructure too
|
|||||||
## How it works
|
## How it works
|
||||||
|
|
||||||
Coder workspaces are represented with Terraform, but no Terraform knowledge is
|
Coder workspaces are represented with Terraform, but no Terraform knowledge is
|
||||||
required to get started. We have a database of pre-made templates built into the
|
required to get started. We have a
|
||||||
product.
|
[database](https://registry.coder.com/templates) of pre-made templates built
|
||||||
|
into the product.
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<img src="./images/providers-compute.png">
|
<img src="./images/providers-compute.png">
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
Coder workspaces don't stop at compute. You can add storage buckets, secrets, sidecars
|
Coder workspaces don't stop at compute. You can add storage buckets, secrets,
|
||||||
and whatever else Terraform lets you dream up.
|
sidecars and whatever else Terraform lets you dream up.
|
||||||
|
|
||||||
[Learn more about managing infrastructure.](./templates/index.md)
|
[Learn more about templates.](./admin/templates/index.md)
|
||||||
|
|
||||||
## IDE Support
|
## IDE Support
|
||||||
|
|
||||||
You can use any Web IDE ([code-server](https://github.com/coder/code-server), [projector](https://github.com/JetBrains/projector-server), [Jupyter](https://jupyter.org/), etc.), [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/), [VS Code Remote](https://code.visualstudio.com/docs/remote/ssh-tutorial) or even a file sync such as [mutagen](https://mutagen.io/).
|
You can use any [Web IDE](./admin/templates/extending-templates/web-ides.md)
|
||||||
|
([code-server](https://github.com/coder/code-server),
|
||||||
|
[projector](https://github.com/JetBrains/projector-server),
|
||||||
|
[Jupyter](https://jupyter.org), etc.),
|
||||||
|
[JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/),
|
||||||
|
[VS Code Remote](https://code.visualstudio.com/docs/remote/ssh-tutorial) or even
|
||||||
|
a file sync such as [mutagen](https://mutagen.io/).
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<img src="./images/ide-icons.svg" height=72>
|
<img src="./images/ide-icons.svg" height=72>
|
||||||
@ -41,11 +53,11 @@ You can use any Web IDE ([code-server](https://github.com/coder/code-server), [p
|
|||||||
## Why remote development
|
## Why remote development
|
||||||
|
|
||||||
Migrating from local developer machines to workspaces hosted by cloud services
|
Migrating from local developer machines to workspaces hosted by cloud services
|
||||||
is an [increasingly common solution for
|
is an
|
||||||
developers](https://blog.alexellis.io/the-internet-is-my-computer/) and
|
[increasingly common solution for developers](https://blog.alexellis.io/the-internet-is-my-computer/)
|
||||||
[organizations
|
and
|
||||||
alike](https://slack.engineering/development-environments-at-slack). There are
|
[organizations alike](https://slack.engineering/development-environments-at-slack).
|
||||||
several benefits, including:
|
There are several benefits, including:
|
||||||
|
|
||||||
- **Increased speed:** Server-grade compute speeds up operations in software
|
- **Increased speed:** Server-grade compute speeds up operations in software
|
||||||
development, such as IDE loading, code compilation and building, and the
|
development, such as IDE loading, code compilation and building, and the
|
||||||
@ -80,8 +92,9 @@ layer of infrastructure control. This additional layer allows admins to:
|
|||||||
- Enable persistent workspaces, which are like local machines, but faster and
|
- Enable persistent workspaces, which are like local machines, but faster and
|
||||||
hosted by a cloud service
|
hosted by a cloud service
|
||||||
|
|
||||||
Coder includes [production-ready templates](https://github.com/coder/coder/tree/c6b1daabc5a7aa67bfbb6c89966d728919ba7f80/examples/templates) for use with AWS EC2,
|
Coder includes
|
||||||
Azure, Google Cloud, Kubernetes, and more.
|
[production-ready templates](https://registry.coder.com/templates) for use with
|
||||||
|
AWS EC2, Azure, Google Cloud, Kubernetes, and more.
|
||||||
|
|
||||||
## What Coder is _not_
|
## What Coder is _not_
|
||||||
|
|
||||||
@ -99,10 +112,5 @@ Azure, Google Cloud, Kubernetes, and more.
|
|||||||
- Coder is not a collaboration platform. You can use git and dedicated IDE
|
- Coder is not a collaboration platform. You can use git and dedicated IDE
|
||||||
extensions for pull requests, code reviews, and pair programming.
|
extensions for pull requests, code reviews, and pair programming.
|
||||||
|
|
||||||
- Coder is not a SaaS/fully-managed offering. You must host
|
- Coder is not a SaaS/fully-managed offering. You must host Coder on a cloud
|
||||||
Coder on a cloud service (AWS, Azure, GCP) or your private data center.
|
service (AWS, Azure, GCP) or your private data center.
|
||||||
|
|
||||||
## Up next
|
|
||||||
|
|
||||||
- Learn about [Templates](./templates/index.md)
|
|
||||||
- [Install Coder](./install/index.md#install-coder)
|
|
||||||
|
@ -1,5 +0,0 @@
|
|||||||
Get started with Coder administration:
|
|
||||||
|
|
||||||
<children>
|
|
||||||
This page is rendered on https://coder.com/docs/admin. Refer to the other documents in the `admin/` directory.
|
|
||||||
</children>
|
|
@ -1,33 +0,0 @@
|
|||||||
# Application Logs
|
|
||||||
|
|
||||||
In Coderd, application logs refer to the records of events, messages, and
|
|
||||||
activities generated by the application during its execution. These logs provide
|
|
||||||
valuable information about the application's behavior, performance, and any
|
|
||||||
issues that may have occurred.
|
|
||||||
|
|
||||||
Application logs include entries that capture events on different levels of
|
|
||||||
severity:
|
|
||||||
|
|
||||||
- Informational messages
|
|
||||||
- Warnings
|
|
||||||
- Errors
|
|
||||||
- Debugging information
|
|
||||||
|
|
||||||
By analyzing application logs, system administrators can gain insights into the
|
|
||||||
application's behavior, identify and diagnose problems, track performance
|
|
||||||
metrics, and make informed decisions to improve the application's stability and
|
|
||||||
efficiency.
|
|
||||||
|
|
||||||
## Error logs
|
|
||||||
|
|
||||||
To ensure effective monitoring and timely response to critical events in the
|
|
||||||
Coder application, it is recommended to configure log alerts that specifically
|
|
||||||
watch for the following log entries:
|
|
||||||
|
|
||||||
| Log Level | Module | Log message | Potential issues |
|
|
||||||
| --------- | ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------- |
|
|
||||||
| `ERROR` | `coderd` | `workspace build error` | Workspace owner is unable to start their workspace. |
|
|
||||||
| `ERROR` | `coderd.autobuild` | `workspace build error` | Autostart failed to initiate the workspace. |
|
|
||||||
| `ERROR` | `coderd.provisionerd-<name>` | | The provisioner job encounters issues importing the workspace template or building the workspace. |
|
|
||||||
| `ERROR` | `coderd.userauth` | | Authentication problems, such as the inability of the workspace user to log in. |
|
|
||||||
| `ERROR` | `coderd.prometheusmetrics` | | The metrics aggregator's queue is full, causing it to reject new metrics. |
|
|
@ -1,21 +1,5 @@
|
|||||||
# External Authentication
|
# External Authentication
|
||||||
|
|
||||||
Coder integrates with Git and OpenID Connect to automate away the need for
|
|
||||||
developers to authenticate with external services within their workspace.
|
|
||||||
|
|
||||||
## Git Providers
|
|
||||||
|
|
||||||
When developers use `git` inside their workspace, they are prompted to
|
|
||||||
authenticate. After that, Coder will store and refresh tokens for future
|
|
||||||
operations.
|
|
||||||
|
|
||||||
<video autoplay playsinline loop>
|
|
||||||
<source src="https://github.com/coder/coder/blob/main/site/static/external-auth.mp4?raw=true" type="video/mp4">
|
|
||||||
Your browser does not support the video tag.
|
|
||||||
</video>
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
To add an external authentication provider, you'll need to create an OAuth
|
To add an external authentication provider, you'll need to create an OAuth
|
||||||
application. The following providers are supported:
|
application. The following providers are supported:
|
||||||
|
|
||||||
@ -25,8 +9,8 @@ application. The following providers are supported:
|
|||||||
- [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops)
|
- [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops)
|
||||||
- [Azure DevOps (via Entra ID)](https://learn.microsoft.com/en-us/entra/architecture/auth-oauth2)
|
- [Azure DevOps (via Entra ID)](https://learn.microsoft.com/en-us/entra/architecture/auth-oauth2)
|
||||||
|
|
||||||
The next step is to [configure the Coder server](./configure.md) to use the
|
The next step is to configure the Coder server to use the OAuth application by
|
||||||
OAuth application by setting the following environment variables:
|
setting the following environment variables:
|
||||||
|
|
||||||
```env
|
```env
|
||||||
CODER_EXTERNAL_AUTH_0_ID="<USER_DEFINED_ID>"
|
CODER_EXTERNAL_AUTH_0_ID="<USER_DEFINED_ID>"
|
||||||
@ -43,7 +27,7 @@ The `CODER_EXTERNAL_AUTH_0_ID` environment variable is used for internal
|
|||||||
reference. Therefore, it can be set arbitrarily (e.g., `primary-github` for your
|
reference. Therefore, it can be set arbitrarily (e.g., `primary-github` for your
|
||||||
GitHub provider).
|
GitHub provider).
|
||||||
|
|
||||||
### GitHub
|
## GitHub
|
||||||
|
|
||||||
> If you don't require fine-grained access control, it's easier to configure a
|
> If you don't require fine-grained access control, it's easier to configure a
|
||||||
> GitHub OAuth app!
|
> GitHub OAuth app!
|
||||||
@ -84,7 +68,7 @@ CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
|
|||||||
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
|
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
|
||||||
```
|
```
|
||||||
|
|
||||||
### GitHub Enterprise
|
## GitHub Enterprise
|
||||||
|
|
||||||
GitHub Enterprise requires the following environment variables:
|
GitHub Enterprise requires the following environment variables:
|
||||||
|
|
||||||
@ -98,7 +82,7 @@ CODER_EXTERNAL_AUTH_0_AUTH_URL="https://github.example.com/login/oauth/authorize
|
|||||||
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token"
|
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token"
|
||||||
```
|
```
|
||||||
|
|
||||||
### Bitbucket Server
|
## Bitbucket Server
|
||||||
|
|
||||||
Bitbucket Server requires the following environment variables:
|
Bitbucket Server requires the following environment variables:
|
||||||
|
|
||||||
@ -110,7 +94,7 @@ CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxx
|
|||||||
CODER_EXTERNAL_AUTH_0_AUTH_URL=https://bitbucket.domain.com/rest/oauth2/latest/authorize
|
CODER_EXTERNAL_AUTH_0_AUTH_URL=https://bitbucket.domain.com/rest/oauth2/latest/authorize
|
||||||
```
|
```
|
||||||
|
|
||||||
### Azure DevOps
|
## Azure DevOps
|
||||||
|
|
||||||
Azure DevOps requires the following environment variables:
|
Azure DevOps requires the following environment variables:
|
||||||
|
|
||||||
@ -124,7 +108,7 @@ CODER_EXTERNAL_AUTH_0_AUTH_URL="https://app.vssps.visualstudio.com/oauth2/author
|
|||||||
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://app.vssps.visualstudio.com/oauth2/token"
|
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://app.vssps.visualstudio.com/oauth2/token"
|
||||||
```
|
```
|
||||||
|
|
||||||
### Azure DevOps (via Entra ID)
|
## Azure DevOps (via Entra ID)
|
||||||
|
|
||||||
Azure DevOps (via Entra ID) requires the following environment variables:
|
Azure DevOps (via Entra ID) requires the following environment variables:
|
||||||
|
|
||||||
@ -138,7 +122,7 @@ CODER_EXTERNAL_AUTH_0_AUTH_URL="https://login.microsoftonline.com/<TENANT ID>/oa
|
|||||||
|
|
||||||
> Note: Your app registration in Entra ID requires the `vso.code_write` scope
|
> Note: Your app registration in Entra ID requires the `vso.code_write` scope
|
||||||
|
|
||||||
### GitLab self-managed
|
## GitLab self-managed
|
||||||
|
|
||||||
GitLab self-managed requires the following environment variables:
|
GitLab self-managed requires the following environment variables:
|
||||||
|
|
||||||
@ -154,7 +138,7 @@ CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://gitlab.company.org/oauth/token"
|
|||||||
CODER_EXTERNAL_AUTH_0_REGEX=gitlab\.company\.org
|
CODER_EXTERNAL_AUTH_0_REGEX=gitlab\.company\.org
|
||||||
```
|
```
|
||||||
|
|
||||||
### Gitea
|
## Gitea
|
||||||
|
|
||||||
```env
|
```env
|
||||||
CODER_EXTERNAL_AUTH_0_ID="gitea"
|
CODER_EXTERNAL_AUTH_0_ID="gitea"
|
||||||
@ -168,7 +152,7 @@ CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitea.com/login/oauth/authorize"
|
|||||||
The Redirect URI for Gitea should be
|
The Redirect URI for Gitea should be
|
||||||
https://coder.company.org/external-auth/gitea/callback
|
https://coder.company.org/external-auth/gitea/callback
|
||||||
|
|
||||||
### Self-managed git providers
|
## Self-managed git providers
|
||||||
|
|
||||||
Custom authentication and token URLs should be used for self-managed Git
|
Custom authentication and token URLs should be used for self-managed Git
|
||||||
provider deployments.
|
provider deployments.
|
||||||
@ -182,12 +166,12 @@ CODER_EXTERNAL_AUTH_0_REGEX=github\.company\.org
|
|||||||
|
|
||||||
> Note: The `REGEX` variable must be set if using a custom git domain.
|
> Note: The `REGEX` variable must be set if using a custom git domain.
|
||||||
|
|
||||||
### JFrog Artifactory
|
## JFrog Artifactory
|
||||||
|
|
||||||
See [this](https://coder.com/docs/guides/artifactory-integration#jfrog-oauth)
|
See [this](../admin/integrations/jfrog-artifactory.md) guide on instructions on
|
||||||
guide on instructions on how to set up for JFrog Artifactory.
|
how to set up for JFrog Artifactory.
|
||||||
|
|
||||||
### Custom scopes
|
## Custom scopes
|
||||||
|
|
||||||
Optionally, you can request custom scopes:
|
Optionally, you can request custom scopes:
|
||||||
|
|
||||||
@ -195,10 +179,11 @@ Optionally, you can request custom scopes:
|
|||||||
CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key"
|
CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key"
|
||||||
```
|
```
|
||||||
|
|
||||||
### Multiple External Providers (enterprise) (premium)
|
## Multiple External Providers (enterprise) (premium)
|
||||||
|
|
||||||
Multiple providers are an [Enterprise feature](https://coder.com/pricing). Below
|
Multiple providers are an Enterprise feature.
|
||||||
is an example configuration with multiple providers.
|
[Learn more](https://coder.com/pricing#compare-plans). Below is an example
|
||||||
|
configuration with multiple providers.
|
||||||
|
|
||||||
```env
|
```env
|
||||||
# Provider 1) github.com
|
# Provider 1) github.com
|
||||||
@ -206,7 +191,7 @@ CODER_EXTERNAL_AUTH_0_ID=primary-github
|
|||||||
CODER_EXTERNAL_AUTH_0_TYPE=github
|
CODER_EXTERNAL_AUTH_0_TYPE=github
|
||||||
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
|
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
|
||||||
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
|
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
|
||||||
CODER_EXTERNAL_AUTH_0_REGEX=github.com/orgname
|
CODER_EXTERNAL_AUTH_0_REGEX=github.com/org
|
||||||
|
|
||||||
# Provider 2) github.example.com
|
# Provider 2) github.example.com
|
||||||
CODER_EXTERNAL_AUTH_1_ID=secondary-github
|
CODER_EXTERNAL_AUTH_1_ID=secondary-github
|
||||||
@ -219,128 +204,10 @@ CODER_EXTERNAL_AUTH_1_TOKEN_URL="https://github.example.com/login/oauth/access_t
|
|||||||
CODER_EXTERNAL_AUTH_1_VALIDATE_URL="https://github.example.com/api/v3/user"
|
CODER_EXTERNAL_AUTH_1_VALIDATE_URL="https://github.example.com/api/v3/user"
|
||||||
```
|
```
|
||||||
|
|
||||||
To support regex matching for paths (e.g. github.com/orgname), you'll need to
|
To support regex matching for paths (e.g. github.com/org), you'll need to add
|
||||||
add this to the
|
this to the
|
||||||
[Coder agent startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script):
|
[Coder agent startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script):
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
git config --global credential.useHttpPath true
|
git config --global credential.useHttpPath true
|
||||||
```
|
```
|
||||||
|
|
||||||
### Kubernetes environment variables
|
|
||||||
|
|
||||||
If you deployed Coder with Kubernetes you can set the environment variables in
|
|
||||||
your `values.yaml` file:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
coder:
|
|
||||||
env:
|
|
||||||
# […]
|
|
||||||
- name: CODER_EXTERNAL_AUTH_0_ID
|
|
||||||
value: USER_DEFINED_ID
|
|
||||||
|
|
||||||
- name: CODER_EXTERNAL_AUTH_0_TYPE
|
|
||||||
value: github
|
|
||||||
|
|
||||||
- name: CODER_EXTERNAL_AUTH_0_CLIENT_ID
|
|
||||||
valueFrom:
|
|
||||||
secretKeyRef:
|
|
||||||
name: github-primary-basic-auth
|
|
||||||
key: client-id
|
|
||||||
|
|
||||||
- name: CODER_EXTERNAL_AUTH_0_CLIENT_SECRET
|
|
||||||
valueFrom:
|
|
||||||
secretKeyRef:
|
|
||||||
name: github-primary-basic-auth
|
|
||||||
key: client-secret
|
|
||||||
```
|
|
||||||
|
|
||||||
You can set the secrets by creating a `github-primary-basic-auth.yaml` file and
|
|
||||||
applying it.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
apiVersion: v1
|
|
||||||
kind: Secret
|
|
||||||
metadata:
|
|
||||||
name: github-primary-basic-auth
|
|
||||||
type: Opaque
|
|
||||||
stringData:
|
|
||||||
client-secret: xxxxxxxxx
|
|
||||||
client-id: xxxxxxxxx
|
|
||||||
```
|
|
||||||
|
|
||||||
Make sure to restart the affected pods for the change to take effect.
|
|
||||||
|
|
||||||
## Require git authentication in templates
|
|
||||||
|
|
||||||
If your template requires git authentication (e.g. running `git clone` in the
|
|
||||||
[startup_script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)),
|
|
||||||
you can require users authenticate via git prior to creating a workspace:
|
|
||||||
|
|
||||||

|
|
||||||
|
|
||||||
### Native git authentication will auto-refresh tokens
|
|
||||||
|
|
||||||
<blockquote class="info">
|
|
||||||
<p>
|
|
||||||
This is the preferred authentication method.
|
|
||||||
</p>
|
|
||||||
</blockquote>
|
|
||||||
|
|
||||||
By default, the coder agent will configure native `git` authentication via the
|
|
||||||
`GIT_ASKPASS` environment variable. Meaning, with no additional configuration,
|
|
||||||
external authentication will work with native `git` commands.
|
|
||||||
|
|
||||||
To check the auth token being used **from inside a running workspace**, run:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
# If the exit code is non-zero, then the user is not authenticated with the
|
|
||||||
# external provider.
|
|
||||||
coder external-auth access-token <external-auth-id>
|
|
||||||
```
|
|
||||||
|
|
||||||
Note: Some IDE's override the `GIT_ASKPASS` environment variable and need to be
|
|
||||||
configured.
|
|
||||||
|
|
||||||
**VSCode**
|
|
||||||
|
|
||||||
Use the
|
|
||||||
[Coder](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote)
|
|
||||||
extension to automatically configure these settings for you!
|
|
||||||
|
|
||||||
Otherwise, you can manually configure the following settings:
|
|
||||||
|
|
||||||
- Set `git.terminalAuthentication` to `false`
|
|
||||||
- Set `git.useIntegratedAskPass` to `false`
|
|
||||||
|
|
||||||
### Hard coded tokens do not auto-refresh
|
|
||||||
|
|
||||||
If the token is required to be inserted into the workspace, for example
|
|
||||||
[GitHub cli](https://cli.github.com/), the auth token can be inserted from the
|
|
||||||
template. This token will not auto-refresh. The following example will
|
|
||||||
authenticate via GitHub and auto-clone a repo into the `~/coder` directory.
|
|
||||||
|
|
||||||
```hcl
|
|
||||||
data "coder_external_auth" "github" {
|
|
||||||
# Matches the ID of the external auth provider in Coder.
|
|
||||||
id = "github"
|
|
||||||
}
|
|
||||||
|
|
||||||
resource "coder_agent" "dev" {
|
|
||||||
os = "linux"
|
|
||||||
arch = "amd64"
|
|
||||||
dir = "~/coder"
|
|
||||||
env = {
|
|
||||||
GITHUB_TOKEN : data.coder_external_auth.github.access_token
|
|
||||||
}
|
|
||||||
startup_script = <<EOF
|
|
||||||
if [ ! -d ~/coder ]; then
|
|
||||||
git clone https://github.com/coder/coder
|
|
||||||
fi
|
|
||||||
EOF
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
See the
|
|
||||||
[Terraform provider documentation](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/external_auth)
|
|
||||||
for all available options.
|
|
||||||
|
@ -1,13 +0,0 @@
|
|||||||
# Groups
|
|
||||||
|
|
||||||
Groups can be used with [template RBAC](./rbac.md) to give groups of users
|
|
||||||
access to specific templates. They can be defined via the Coder web UI,
|
|
||||||
[synced from your identity provider](./auth.md) or
|
|
||||||
[managed via Terraform](https://registry.terraform.io/providers/coder/coderd/latest/docs/resources/template).
|
|
||||||
|
|
||||||

|
|
||||||
|
|
||||||
## Enabling this feature
|
|
||||||
|
|
||||||
This feature is only available with a
|
|
||||||
[Premium or Enterprise license](https://coder.com/pricing).
|
|
18
docs/admin/index.md
Normal file
18
docs/admin/index.md
Normal file
@ -0,0 +1,18 @@
|
|||||||
|
# Administration
|
||||||
|
|
||||||
|
These guides contain information on managing the Coder control plane and
|
||||||
|
[authoring templates](./templates/index.md).
|
||||||
|
|
||||||
|
First time viewers looking to set up control plane access can start with the
|
||||||
|
[configuration guide](./setup/index.md). If you're a team lead looking to design
|
||||||
|
environments for your developers, check out our
|
||||||
|
[templates guides](./templates/index.md). If you are a developer using Coder, we
|
||||||
|
recommend the [user guides](../user-guides/index.md).
|
||||||
|
|
||||||
|
For automation and scripting workflows, see our [CLI](../reference/cli/index.md)
|
||||||
|
and [API](../reference/api/index.md) docs.
|
||||||
|
|
||||||
|
For any information not strictly contained in these sections, check out our
|
||||||
|
[Tutorials](../tutorials/index.md) and [FAQs](../tutorials/faqs.md).
|
||||||
|
|
||||||
|
<children></children>
|
130
docs/admin/infrastructure/architecture.md
Normal file
130
docs/admin/infrastructure/architecture.md
Normal file
@ -0,0 +1,130 @@
|
|||||||
|
# Architecture
|
||||||
|
|
||||||
|
The Coder deployment model is flexible and offers various components that
|
||||||
|
platform administrators can deploy and scale depending on their use case. This
|
||||||
|
page describes possible deployments, challenges, and risks associated with them.
|
||||||
|
|
||||||
|
<div class="tabs">
|
||||||
|
|
||||||
|
## Community Edition
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
## Enterprise
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
## Multi-Region Enterprise
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
## Primary components
|
||||||
|
|
||||||
|
### coderd
|
||||||
|
|
||||||
|
_coderd_ is the service created by running `coder server`. It is a thin API that
|
||||||
|
connects workspaces, provisioners and users. _coderd_ stores its state in
|
||||||
|
Postgres and is the only service that communicates with Postgres.
|
||||||
|
|
||||||
|
It offers:
|
||||||
|
|
||||||
|
- Dashboard (UI)
|
||||||
|
- HTTP API
|
||||||
|
- Dev URLs (HTTP reverse proxy to workspaces)
|
||||||
|
- Workspace Web Applications (e.g for easy access to `code-server`)
|
||||||
|
- Agent registration
|
||||||
|
|
||||||
|
### provisionerd
|
||||||
|
|
||||||
|
_provisionerd_ is the execution context for infrastructure modifying providers.
|
||||||
|
At the moment, the only provider is Terraform (running `terraform`).
|
||||||
|
|
||||||
|
By default, the Coder server runs multiple provisioner daemons.
|
||||||
|
[External provisioners](../provisioners.md) can be added for security or
|
||||||
|
scalability purposes.
|
||||||
|
|
||||||
|
### Workspaces
|
||||||
|
|
||||||
|
At the highest level, a workspace is a set of cloud resources. These resources
|
||||||
|
can be VMs, Kubernetes clusters, storage buckets, or whatever else Terraform
|
||||||
|
lets you dream up.
|
||||||
|
|
||||||
|
The resources that run the agent are described as _computational resources_,
|
||||||
|
while those that don't are called _peripheral resources_.
|
||||||
|
|
||||||
|
Each resource may also be _persistent_ or _ephemeral_ depending on whether
|
||||||
|
they're destroyed on workspace stop.
|
||||||
|
|
||||||
|
### Agents
|
||||||
|
|
||||||
|
An agent is the Coder service that runs within a user's remote workspace. It
|
||||||
|
provides a consistent interface for coderd and clients to communicate with
|
||||||
|
workspaces regardless of operating system, architecture, or cloud.
|
||||||
|
|
||||||
|
It offers the following services along with much more:
|
||||||
|
|
||||||
|
- SSH
|
||||||
|
- Port forwarding
|
||||||
|
- Liveness checks
|
||||||
|
- `startup_script` automation
|
||||||
|
|
||||||
|
Templates are responsible for
|
||||||
|
[creating and running agents](../templates/extending-templates/index.md#workspace-agents)
|
||||||
|
within workspaces.
|
||||||
|
|
||||||
|
## Service Bundling
|
||||||
|
|
||||||
|
While _coderd_ and Postgres can be orchestrated independently, our default
|
||||||
|
installation paths bundle them all together into one system service. It's
|
||||||
|
perfectly fine to run a production deployment this way, but there are certain
|
||||||
|
situations that necessitate decomposition:
|
||||||
|
|
||||||
|
- Reducing global client latency (distribute coderd and centralize database)
|
||||||
|
- Achieving greater availability and efficiency (horizontally scale individual
|
||||||
|
services)
|
||||||
|
|
||||||
|
## Data Layer
|
||||||
|
|
||||||
|
### PostgreSQL (Recommended)
|
||||||
|
|
||||||
|
While `coderd` runs a bundled version of PostgreSQL, we recommend running an
|
||||||
|
external PostgreSQL 13+ database for production deployments.
|
||||||
|
|
||||||
|
A managed PostgreSQL database, with daily backups, is recommended:
|
||||||
|
|
||||||
|
- For AWS: Amazon RDS for PostgreSQL
|
||||||
|
- For Azure: Azure Database for PostgreSQL
|
||||||
|
- Flexible Server For GCP: Cloud SQL for PostgreSQL
|
||||||
|
|
||||||
|
Learn more about database requirements:
|
||||||
|
[Database Health](../monitoring/health-check.md#database)
|
||||||
|
|
||||||
|
### Git Providers (Recommended)
|
||||||
|
|
||||||
|
Users will likely need to pull source code and other artifacts from a git
|
||||||
|
provider. The Coder control plane and workspaces will need network connectivity
|
||||||
|
to the git provider.
|
||||||
|
|
||||||
|
- [GitHub Enterprise](../external-auth.md#github-enterprise)
|
||||||
|
- [GitLab](../external-auth.md#gitlab-self-managed)
|
||||||
|
- [BitBucket](../external-auth.md#bitbucket-server)
|
||||||
|
- [Other Providers](../external-auth.md#self-managed-git-providers)
|
||||||
|
|
||||||
|
### Artifact Manager (Optional)
|
||||||
|
|
||||||
|
Workspaces and templates can pull artifacts from an artifact manager, such as
|
||||||
|
JFrog Artifactory. This can be configured on the infrastructure level, or in
|
||||||
|
some cases within Coder:
|
||||||
|
|
||||||
|
- Tutorial: [JFrog Artifactory and Coder](../integrations/jfrog-artifactory.md)
|
||||||
|
|
||||||
|
### Container Registry (Optional)
|
||||||
|
|
||||||
|
If you prefer not to pull container images for the control plane (`coderd`,
|
||||||
|
`provisionerd`) and workspaces from public container registry (Docker Hub,
|
||||||
|
GitHub Container Registry) you can run your own container registry with Coder.
|
||||||
|
|
||||||
|
To shorten the provisioning time, it is recommended to deploy registry mirrors
|
||||||
|
in the same region as the workspace nodes.
|
32
docs/admin/infrastructure/index.md
Normal file
32
docs/admin/infrastructure/index.md
Normal file
@ -0,0 +1,32 @@
|
|||||||
|
# Infrastructure
|
||||||
|
|
||||||
|
Learn how to spin up & manage Coder infrastructure.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
Coder is a self-hosted platform that runs on your own servers. For large
|
||||||
|
deployments, we recommend running the control plane on Kubernetes. Workspaces
|
||||||
|
can be run as VMs or Kubernetes pods. The control plane (`coderd`) runs in a
|
||||||
|
single region. However, workspace proxies, provisioners, and workspaces can run
|
||||||
|
across regions or even cloud providers for the optimal developer experience.
|
||||||
|
|
||||||
|
Learn more about Coder's
|
||||||
|
[architecture, concepts, and dependencies](./architecture.md).
|
||||||
|
|
||||||
|
## Reference Architectures
|
||||||
|
|
||||||
|
We publish [reference architectures](./validated-architectures/index.md) that
|
||||||
|
include best practices around Coder configuration, infrastructure sizing,
|
||||||
|
autoscaling, and operational readiness for different deployment sizes (e.g.
|
||||||
|
`Up to 2000 users`).
|
||||||
|
|
||||||
|
## Scale Tests
|
||||||
|
|
||||||
|
Use our [scale test utility](./scale-utility.md) that can be run on your Coder
|
||||||
|
deployment to simulate user activity and measure performance.
|
||||||
|
|
||||||
|
## Monitoring
|
||||||
|
|
||||||
|
See our dedicated [Monitoring](../monitoring/index.md) section for details
|
||||||
|
around monitoring your Coder deployment via a bundled Grafana dashboard, health
|
||||||
|
check, and/or within your own observability stack via Prometheus metrics.
|
@ -90,11 +90,11 @@ Database:
|
|||||||
|
|
||||||
## Available reference architectures
|
## Available reference architectures
|
||||||
|
|
||||||
[Up to 1,000 users](../../architecture/1k-users.md)
|
[Up to 1,000 users](./validated-architectures/1k-users.md)
|
||||||
|
|
||||||
[Up to 2,000 users](../../architecture/2k-users.md)
|
[Up to 2,000 users](./validated-architectures/2k-users.md)
|
||||||
|
|
||||||
[Up to 3,000 users](../../architecture/3k-users.md)
|
[Up to 3,000 users](./validated-architectures/3k-users.md)
|
||||||
|
|
||||||
## Hardware recommendation
|
## Hardware recommendation
|
||||||
|
|
||||||
@ -113,12 +113,12 @@ on the workload size to ensure deployment stability.
|
|||||||
#### CPU and memory usage
|
#### CPU and memory usage
|
||||||
|
|
||||||
Enabling
|
Enabling
|
||||||
[agent stats collection](../../reference/cli/server.md#--prometheus-collect-agent-stats)
|
[agent stats collection](../../reference/cli/index.md#--prometheus-collect-agent-stats)
|
||||||
(optional) may increase memory consumption.
|
(optional) may increase memory consumption.
|
||||||
|
|
||||||
Enabling direct connections between users and workspace agents (apps or SSH
|
Enabling direct connections between users and workspace agents (apps or SSH
|
||||||
traffic) can help prevent an increase in CPU usage. It is recommended to keep
|
traffic) can help prevent an increase in CPU usage. It is recommended to keep
|
||||||
[this option enabled](../../reference/cli/server.md#--disable-direct-connections)
|
[this option enabled](../../reference/cli/index.md#--disable-direct-connections)
|
||||||
unless there are compelling reasons to disable it.
|
unless there are compelling reasons to disable it.
|
||||||
|
|
||||||
Inactive users do not consume Coder resources.
|
Inactive users do not consume Coder resources.
|
||||||
@ -149,18 +149,19 @@ Terminal (bidirectional), and Workspace events/logs (unidirectional).
|
|||||||
If the Coder deployment expects traffic from developers spread across the globe,
|
If the Coder deployment expects traffic from developers spread across the globe,
|
||||||
be aware that customer-facing latency might be higher because of the distance
|
be aware that customer-facing latency might be higher because of the distance
|
||||||
between users and the load balancer. Fortunately, the latency can be improved
|
between users and the load balancer. Fortunately, the latency can be improved
|
||||||
with a deployment of Coder [workspace proxies](../workspace-proxies.md).
|
with a deployment of Coder
|
||||||
|
[workspace proxies](../networking/workspace-proxies.md).
|
||||||
|
|
||||||
**Node Autoscaling**
|
**Node Autoscaling**
|
||||||
|
|
||||||
We recommend disabling the autoscaling for `coderd` nodes. Autoscaling can cause
|
We recommend disabling the autoscaling for `coderd` nodes. Autoscaling can cause
|
||||||
interruptions for user connections, see
|
interruptions for user connections, see
|
||||||
[Autoscaling](scale-utility.md#autoscaling) for more details.
|
[Autoscaling](./scale-utility.md#autoscaling) for more details.
|
||||||
|
|
||||||
### Control plane: Workspace Proxies
|
### Control plane: Workspace Proxies
|
||||||
|
|
||||||
When scaling [workspace proxies](../workspace-proxies.md), follow the same
|
When scaling [workspace proxies](../networking/workspace-proxies.md), follow the
|
||||||
guidelines as for `coderd` above:
|
same guidelines as for `coderd` above:
|
||||||
|
|
||||||
- `1 vCPU x 2 GB memory` for every 250 users.
|
- `1 vCPU x 2 GB memory` for every 250 users.
|
||||||
- Disable autoscaling.
|
- Disable autoscaling.
|
@ -6,15 +6,15 @@ infrastructure. For scale-testing Kubernetes clusters we recommend to install
|
|||||||
and use the dedicated Coder template,
|
and use the dedicated Coder template,
|
||||||
[scaletest-runner](https://github.com/coder/coder/tree/main/scaletest/templates/scaletest-runner).
|
[scaletest-runner](https://github.com/coder/coder/tree/main/scaletest/templates/scaletest-runner).
|
||||||
|
|
||||||
Learn more about [Coder’s architecture](../../architecture/architecture.md) and
|
Learn more about [Coder’s architecture](./architecture.md) and our
|
||||||
our [scale-testing methodology](scale-testing.md).
|
[scale-testing methodology](./scale-testing.md).
|
||||||
|
|
||||||
## Recent scale tests
|
## Recent scale tests
|
||||||
|
|
||||||
> Note: the below information is for reference purposes only, and are not
|
> Note: the below information is for reference purposes only, and are not
|
||||||
> intended to be used as guidelines for infrastructure sizing. Review the
|
> intended to be used as guidelines for infrastructure sizing. Review the
|
||||||
> [Reference Architectures](../../architecture/validated-arch.md#node-sizing)
|
> [Reference Architectures](./validated-architectures/index.md#node-sizing) for
|
||||||
> for hardware sizing recommendations.
|
> hardware sizing recommendations.
|
||||||
|
|
||||||
| Environment | Coder CPU | Coder RAM | Coder Replicas | Database | Users | Concurrent builds | Concurrent connections (Terminal/SSH) | Coder Version | Last tested |
|
| Environment | Coder CPU | Coder RAM | Coder Replicas | Database | Users | Concurrent builds | Concurrent connections (Terminal/SSH) | Coder Version | Last tested |
|
||||||
| ---------------- | --------- | --------- | -------------- | ----------------- | ----- | ----------------- | ------------------------------------- | ------------- | ------------ |
|
| ---------------- | --------- | --------- | -------------- | ----------------- | ----- | ----------------- | ------------------------------------- | ------------- | ------------ |
|
||||||
@ -249,6 +249,7 @@ an annotation on the coderd deployment.
|
|||||||
## Troubleshooting
|
## Troubleshooting
|
||||||
|
|
||||||
If a load test fails or if you are experiencing performance issues during
|
If a load test fails or if you are experiencing performance issues during
|
||||||
day-to-day use, you can leverage Coder's [Prometheus metrics](../prometheus.md)
|
day-to-day use, you can leverage Coder's
|
||||||
to identify bottlenecks during scale tests. Additionally, you can use your
|
[Prometheus metrics](../integrations/prometheus.md) to identify bottlenecks
|
||||||
existing cloud monitoring stack to measure load, view server logs, etc.
|
during scale tests. Additionally, you can use your existing cloud monitoring
|
||||||
|
stack to measure load, view server logs, etc.
|
@ -61,18 +61,19 @@ by default.
|
|||||||
|
|
||||||
### User
|
### User
|
||||||
|
|
||||||
A [user](../admin/users.md) is an individual who utilizes the Coder platform to
|
A [user](../../users/index.md) is an individual who utilizes the Coder platform
|
||||||
develop, test, and deploy applications using workspaces. Users can select
|
to develop, test, and deploy applications using workspaces. Users can select
|
||||||
available templates to provision workspaces. They interact with Coder using the
|
available templates to provision workspaces. They interact with Coder using the
|
||||||
web interface, the CLI tool, or directly calling API methods.
|
web interface, the CLI tool, or directly calling API methods.
|
||||||
|
|
||||||
### Workspace
|
### Workspace
|
||||||
|
|
||||||
A [workspace](../workspaces.md) refers to an isolated development environment
|
A [workspace](../../../user-guides/workspace-management.md) refers to an
|
||||||
where users can write, build, and run code. Workspaces are fully configurable
|
isolated development environment where users can write, build, and run code.
|
||||||
and can be tailored to specific project requirements, providing developers with
|
Workspaces are fully configurable and can be tailored to specific project
|
||||||
a consistent and efficient development environment. Workspaces can be
|
requirements, providing developers with a consistent and efficient development
|
||||||
autostarted and autostopped, enabling efficient resource management.
|
environment. Workspaces can be autostarted and autostopped, enabling efficient
|
||||||
|
resource management.
|
||||||
|
|
||||||
Users can connect to workspaces using SSH or via workspace applications like
|
Users can connect to workspaces using SSH or via workspace applications like
|
||||||
`code-server`, facilitating collaboration and remote access. Additionally,
|
`code-server`, facilitating collaboration and remote access. Additionally,
|
||||||
@ -82,22 +83,24 @@ Coder templates and deployed on resources created by provisioners.
|
|||||||
|
|
||||||
### Template
|
### Template
|
||||||
|
|
||||||
A [template](../templates/index.md) in Coder is a predefined configuration for
|
A [template](../../../admin/templates/index.md) in Coder is a predefined
|
||||||
creating workspaces. Templates streamline the process of workspace creation by
|
configuration for creating workspaces. Templates streamline the process of
|
||||||
providing pre-configured settings, tooling, and dependencies. They are built by
|
workspace creation by providing pre-configured settings, tooling, and
|
||||||
template administrators on top of Terraform, allowing for efficient management
|
dependencies. They are built by template administrators on top of Terraform,
|
||||||
of infrastructure resources. Additionally, templates can utilize Coder modules
|
allowing for efficient management of infrastructure resources. Additionally,
|
||||||
to leverage existing features shared with other templates, enhancing flexibility
|
templates can utilize Coder modules to leverage existing features shared with
|
||||||
and consistency across deployments. Templates describe provisioning rules for
|
other templates, enhancing flexibility and consistency across deployments.
|
||||||
infrastructure resources offered by Terraform providers.
|
Templates describe provisioning rules for infrastructure resources offered by
|
||||||
|
Terraform providers.
|
||||||
|
|
||||||
### Workspace Proxy
|
### Workspace Proxy
|
||||||
|
|
||||||
A [workspace proxy](../admin/workspace-proxies.md) serves as a relay connection
|
A [workspace proxy](../../../admin/networking/workspace-proxies.md) serves as a
|
||||||
option for developers connecting to their workspace over SSH, a workspace app,
|
relay connection option for developers connecting to their workspace over SSH, a
|
||||||
or through port forwarding. It helps reduce network latency for geo-distributed
|
workspace app, or through port forwarding. It helps reduce network latency for
|
||||||
teams by minimizing the distance network traffic needs to travel. Notably,
|
geo-distributed teams by minimizing the distance network traffic needs to
|
||||||
workspace proxies do not handle dashboard connections or API calls.
|
travel. Notably, workspace proxies do not handle dashboard connections or API
|
||||||
|
calls.
|
||||||
|
|
||||||
### Provisioner
|
### Provisioner
|
||||||
|
|
||||||
@ -161,7 +164,7 @@ compute as users start/stop workspaces at the beginning and end of their day.
|
|||||||
Set nodeSelectors, affinities, and tolerations in Coder templates to assign
|
Set nodeSelectors, affinities, and tolerations in Coder templates to assign
|
||||||
workspaces to the given node group:
|
workspaces to the given node group:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "kubernetes_deployment" "coder" {
|
resource "kubernetes_deployment" "coder" {
|
||||||
spec {
|
spec {
|
||||||
template {
|
template {
|
||||||
@ -212,11 +215,11 @@ resource "kubernetes_deployment" "coder" {
|
|||||||
|
|
||||||
For sizing recommendations, see the below reference architectures:
|
For sizing recommendations, see the below reference architectures:
|
||||||
|
|
||||||
- [Up to 1,000 users](./1k-users.md)
|
- [Up to 1,000 users](1k-users.md)
|
||||||
|
|
||||||
- [Up to 2,000 users](./2k-users.md)
|
- [Up to 2,000 users](2k-users.md)
|
||||||
|
|
||||||
- [Up to 3,000 users](./3k-users.md)
|
- [Up to 3,000 users](3k-users.md)
|
||||||
|
|
||||||
### Networking
|
### Networking
|
||||||
|
|
||||||
@ -297,8 +300,9 @@ considerations:
|
|||||||
active users.
|
active users.
|
||||||
- Enable High Availability mode for database engine for large scale deployments.
|
- Enable High Availability mode for database engine for large scale deployments.
|
||||||
|
|
||||||
If you enable [database encryption](../admin/encryption.md) in Coder, consider
|
If you enable
|
||||||
allocating an additional CPU core to every `coderd` replica.
|
[database encryption](../../../admin/security/database-encryption.md) in Coder,
|
||||||
|
consider allocating an additional CPU core to every `coderd` replica.
|
||||||
|
|
||||||
#### Resource utilization guidelines
|
#### Resource utilization guidelines
|
||||||
|
|
||||||
@ -320,27 +324,25 @@ could affect workspace users experience once the platform is live.
|
|||||||
|
|
||||||
### Helm Chart Configuration
|
### Helm Chart Configuration
|
||||||
|
|
||||||
1. Reference our [Helm chart values file](../../helm/coder/values.yaml) and
|
1. Reference our [Helm chart values file](../../../../helm/coder/values.yaml)
|
||||||
identify the required values for deployment.
|
and identify the required values for deployment.
|
||||||
1. Create a `values.yaml` and add it to your version control system.
|
1. Create a `values.yaml` and add it to your version control system.
|
||||||
1. Determine the necessary environment variables. Here is the
|
1. Determine the necessary environment variables. Here is the
|
||||||
[full list of supported server environment variables](../reference/cli/server.md).
|
[full list of supported server environment variables](../../../reference/cli/server.md).
|
||||||
1. Follow our documented
|
1. Follow our documented
|
||||||
[steps for installing Coder via Helm](../install/kubernetes.md).
|
[steps for installing Coder via Helm](../../../install/kubernetes.md).
|
||||||
|
|
||||||
### Template configuration
|
### Template configuration
|
||||||
|
|
||||||
1. Establish dedicated accounts for users with the _Template Administrator_
|
1. Establish dedicated accounts for users with the _Template Administrator_
|
||||||
role.
|
role.
|
||||||
1. Maintain Coder templates using
|
1. Maintain Coder templates using
|
||||||
[version control](../templates/change-management.md) and the
|
[version control](../../templates/managing-templates/change-management.md).
|
||||||
[coderd Terraform Provider](https://registry.terraform.io/providers/coder/coderd/latest/docs).
|
|
||||||
1. Consider implementing a GitOps workflow to automatically push new template
|
1. Consider implementing a GitOps workflow to automatically push new template
|
||||||
versions into Coder from git. For example, on Github, you can use the
|
versions into Coder from git. For example, on Github, you can use the
|
||||||
[Update Coder Template](https://github.com/marketplace/actions/update-coder-template)
|
[Setup Coder](https://github.com/marketplace/actions/setup-coder) action.
|
||||||
action.
|
|
||||||
1. Evaluate enabling
|
1. Evaluate enabling
|
||||||
[automatic template updates](../templates/general-settings.md#require-automatic-updates-enterprise)
|
[automatic template updates](../../templates/managing-templates/index.md#template-update-policies-enterprise-premium)
|
||||||
upon workspace startup.
|
upon workspace startup.
|
||||||
|
|
||||||
### Observability
|
### Observability
|
||||||
@ -352,12 +354,12 @@ could affect workspace users experience once the platform is live.
|
|||||||
leverage pre-configured dashboards, alerts, and runbooks for monitoring
|
leverage pre-configured dashboards, alerts, and runbooks for monitoring
|
||||||
Coder. This includes integrations between Prometheus, Grafana, Loki, and
|
Coder. This includes integrations between Prometheus, Grafana, Loki, and
|
||||||
Alertmanager.
|
Alertmanager.
|
||||||
1. Review the [Prometheus response](../admin/prometheus.md) and set up alarms on
|
1. Review the [Prometheus response](../../integrations/prometheus.md) and set up
|
||||||
selected metrics.
|
alarms on selected metrics.
|
||||||
|
|
||||||
### User support
|
### User support
|
||||||
|
|
||||||
1. Incorporate [support links](../admin/appearance.md#support-links) into
|
1. Incorporate [support links](../../setup/appearance.md#support-links) into
|
||||||
internal documentation accessible from the user context menu. Ensure that
|
internal documentation accessible from the user context menu. Ensure that
|
||||||
hyperlinks are valid and lead to up-to-date materials.
|
hyperlinks are valid and lead to up-to-date materials.
|
||||||
1. Encourage the use of `coder support bundle` to allow workspace users to
|
1. Encourage the use of `coder support bundle` to allow workspace users to
|
@ -1,13 +1,18 @@
|
|||||||
# Other platforms
|
# Integrations
|
||||||
|
|
||||||
Coder is highly extensible and is not limited to the platforms outlined in these
|
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
|
docs. The control plane can be provisioned on any VM or container compute, and
|
||||||
workspaces can include any Terraform resource. See our
|
workspaces can include any Terraform resource. See our
|
||||||
[architecture documentation](../architecture/architecture.md) for more details.
|
[architecture diagram](../infrastructure/architecture.md) for more details.
|
||||||
|
|
||||||
|
You can host your deployment on almost any infrastructure. To learn how, read
|
||||||
|
our [installation guides](../../install/index.md).
|
||||||
|
|
||||||
|
<children></children>
|
||||||
|
|
||||||
The following resources may help as you're deploying Coder.
|
The following resources may help as you're deploying Coder.
|
||||||
|
|
||||||
- [Coder packages: one-click install on cloud providers](https://github.com/coder/packages)
|
- [Coder packages: one-click install on cloud providers](https://github.com/coder/packages)
|
||||||
- [Deploy Coder offline](../install/offline.md)
|
- [Deploy Coder offline](../../install/offline.md)
|
||||||
- [Supported resources (Terraform registry)](https://registry.terraform.io)
|
- [Supported resources (Terraform registry)](https://registry.terraform.io)
|
||||||
- [Writing custom templates](../templates/index.md)
|
- [Writing custom templates](../templates/index.md)
|
@ -69,7 +69,7 @@ artifactory:
|
|||||||
<https://JFROG_URL/ui/admin/configuration/integrations/new> and select the
|
<https://JFROG_URL/ui/admin/configuration/integrations/new> and select the
|
||||||
Application Type as the integration you created in step 1.
|
Application Type as the integration you created in step 1.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
3. Add a new
|
3. Add a new
|
||||||
[external authentication](https://coder.com/docs/admin/external-auth) to
|
[external authentication](https://coder.com/docs/admin/external-auth) to
|
||||||
@ -94,7 +94,7 @@ CODER_EXTERNAL_AUTH_1_SCOPES="applied-permissions/user"
|
|||||||
[JFrog-OAuth](https://registry.coder.com/modules/jfrog-oauth) module to
|
[JFrog-OAuth](https://registry.coder.com/modules/jfrog-oauth) module to
|
||||||
configure the integration.
|
configure the integration.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
module "jfrog" {
|
module "jfrog" {
|
||||||
source = "registry.coder.com/modules/jfrog-oauth/coder"
|
source = "registry.coder.com/modules/jfrog-oauth/coder"
|
||||||
version = "1.0.0"
|
version = "1.0.0"
|
||||||
@ -129,7 +129,7 @@ To set this up, follow these steps:
|
|||||||
store the token in a sensitive terraform variable to prevent it from being
|
store the token in a sensitive terraform variable to prevent it from being
|
||||||
displayed in plain text in the terraform state.
|
displayed in plain text in the terraform state.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
variable "artifactory_access_token" {
|
variable "artifactory_access_token" {
|
||||||
type = string
|
type = string
|
||||||
sensitive = true
|
sensitive = true
|
||||||
@ -162,7 +162,8 @@ concepts apply to all compute types.
|
|||||||
|
|
||||||
## Offline Deployments
|
## Offline Deployments
|
||||||
|
|
||||||
See the [offline deployments](../templates/modules.md#offline-installations)
|
See the
|
||||||
|
[offline deployments](../templates/extending-templates/modules.md#offline-installations)
|
||||||
section for instructions on how to use coder-modules in an offline environment
|
section for instructions on how to use coder-modules in an offline environment
|
||||||
with Artifactory.
|
with Artifactory.
|
||||||
|
|
||||||
@ -172,5 +173,3 @@ with Artifactory.
|
|||||||
[here](https://github.com/coder/coder/tree/main/examples/jfrog/docker).
|
[here](https://github.com/coder/coder/tree/main/examples/jfrog/docker).
|
||||||
- To serve extensions from your own VS Code Marketplace, check out
|
- To serve extensions from your own VS Code Marketplace, check out
|
||||||
[code-marketplace](https://github.com/coder/code-marketplace#artifactory-storage).
|
[code-marketplace](https://github.com/coder/code-marketplace#artifactory-storage).
|
||||||
- To store templates in Artifactory, check out our
|
|
||||||
[Artifactory modules](../templates/modules.md#artifactory) docs.
|
|
@ -26,30 +26,29 @@ using Coder's [JFrog Xray Integration](https://github.com/coder/coder-xray).
|
|||||||
with a user that has the read
|
with a user that has the read
|
||||||
[permission](https://jfrog.com/help/r/jfrog-platform-administration-documentation/permissions)
|
[permission](https://jfrog.com/help/r/jfrog-platform-administration-documentation/permissions)
|
||||||
for the repositories you want to scan.
|
for the repositories you want to scan.
|
||||||
2. Create a Coder
|
1. Create a Coder [token](../../reference/cli/tokens_create.md#tokens-create)
|
||||||
[token](https://coder.com/docs/cli/tokens_create#tokens-create) with a user
|
with a user that has the [`owner`](../users#roles) role.
|
||||||
that has the [`owner`](https://coder.com/docs/admin/users#roles) role.
|
1. Create Kubernetes secrets for the JFrog Xray and Coder tokens.
|
||||||
3. Create kubernetes secrets for the JFrog Xray and Coder tokens.
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
kubectl create secret generic coder-token --from-literal=coder-token='<token>'
|
kubectl create secret generic coder-token --from-literal=coder-token='<token>'
|
||||||
kubectl create secret generic jfrog-token --from-literal=user='<user>' --from-literal=token='<token>'
|
kubectl create secret generic jfrog-token --from-literal=user='<user>' --from-literal=token='<token>'
|
||||||
```
|
```
|
||||||
|
|
||||||
4. Deploy the Coder - JFrog Xray integration.
|
1. Deploy the Coder - JFrog Xray integration.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
helm repo add coder-xray https://helm.coder.com/coder-xray
|
helm repo add coder-xray https://helm.coder.com/coder-xray
|
||||||
|
|
||||||
helm upgrade --install coder-xray coder-xray/coder-xray \
|
helm upgrade --install coder-xray coder-xray/coder-xray \
|
||||||
--namespace coder-xray \
|
--namespace coder-xray \
|
||||||
--create-namespace \
|
--create-namespace \
|
||||||
--set namespace="<CODER_WORKSPACES_NAMESPACE>" \ # Replace with your Coder workspaces namespace
|
--set namespace="<CODER_WORKSPACES_NAMESPACE>" \ # Replace with your Coder workspaces namespace
|
||||||
--set coder.url="https://<your-coder-url>" \
|
--set coder.url="https://<your-coder-url>" \
|
||||||
--set coder.secretName="coder-token" \
|
--set coder.secretName="coder-token" \
|
||||||
--set artifactory.url="https://<your-artifactory-url>" \
|
--set artifactory.url="https://<your-artifactory-url>" \
|
||||||
--set artifactory.secretName="jfrog-token"
|
--set artifactory.secretName="jfrog-token"
|
||||||
```
|
```
|
||||||
|
|
||||||
### Updating the Coder template
|
### Updating the Coder template
|
||||||
|
|
||||||
@ -66,6 +65,6 @@ image = "<ARTIFACTORY_URL>/<REPO>/<IMAGE>:<TAG>"
|
|||||||
> create a
|
> create a
|
||||||
> [Docker config](https://jfrog.com/help/r/jfrog-artifactory-documentation/docker-advanced-topics)
|
> [Docker config](https://jfrog.com/help/r/jfrog-artifactory-documentation/docker-advanced-topics)
|
||||||
> and use it in the `imagePullSecrets` field of the kubernetes pod. See this
|
> and use it in the `imagePullSecrets` field of the kubernetes pod. See this
|
||||||
> [guide](./image-pull-secret.md) for more information.
|
> [guide](../../tutorials/image-pull-secret.md) for more information.
|
||||||
|
|
||||||

|

|
@ -50,19 +50,19 @@ logs:
|
|||||||
|
|
||||||
### Normal pod deployment
|
### Normal pod deployment
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
### Wrong image
|
### Wrong image
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
### Kubernetes quota exceeded
|
### Kubernetes quota exceeded
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
### Pod crash loop
|
### Pod crash loop
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
## How it works
|
## How it works
|
||||||
|
|
@ -5,7 +5,7 @@ different
|
|||||||
[authentication methods](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#authentication)
|
[authentication methods](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#authentication)
|
||||||
in the Terraform provider.
|
in the Terraform provider.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
## Option 1) Kubernetes contexts and kubeconfig
|
## Option 1) Kubernetes contexts and kubeconfig
|
||||||
|
|
||||||
@ -58,10 +58,11 @@ If you deployed Coder on a VM, copy the kubeconfig file to
|
|||||||
|
|
||||||
You can start from our
|
You can start from our
|
||||||
[example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes).
|
[example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes).
|
||||||
From there, add [template parameters](../../templates/parameters.md) to allow
|
From there, add
|
||||||
|
[template parameters](../templates/extending-templates/parameters.md) to allow
|
||||||
developers to pick their desired cluster.
|
developers to pick their desired cluster.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
# main.tf
|
# main.tf
|
||||||
|
|
||||||
data "coder_parameter" "kube_context" {
|
data "coder_parameter" "kube_context" {
|
||||||
@ -91,7 +92,7 @@ provider "kubernetes" {
|
|||||||
|
|
||||||
Alternatively, you can authenticate with remote clusters with ServiceAccount
|
Alternatively, you can authenticate with remote clusters with ServiceAccount
|
||||||
tokens. Coder can store these secrets on your behalf with
|
tokens. Coder can store these secrets on your behalf with
|
||||||
[managed Terraform variables](../../templates/variables.md).
|
[managed Terraform variables](../templates/extending-templates/variables.md).
|
||||||
|
|
||||||
Alternatively, these could also be fetched from Kubernetes secrets or even
|
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).
|
[Hashicorp Vault](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret).
|
||||||
@ -99,16 +100,30 @@ Alternatively, these could also be fetched from Kubernetes secrets or even
|
|||||||
This guide assumes you have a `coder-workspaces` namespace on your remote
|
This guide assumes you have a `coder-workspaces` namespace on your remote
|
||||||
cluster. Change the namespace accordingly.
|
cluster. Change the namespace accordingly.
|
||||||
|
|
||||||
### Create a Role and RoleBinding
|
### Create a ServiceAccount
|
||||||
|
|
||||||
Run this command against your remote cluster to create a Role and RoleBinding:
|
Run this command against your remote cluster to create a ServiceAccount, Role,
|
||||||
|
RoleBinding, and token:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
kubectl apply -n coder-workspaces -f - <<EOF
|
kubectl apply -n coder-workspaces -f - <<EOF
|
||||||
|
apiVersion: v1
|
||||||
|
kind: ServiceAccount
|
||||||
|
metadata:
|
||||||
|
name: coder-v2
|
||||||
|
---
|
||||||
|
apiVersion: v1
|
||||||
|
kind: Secret
|
||||||
|
metadata:
|
||||||
|
name: coder-v2
|
||||||
|
annotations:
|
||||||
|
kubernetes.io/service-account.name: coder-v2
|
||||||
|
type: kubernetes.io/service-account-token
|
||||||
|
---
|
||||||
apiVersion: rbac.authorization.k8s.io/v1
|
apiVersion: rbac.authorization.k8s.io/v1
|
||||||
kind: Role
|
kind: Role
|
||||||
metadata:
|
metadata:
|
||||||
name: coder-workspaces
|
name: coder-v2
|
||||||
rules:
|
rules:
|
||||||
- apiGroups: ["", "apps", "networking.k8s.io"]
|
- apiGroups: ["", "apps", "networking.k8s.io"]
|
||||||
resources: ["persistentvolumeclaims", "pods", "deployments", "services", "secrets", "pods/exec","pods/log", "events", "networkpolicies", "serviceaccounts"]
|
resources: ["persistentvolumeclaims", "pods", "deployments", "services", "secrets", "pods/exec","pods/log", "events", "networkpolicies", "serviceaccounts"]
|
||||||
@ -120,13 +135,13 @@ rules:
|
|||||||
apiVersion: rbac.authorization.k8s.io/v1
|
apiVersion: rbac.authorization.k8s.io/v1
|
||||||
kind: RoleBinding
|
kind: RoleBinding
|
||||||
metadata:
|
metadata:
|
||||||
name: coder-workspaces
|
name: coder-v2
|
||||||
subjects:
|
subjects:
|
||||||
- kind: ServiceAccount
|
- kind: ServiceAccount
|
||||||
name: coder
|
name: coder-v2
|
||||||
roleRef:
|
roleRef:
|
||||||
kind: Role
|
kind: Role
|
||||||
name: coder-workspaces
|
name: coder-v2
|
||||||
apiGroup: rbac.authorization.k8s.io
|
apiGroup: rbac.authorization.k8s.io
|
||||||
EOF
|
EOF
|
||||||
```
|
```
|
||||||
@ -134,8 +149,10 @@ EOF
|
|||||||
The output should be similar to:
|
The output should be similar to:
|
||||||
|
|
||||||
```text
|
```text
|
||||||
role.rbac.authorization.k8s.io/coder-workspaces created
|
serviceaccount/coder-v2 created
|
||||||
rolebinding.rbac.authorization.k8s.io/coder-workspaces created
|
secret/coder-v2 created
|
||||||
|
role.rbac.authorization.k8s.io/coder-v2 created
|
||||||
|
rolebinding.rbac.authorization.k8s.io/coder-v2 created
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2. Modify the Kubernetes template
|
### 2. Modify the Kubernetes template
|
||||||
@ -143,7 +160,7 @@ rolebinding.rbac.authorization.k8s.io/coder-workspaces created
|
|||||||
You can start from our
|
You can start from our
|
||||||
[example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes).
|
[example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes).
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
variable "host" {
|
variable "host" {
|
||||||
description = "Cluster host address"
|
description = "Cluster host address"
|
||||||
sensitive = true
|
sensitive = true
|
23
docs/admin/integrations/opentofu.md
Normal file
23
docs/admin/integrations/opentofu.md
Normal file
@ -0,0 +1,23 @@
|
|||||||
|
# Provisioning with OpenTofu
|
||||||
|
|
||||||
|
<!-- Keeping this in as a placeholder for supporting OpenTofu. We should fix support for custom terraform binaries ASAP. -->
|
||||||
|
|
||||||
|
> ⚠️ This guide is a work in progress. We do not officially support using custom
|
||||||
|
> Terraform binaries in your Coder deployment. To track progress on the work,
|
||||||
|
> see this related [Github Issue](https://github.com/coder/coder/issues/12009).
|
||||||
|
|
||||||
|
Coder deployments support any custom Terraform binary, including
|
||||||
|
[OpenTofu](https://opentofu.org/docs/) - an open source alternative to
|
||||||
|
Terraform.
|
||||||
|
|
||||||
|
> You can read more about OpenTofu and Hashicorp's licensing in our
|
||||||
|
> [blog post](https://coder.com/blog/hashicorp-license) on the Terraform
|
||||||
|
> licensing changes.
|
||||||
|
|
||||||
|
## Using a custom Terraform binary
|
||||||
|
|
||||||
|
You can change your deployment custom Terraform binary as long as it is in
|
||||||
|
`PATH` and is within the
|
||||||
|
[supported versions](https://github.com/coder/coder/blob/f57ce97b5aadd825ddb9a9a129bb823a3725252b/provisioner/terraform/install.go#L22-L25).
|
||||||
|
The hardcoded version check ensures compatibility with our
|
||||||
|
[example templates](https://github.com/coder/coder/tree/main/examples/templates).
|
@ -101,7 +101,7 @@ spec:
|
|||||||
`CODER_PROMETHEUS_COLLECT_AGENT_STATS` before they can be retrieved from the
|
`CODER_PROMETHEUS_COLLECT_AGENT_STATS` before they can be retrieved from the
|
||||||
deployment. They will always be available from the agent.
|
deployment. They will always be available from the agent.
|
||||||
|
|
||||||
<!-- Code generated by 'make docs/admin/prometheus.md'. DO NOT EDIT -->
|
<!-- Code generated by 'make docs/admin/integrations/prometheus.md'. DO NOT EDIT -->
|
||||||
|
|
||||||
| Name | Type | Description | Labels |
|
| Name | Type | Description | Labels |
|
||||||
| ------------------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
|
| ------------------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
|
||||||
@ -183,4 +183,4 @@ deployment. They will always be available from the agent.
|
|||||||
| `promhttp_metric_handler_requests_in_flight` | gauge | Current number of scrapes being served. | |
|
| `promhttp_metric_handler_requests_in_flight` | gauge | Current number of scrapes being served. | |
|
||||||
| `promhttp_metric_handler_requests_total` | counter | Total number of scrapes by HTTP status code. | `code` |
|
| `promhttp_metric_handler_requests_total` | counter | Total number of scrapes by HTTP status code. | `code` |
|
||||||
|
|
||||||
<!-- End generated by 'make docs/admin/prometheus.md'. -->
|
<!-- End generated by 'make docs/admin/integrations/prometheus.md'. -->
|
48
docs/admin/integrations/vault.md
Normal file
48
docs/admin/integrations/vault.md
Normal file
@ -0,0 +1,48 @@
|
|||||||
|
# Integrating HashiCorp Vault with Coder
|
||||||
|
|
||||||
|
<div>
|
||||||
|
<a href="https://github.com/matifali" style="text-decoration: none; color: inherit;">
|
||||||
|
<span style="vertical-align:middle;">Muhammad Atif Ali</span>
|
||||||
|
<img src="https://github.com/matifali.png" width="24px" height="24px" style="vertical-align:middle; margin: 0px;"/>
|
||||||
|
</a>
|
||||||
|
</div>
|
||||||
|
August 05, 2024
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
This guide will walk you through the process of adding
|
||||||
|
[HashiCorp Vault](https://www.vaultproject.io/) integration to Coder workspaces.
|
||||||
|
|
||||||
|
Coder makes it easy to integrate HashiCorp Vault with your workspaces by
|
||||||
|
providing official terraform modules to integrate Vault with Coder. This guide
|
||||||
|
will show you how to use these modules to integrate HashiCorp Vault with Coder.
|
||||||
|
|
||||||
|
## `vault-github`
|
||||||
|
|
||||||
|
[`vault-github`](https://registry.coder.com/modules/vault-github) is a terraform
|
||||||
|
module that allows you to authenticate with Vault using a GitHub token. This
|
||||||
|
modules uses the existing GitHub [external authentication](../external-auth.md)
|
||||||
|
to get the token and authenticate with Vault.
|
||||||
|
|
||||||
|
To use this module, you need to add the following code to your terraform
|
||||||
|
configuration:
|
||||||
|
|
||||||
|
```tf
|
||||||
|
module "vault" {
|
||||||
|
source = "registry.coder.com/modules/vault-github/coder"
|
||||||
|
version = "1.0.7"
|
||||||
|
agent_id = coder_agent.example.id
|
||||||
|
vault_addr = "https://vault.example.com"
|
||||||
|
coder_github_auth_id = "my-github-auth-id"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This module will install and authenticate the `vault` CLI in your Coder
|
||||||
|
workspace.
|
||||||
|
|
||||||
|
Users then can use the `vault` CLI to interact with the vault, e.g., to het a kv
|
||||||
|
secret,
|
||||||
|
|
||||||
|
```shell
|
||||||
|
vault kv get -namespace=YOUR_NAMESPACE -mount=MOUNT_NAME SECRET_NAME
|
||||||
|
```
|
@ -26,13 +26,13 @@ First, ensure you have a license key
|
|||||||
With an `Owner` account, navigate to `Deployment -> Licenses`, `Add a license`
|
With an `Owner` account, navigate to `Deployment -> Licenses`, `Add a license`
|
||||||
then drag or select the license file with the `jwt` extension.
|
then drag or select the license file with the `jwt` extension.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
### Coder CLI
|
### Coder CLI
|
||||||
|
|
||||||
First, ensure you have a license key
|
First, ensure you have a license key
|
||||||
([request a trial](https://coder.com/trial)) and the
|
([request a trial](https://coder.com/trial)) and the
|
||||||
[Coder CLI](./install/index.md) installed.
|
[Coder CLI](../../install/cli.md) installed.
|
||||||
|
|
||||||
1. Save your license key to disk and make note of the path
|
1. Save your license key to disk and make note of the path
|
||||||
2. Open a terminal
|
2. Open a terminal
|
@ -3,16 +3,18 @@
|
|||||||
Coder includes an operator-friendly deployment health page that provides a
|
Coder includes an operator-friendly deployment health page that provides a
|
||||||
number of details about the health of your Coder deployment.
|
number of details about the health of your Coder deployment.
|
||||||
|
|
||||||
|

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

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

|
22
docs/admin/monitoring/metrics.md
Normal file
22
docs/admin/monitoring/metrics.md
Normal file
@ -0,0 +1,22 @@
|
|||||||
|
# Deployment Metrics
|
||||||
|
|
||||||
|
Coder exposes many metrics which give insight into the current state of a live
|
||||||
|
Coder deployment. Our metrics are designed to be consumed by a
|
||||||
|
[Prometheus server](https://prometheus.io/).
|
||||||
|
|
||||||
|
If you don't have an Prometheus server installed, you can follow the Prometheus
|
||||||
|
[Getting started](https://prometheus.io/docs/prometheus/latest/getting_started/)
|
||||||
|
guide.
|
||||||
|
|
||||||
|
### Setting up metrics
|
||||||
|
|
||||||
|
To set up metrics monitoring, please read our
|
||||||
|
[Prometheus integration guide](../integrations/prometheus.md). The following
|
||||||
|
links point to relevant sections there.
|
||||||
|
|
||||||
|
- [Enable Prometheus metrics](../integrations/prometheus.md#enable-prometheus-metrics)
|
||||||
|
in the control plane
|
||||||
|
- [Enable the Prometheus endpoint in Helm](../integrations/prometheus.md#kubernetes-deployment)
|
||||||
|
(Kubernetes users only)
|
||||||
|
- [Configure Prometheus to scrape Coder metrics](../integrations/prometheus.md#prometheus-configuration)
|
||||||
|
- [See the list of available metrics](../integrations/prometheus.md#available-metrics)
|
@ -3,12 +3,11 @@
|
|||||||
Notifications are sent by Coder in response to specific internal events, such as
|
Notifications are sent by Coder in response to specific internal events, such as
|
||||||
a workspace being deleted or a user being created.
|
a workspace being deleted or a user being created.
|
||||||
|
|
||||||
**Notifications are currently an experimental feature.**
|
|
||||||
|
|
||||||
## Enable experiment
|
## Enable experiment
|
||||||
|
|
||||||
In order to activate the notifications feature, you'll need to enable the
|
In order to activate the notifications feature on Coder v2.15.X, you'll need to
|
||||||
`notifications` experiment.
|
enable the `notifications` experiment. Notifications are enabled by default
|
||||||
|
starting in v2.16.0.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Using the CLI flag
|
# Using the CLI flag
|
||||||
@ -74,7 +73,7 @@ flags.
|
|||||||
|
|
||||||
Notifications can currently be delivered by either SMTP or webhook. Each message
|
Notifications can currently be delivered by either SMTP or webhook. Each message
|
||||||
can only be delivered to one method, and this method is configured globally with
|
can only be delivered to one method, and this method is configured globally with
|
||||||
[`CODER_NOTIFICATIONS_METHOD`](https://coder.com/docs/reference/cli/server#--notifications-method)
|
[`CODER_NOTIFICATIONS_METHOD`](../../../reference/cli/server.md#--notifications-method)
|
||||||
(default: `smtp`).
|
(default: `smtp`).
|
||||||
|
|
||||||
Enterprise customers can configure which method to use for each of the supported
|
Enterprise customers can configure which method to use for each of the supported
|
||||||
@ -229,14 +228,14 @@ All users have the option to opt-out of any notifications. Go to **Account** ->
|
|||||||
**Notifications** to turn notifications on or off. The delivery method for each
|
**Notifications** to turn notifications on or off. The delivery method for each
|
||||||
notification is indicated on the right hand side of this table.
|
notification is indicated on the right hand side of this table.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
## Delivery Preferences (enterprise) (premium)
|
## Delivery Preferences (enterprise) (premium)
|
||||||
|
|
||||||
Administrators can configure which delivery methods are used for each different
|
Administrators can configure which delivery methods are used for each different
|
||||||
[event type](#event-types).
|
[event type](#event-types).
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
You can find this page under
|
You can find this page under
|
||||||
`https://$CODER_ACCESS_URL/deployment/notifications?tab=events`.
|
`https://$CODER_ACCESS_URL/deployment/notifications?tab=events`.
|
||||||
@ -247,10 +246,10 @@ Administrators may wish to stop _all_ notifications across the deployment. We
|
|||||||
support a killswitch in the CLI for these cases.
|
support a killswitch in the CLI for these cases.
|
||||||
|
|
||||||
To pause sending notifications, execute
|
To pause sending notifications, execute
|
||||||
[`coder notifications pause`](https://coder.com/docs/reference/cli/notifications_pause).
|
[`coder notifications pause`](../../../reference/cli/notifications_pause.md).
|
||||||
|
|
||||||
To resume sending notifications, execute
|
To resume sending notifications, execute
|
||||||
[`coder notifications resume`](https://coder.com/docs/reference/cli/notifications_resume).
|
[`coder notifications resume`](../../../reference/cli/notifications_resume.md).
|
||||||
|
|
||||||
## Troubleshooting
|
## Troubleshooting
|
||||||
|
|
||||||
@ -277,7 +276,7 @@ Messages older than 7 days are deleted.
|
|||||||
|
|
||||||
### Message States
|
### Message States
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
_A notifier here refers to a Coder replica which is responsible for dispatching
|
_A notifier here refers to a Coder replica which is responsible for dispatching
|
||||||
the notification. All running replicas act as notifiers to process pending
|
the notification. All running replicas act as notifiers to process pending
|
@ -17,8 +17,8 @@ consistent between Slack and their Coder login.
|
|||||||
Before setting up Slack notifications, ensure that you have the following:
|
Before setting up Slack notifications, ensure that you have the following:
|
||||||
|
|
||||||
- Administrator access to the Slack platform to create apps
|
- Administrator access to the Slack platform to create apps
|
||||||
- Coder platform with
|
- Coder platform v2.15.0 or greater with
|
||||||
[notifications enabled](../notifications#enable-experiment)
|
[notifications enabled](./index.md#enable-experiment) for versions <v2.16.0
|
||||||
|
|
||||||
## Create Slack Application
|
## Create Slack Application
|
||||||
|
|
||||||
@ -90,11 +90,9 @@ receiver.router.post("/v1/webhook", async (req, res) => {
|
|||||||
return res.status(400).send("Error: request body is missing");
|
return res.status(400).send("Error: request body is missing");
|
||||||
}
|
}
|
||||||
|
|
||||||
const { title_markdown, body_markdown } = req.body;
|
const { title, body } = req.body;
|
||||||
if (!title_markdown || !body_markdown) {
|
if (!title || !body) {
|
||||||
return res
|
return res.status(400).send('Error: missing fields: "title", or "body"');
|
||||||
.status(400)
|
|
||||||
.send('Error: missing fields: "title_markdown", or "body_markdown"');
|
|
||||||
}
|
}
|
||||||
|
|
||||||
const payload = req.body.payload;
|
const payload = req.body.payload;
|
||||||
@ -120,11 +118,11 @@ receiver.router.post("/v1/webhook", async (req, res) => {
|
|||||||
blocks: [
|
blocks: [
|
||||||
{
|
{
|
||||||
type: "header",
|
type: "header",
|
||||||
text: { type: "mrkdwn", text: title_markdown },
|
text: { type: "plain_text", text: title },
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
type: "section",
|
type: "section",
|
||||||
text: { type: "mrkdwn", text: body_markdown },
|
text: { type: "mrkdwn", text: body },
|
||||||
},
|
},
|
||||||
],
|
],
|
||||||
};
|
};
|
||||||
@ -194,12 +192,9 @@ must respond appropriately.
|
|||||||
|
|
||||||
## Enable Webhook Integration in Coder
|
## Enable Webhook Integration in Coder
|
||||||
|
|
||||||
To enable webhook integration in Coder, ensure the "notifications" experiment is
|
To enable webhook integration in Coder, ensure the "notifications"
|
||||||
activated by running the following command:
|
[experiment is activated](./index.md#enable-experiment) (only required in
|
||||||
|
v2.15.X).
|
||||||
```bash
|
|
||||||
export CODER_EXPERIMENTS=notifications
|
|
||||||
```
|
|
||||||
|
|
||||||
Then, define the POST webhook endpoint matching the deployed Slack bot:
|
Then, define the POST webhook endpoint matching the deployed Slack bot:
|
||||||
|
|
@ -15,7 +15,7 @@ Before setting up Microsoft Teams notifications, ensure that you have the
|
|||||||
following:
|
following:
|
||||||
|
|
||||||
- Administrator access to the Teams platform
|
- Administrator access to the Teams platform
|
||||||
- Coder platform with notifications enabled
|
- Coder platform with [notifications enabled](./index.md#enable-experiment)
|
||||||
|
|
||||||
## Build Teams Workflow
|
## Build Teams Workflow
|
||||||
|
|
||||||
@ -67,10 +67,10 @@ The process of setting up a Teams workflow consists of three key steps:
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
"title_markdown": {
|
"title": {
|
||||||
"type": "string"
|
"type": "string"
|
||||||
},
|
},
|
||||||
"body_markdown": {
|
"body": {
|
||||||
"type": "string"
|
"type": "string"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@ -108,11 +108,11 @@ The process of setting up a Teams workflow consists of three key steps:
|
|||||||
},
|
},
|
||||||
{
|
{
|
||||||
"type": "TextBlock",
|
"type": "TextBlock",
|
||||||
"text": "**@{replace(body('Parse_JSON')?['title_markdown'], '"', '\"')}**"
|
"text": "**@{replace(body('Parse_JSON')?['title'], '"', '\"')}**"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"type": "TextBlock",
|
"type": "TextBlock",
|
||||||
"text": "@{replace(body('Parse_JSON')?['body_markdown'], '"', '\"')}",
|
"text": "@{replace(body('Parse_JSON')?['body'], '"', '\"')}",
|
||||||
"wrap": true
|
"wrap": true
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
@ -133,12 +133,9 @@ The process of setting up a Teams workflow consists of three key steps:
|
|||||||
|
|
||||||
## Enable Webhook Integration
|
## Enable Webhook Integration
|
||||||
|
|
||||||
To enable webhook integration in Coder, ensure the "notifications" experiment is
|
To enable webhook integration in Coder, ensure the "notifications"
|
||||||
activated by running the following command:
|
[experiment is activated](./index.md#enable-experiment) (only required in
|
||||||
|
v2.15.X).
|
||||||
```bash
|
|
||||||
export CODER_EXPERIMENTS=notifications
|
|
||||||
```
|
|
||||||
|
|
||||||
Then, define the POST webhook endpoint created by your Teams workflow:
|
Then, define the POST webhook endpoint created by your Teams workflow:
|
||||||
|
|
@ -32,10 +32,9 @@ connect to the same Postgres endpoint.
|
|||||||
HA brings one configuration variable to set in each Coderd node:
|
HA brings one configuration variable to set in each Coderd node:
|
||||||
`CODER_DERP_SERVER_RELAY_URL`. The HA nodes use these URLs to communicate with
|
`CODER_DERP_SERVER_RELAY_URL`. The HA nodes use these URLs to communicate with
|
||||||
each other. Inter-node communication is only required while using the embedded
|
each other. Inter-node communication is only required while using the embedded
|
||||||
relay (default). If you're using
|
relay (default). If you're using [custom relays](./index.md#custom-relays),
|
||||||
[custom relays](../networking/index.md#custom-relays), Coder ignores
|
Coder ignores `CODER_DERP_SERVER_RELAY_URL` since Postgres is the sole
|
||||||
`CODER_DERP_SERVER_RELAY_URL` since Postgres is the sole rendezvous for the
|
rendezvous for the Coder nodes.
|
||||||
Coder nodes.
|
|
||||||
|
|
||||||
`CODER_DERP_SERVER_RELAY_URL` will never be `CODER_ACCESS_URL` because
|
`CODER_DERP_SERVER_RELAY_URL` will never be `CODER_ACCESS_URL` because
|
||||||
`CODER_ACCESS_URL` is a load balancer to all Coder nodes.
|
`CODER_ACCESS_URL` is a load balancer to all Coder nodes.
|
||||||
@ -51,7 +50,7 @@ Here's an example 3-node network configuration setup:
|
|||||||
## Kubernetes
|
## Kubernetes
|
||||||
|
|
||||||
If you installed Coder via
|
If you installed Coder via
|
||||||
[our Helm Chart](../install/kubernetes.md#install-coder-with-helm), just
|
[our Helm Chart](../../install/kubernetes.md#4-install-coder-with-helm), just
|
||||||
increase `coder.replicaCount` in `values.yaml`.
|
increase `coder.replicaCount` in `values.yaml`.
|
||||||
|
|
||||||
If you installed Coder into Kubernetes by some other means, insert the relay URL
|
If you installed Coder into Kubernetes by some other means, insert the relay URL
|
||||||
@ -71,5 +70,5 @@ Then, increase the number of pods.
|
|||||||
|
|
||||||
## Up next
|
## Up next
|
||||||
|
|
||||||
- [Networking](../networking/index.md)
|
- [Read more on Coder's networking stack](./index.md)
|
||||||
- [Kubernetes](../install/kubernetes.md)
|
- [Install on Kubernetes](../../install/kubernetes.md)
|
@ -17,6 +17,14 @@ user <-> workspace connections are end-to-end encrypted.
|
|||||||
|
|
||||||
In order for clients and workspaces to be able to connect:
|
In order for clients and workspaces to be able to connect:
|
||||||
|
|
||||||
|
> **Note:** We strongly recommend that clients connect to Coder and their
|
||||||
|
> workspaces over a good quality, broadband network connection. The following
|
||||||
|
> are minimum requirements:
|
||||||
|
>
|
||||||
|
> - better than 400ms round-trip latency to the Coder server and to their
|
||||||
|
> workspace
|
||||||
|
> - better than 0.5% random packet loss
|
||||||
|
|
||||||
- All clients and agents must be able to establish a connection to the Coder
|
- All clients and agents must be able to establish a connection to the Coder
|
||||||
server (`CODER_ACCESS_URL`) over HTTP/HTTPS.
|
server (`CODER_ACCESS_URL`) over HTTP/HTTPS.
|
||||||
- Any reverse proxy or ingress between the Coder control plane and
|
- Any reverse proxy or ingress between the Coder control plane and
|
||||||
@ -35,20 +43,20 @@ In order for clients to be able to establish direct connections:
|
|||||||
> **Note:** Direct connections via the web browser are not supported. To improve
|
> **Note:** Direct connections via the web browser are not supported. To improve
|
||||||
> latency for browser-based applications running inside Coder workspaces in
|
> latency for browser-based applications running inside Coder workspaces in
|
||||||
> regions far from the Coder control plane, consider deploying one or more
|
> regions far from the Coder control plane, consider deploying one or more
|
||||||
> [workspace proxies](../admin/workspace-proxies.md).
|
> [workspace proxies](./workspace-proxies.md).
|
||||||
|
|
||||||
- The client is connecting using the CLI (e.g. `coder ssh` or
|
- The client is connecting using the CLI (e.g. `coder ssh` or
|
||||||
`coder port-forward`). Note that the
|
`coder port-forward`). Note that the
|
||||||
[VSCode extension](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote)
|
[VSCode extension](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote)
|
||||||
and [JetBrains Plugin](https://plugins.jetbrains.com/plugin/19620-coder/), and
|
and [JetBrains Plugin](https://plugins.jetbrains.com/plugin/19620-coder/), and
|
||||||
[`ssh coder.<workspace>`](../reference/cli/config-ssh.md) all utilize the CLI
|
[`ssh coder.<workspace>`](../../reference/cli/config-ssh.md) all utilize the
|
||||||
to establish a workspace connection.
|
CLI to establish a workspace connection.
|
||||||
- Either the client or workspace agent are able to discover a reachable
|
- Either the client or workspace agent are able to discover a reachable
|
||||||
`ip:port` of their counterpart. If the agent and client are able to
|
`ip:port` of their counterpart. If the agent and client are able to
|
||||||
communicate with each other using their locally assigned IP addresses, then a
|
communicate with each other using their locally assigned IP addresses, then a
|
||||||
direct connection can be established immediately. Otherwise, the client and
|
direct connection can be established immediately. Otherwise, the client and
|
||||||
agent will contact
|
agent will contact
|
||||||
[the configured STUN servers](../reference/cli/server.md#derp-server-stun-addresses)
|
[the configured STUN servers](../../reference/cli/server.md#derp-server-stun-addresses)
|
||||||
to try and determine which `ip:port` can be used to communicate with their
|
to try and determine which `ip:port` can be used to communicate with their
|
||||||
counterpart. See [STUN and NAT](./stun.md) for more details on how this
|
counterpart. See [STUN and NAT](./stun.md) for more details on how this
|
||||||
process works.
|
process works.
|
||||||
@ -56,9 +64,9 @@ In order for clients to be able to establish direct connections:
|
|||||||
**all ports** to each others' respective networks.
|
**all ports** to each others' respective networks.
|
||||||
- To establish a direct connection, both agent and client use STUN. This
|
- To establish a direct connection, both agent and client use STUN. This
|
||||||
involves sending UDP packets outbound on `udp/3478` to the configured
|
involves sending UDP packets outbound on `udp/3478` to the configured
|
||||||
[STUN server](../reference/cli/server.md#--derp-server-stun-addresses). If
|
[STUN server](../../reference/cli/server.md#--derp-server-stun-addresses).
|
||||||
either the agent or the client are unable to send and receive UDP packets to
|
If either the agent or the client are unable to send and receive UDP packets
|
||||||
a STUN server, then direct connections will not be possible.
|
to a STUN server, then direct connections will not be possible.
|
||||||
- Both agents and clients will then establish a
|
- Both agents and clients will then establish a
|
||||||
[WireGuard](https://www.wireguard.com/)️ tunnel and send UDP traffic on
|
[WireGuard](https://www.wireguard.com/)️ tunnel and send UDP traffic on
|
||||||
ephemeral (high) ports. If a firewall between the client and the agent
|
ephemeral (high) ports. If a firewall between the client and the agent
|
||||||
@ -67,8 +75,8 @@ In order for clients to be able to establish direct connections:
|
|||||||
## coder server
|
## coder server
|
||||||
|
|
||||||
Workspaces connect to the coder server via the server's external address, set
|
Workspaces connect to the coder server via the server's external address, set
|
||||||
via [`ACCESS_URL`](../admin/configure.md#access-url). There must not be a NAT
|
via [`ACCESS_URL`](../../admin/setup/index.md#access-url). There must not be a
|
||||||
between workspaces and coder server.
|
NAT between workspaces and coder server.
|
||||||
|
|
||||||
Users connect to the coder server's dashboard and API through its `ACCESS_URL`
|
Users connect to the coder server's dashboard and API through its `ACCESS_URL`
|
||||||
as well. There must not be a NAT between users and the coder server.
|
as well. There must not be a NAT between users and the coder server.
|
||||||
@ -111,14 +119,14 @@ for more information on how this process works.
|
|||||||
|
|
||||||
If a direct connection is not available (e.g. client or server is behind NAT),
|
If a direct connection is not available (e.g. client or server is behind NAT),
|
||||||
Coder will use a relayed connection. By default,
|
Coder will use a relayed connection. By default,
|
||||||
[Coder uses Google's public STUN server](../reference/cli/server.md#--derp-server-stun-addresses),
|
[Coder uses Google's public STUN server](../../reference/cli/server.md#--derp-server-stun-addresses),
|
||||||
but this can be disabled or changed for
|
but this can be disabled or changed for
|
||||||
[offline deployments](../install/offline.md).
|
[offline deployments](../../install/offline.md).
|
||||||
|
|
||||||
### Relayed connections
|
### Relayed connections
|
||||||
|
|
||||||
By default, your Coder server also runs a built-in DERP relay which can be used
|
By default, your Coder server also runs a built-in DERP relay which can be used
|
||||||
for both public and [offline deployments](../install/offline.md).
|
for both public and [offline deployments](../../install/offline.md).
|
||||||
|
|
||||||
However, Tailscale has graciously allowed us to use
|
However, Tailscale has graciously allowed us to use
|
||||||
[their global DERP relays](https://tailscale.com/kb/1118/custom-derp-servers/#what-are-derp-servers).
|
[their global DERP relays](https://tailscale.com/kb/1118/custom-derp-servers/#what-are-derp-servers).
|
||||||
@ -165,8 +173,8 @@ $ coder server --derp-config-path derpmap.json
|
|||||||
|
|
||||||
The dashboard (and web apps opened through the dashboard) are served from the
|
The dashboard (and web apps opened through the dashboard) are served from the
|
||||||
coder server, so they can only be geo-distributed with High Availability mode in
|
coder server, so they can only be geo-distributed with High Availability mode in
|
||||||
our Enterprise and Premium Editions.
|
our Enterprise Edition. [Reach out to Sales](https://coder.com/contact) to learn
|
||||||
[Reach out to Sales](https://coder.com/contact) to learn more.
|
more.
|
||||||
|
|
||||||
## Browser-only connections (enterprise) (premium)
|
## Browser-only connections (enterprise) (premium)
|
||||||
|
|
||||||
@ -175,7 +183,15 @@ with security policies. In these cases, pass the `--browser-only` flag to
|
|||||||
`coder server` or set `CODER_BROWSER_ONLY=true`.
|
`coder server` or set `CODER_BROWSER_ONLY=true`.
|
||||||
|
|
||||||
With browser-only connections, developers can only connect to their workspaces
|
With browser-only connections, developers can only connect to their workspaces
|
||||||
via the web terminal and [web IDEs](../ides/web-ides.md).
|
via the web terminal and
|
||||||
|
[web IDEs](../../user-guides/workspace-access/web-ides.md).
|
||||||
|
|
||||||
|
### Workspace Proxies (enterprise) (premium)
|
||||||
|
|
||||||
|
Workspace proxies are a Coder Enterprise feature that allows you to provide
|
||||||
|
low-latency browser experiences for geo-distributed teams.
|
||||||
|
|
||||||
|
To learn more, see [Workspace Proxies](./workspace-proxies.md).
|
||||||
|
|
||||||
## Up next
|
## Up next
|
||||||
|
|
@ -49,10 +49,10 @@ For more examples, see `coder port-forward --help`.
|
|||||||
## Dashboard
|
## Dashboard
|
||||||
|
|
||||||
> To enable port forwarding via the dashboard, Coder must be configured with a
|
> To enable port forwarding via the dashboard, Coder must be configured with a
|
||||||
> [wildcard access URL](../admin/configure.md#wildcard-access-url). If an access
|
> [wildcard access URL](../../admin/setup/index.md#wildcard-access-url). If an
|
||||||
> URL is not specified, Coder will create
|
> access URL is not specified, Coder will create
|
||||||
> [a publicly accessible URL](../admin/configure.md#tunnel) to reverse proxy the
|
> [a publicly accessible URL](../../admin/setup/index.md#tunnel) to reverse
|
||||||
> deployment, and port forwarding will work.
|
> proxy the deployment, and port forwarding will work.
|
||||||
>
|
>
|
||||||
> There is a
|
> There is a
|
||||||
> [DNS limitation](https://datatracker.ietf.org/doc/html/rfc1035#section-2.3.1)
|
> [DNS limitation](https://datatracker.ietf.org/doc/html/rfc1035#section-2.3.1)
|
||||||
@ -67,7 +67,7 @@ workspace's template. This approach shows a visual application icon in the
|
|||||||
dashboard. See the following `coder_app` example for a Node React app and note
|
dashboard. See the following `coder_app` example for a Node React app and note
|
||||||
the `subdomain` and `share` settings:
|
the `subdomain` and `share` settings:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
# node app
|
# node app
|
||||||
resource "coder_app" "node-react-app" {
|
resource "coder_app" "node-react-app" {
|
||||||
agent_id = coder_agent.dev.id
|
agent_id = coder_agent.dev.id
|
||||||
@ -90,7 +90,7 @@ Valid `share` values include `owner` - private to the user, `authenticated` -
|
|||||||
accessible by any user authenticated to the Coder deployment, and `public` -
|
accessible by any user authenticated to the Coder deployment, and `public` -
|
||||||
accessible by users outside of the Coder deployment.
|
accessible by users outside of the Coder deployment.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
## Accessing workspace ports
|
## Accessing workspace ports
|
||||||
|
|
||||||
@ -99,7 +99,7 @@ to specify an arbitrary port. Coder will also detect if apps inside the
|
|||||||
workspace are listening on ports, and list them below the port input (this is
|
workspace are listening on ports, and list them below the port input (this is
|
||||||
only supported on Windows and Linux workspace agents).
|
only supported on Windows and Linux workspace agents).
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
### Sharing ports
|
### Sharing ports
|
||||||
|
|
||||||
@ -118,7 +118,7 @@ Once a port is shared at either `authenticated` or `public` levels, it will stay
|
|||||||
pinned in the open ports UI for better accessibility regardless of whether or
|
pinned in the open ports UI for better accessibility regardless of whether or
|
||||||
not it is still accessible.
|
not it is still accessible.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
The sharing level is limited by the maximum level enforced in the template
|
The sharing level is limited by the maximum level enforced in the template
|
||||||
settings in enterprise deployments, and not restricted in OSS deployments.
|
settings in enterprise deployments, and not restricted in OSS deployments.
|
||||||
@ -137,7 +137,7 @@ maximum sharing level is set to `Owner`, meaning port sharing is disabled for
|
|||||||
end-users. OSS deployments allow all workspaces to share ports at both the
|
end-users. OSS deployments allow all workspaces to share ports at both the
|
||||||
`authenticated` and `public` levels.
|
`authenticated` and `public` levels.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
### Configuring port protocol
|
### Configuring port protocol
|
||||||
|
|
||||||
@ -274,8 +274,9 @@ configurable by either admins or users.
|
|||||||
|
|
||||||
## SSH
|
## SSH
|
||||||
|
|
||||||
First, [configure SSH](../ides.md#ssh-configuration) on your local machine.
|
First,
|
||||||
Then, use `ssh` to forward like so:
|
[configure SSH](../../user-guides/workspace-access/index.md#configure-ssh) on
|
||||||
|
your local machine. Then, use `ssh` to forward like so:
|
||||||
|
|
||||||
```console
|
```console
|
||||||
ssh -L 8080:localhost:8000 coder.myworkspace
|
ssh -L 8080:localhost:8000 coder.myworkspace
|
@ -66,7 +66,7 @@ In this example, both the client and agent are located on the network
|
|||||||
direction, both client and agent are able to communicate directly with each
|
direction, both client and agent are able to communicate directly with each
|
||||||
other's locally assigned IP address.
|
other's locally assigned IP address.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
### 2. Direct connections with one layer of NAT
|
### 2. Direct connections with one layer of NAT
|
||||||
|
|
||||||
@ -75,12 +75,12 @@ to each other over the public Internet. Both client and agent connect to a
|
|||||||
configured STUN server located on the public Internet to determine the public IP
|
configured STUN server located on the public Internet to determine the public IP
|
||||||
address and port on which they can be reached.
|
address and port on which they can be reached.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
They then exchange this information through Coder server, and can then
|
They then exchange this information through Coder server, and can then
|
||||||
communicate directly with each other through their respective NATs.
|
communicate directly with each other through their respective NATs.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
### 3. Direct connections with VPN and NAT hairpinning
|
### 3. Direct connections with VPN and NAT hairpinning
|
||||||
|
|
||||||
@ -121,7 +121,7 @@ addresses on the corporate network from which their traffic appears to
|
|||||||
originate. Using these internal addresses is much more likely to result in a
|
originate. Using these internal addresses is much more likely to result in a
|
||||||
successful direct connection.
|
successful direct connection.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
## Hard NAT
|
## Hard NAT
|
||||||
|
|
@ -4,15 +4,16 @@ Workspace proxies provide low-latency experiences for geo-distributed teams.
|
|||||||
|
|
||||||
Coder's networking does a best effort to make direct connections to a workspace.
|
Coder's networking does a best effort to make direct connections to a workspace.
|
||||||
In situations where this is not possible, such as connections via the web
|
In situations where this is not possible, such as connections via the web
|
||||||
terminal and [web IDEs](../ides/web-ides.md), workspace proxies are able to
|
terminal and [web IDEs](../../user-guides/workspace-access/index.md#web-ides),
|
||||||
reduce the amount of distance the network traffic needs to travel.
|
workspace proxies are able to reduce the amount of distance the network traffic
|
||||||
|
needs to travel.
|
||||||
|
|
||||||
A workspace proxy is a relay connection a developer can choose to use when
|
A workspace proxy is a relay connection a developer can choose to use when
|
||||||
connecting with their workspace over SSH, a workspace app, port forwarding, etc.
|
connecting with their workspace over SSH, a workspace app, port forwarding, etc.
|
||||||
Dashboard connections and API calls (e.g. the workspaces list) are not served
|
Dashboard connections and API calls (e.g. the workspaces list) are not served
|
||||||
over workspace proxies.
|
over workspace proxies.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
# Deploy a workspace proxy
|
# Deploy a workspace proxy
|
||||||
|
|
||||||
@ -26,12 +27,8 @@ Workspace proxies can be used in the browser by navigating to the user
|
|||||||
|
|
||||||
## Requirements
|
## Requirements
|
||||||
|
|
||||||
- The [Coder CLI](../reference/cli) must be installed and authenticated as a
|
- The [Coder CLI](../../reference/cli/index.md) must be installed and
|
||||||
user with the Owner role.
|
authenticated as a user with the Owner role.
|
||||||
- Alternatively, the
|
|
||||||
[coderd Terraform Provider](https://registry.terraform.io/providers/coder/coderd/latest)
|
|
||||||
can be used to create and manage workspace proxies, if authenticated as a user
|
|
||||||
with the Owner role.
|
|
||||||
|
|
||||||
## Step 1: Create the proxy
|
## Step 1: Create the proxy
|
||||||
|
|
||||||
@ -61,7 +58,7 @@ the workspace proxy usable. If the proxy deployment is successful,
|
|||||||
|
|
||||||
```
|
```
|
||||||
$ coder wsproxy ls
|
$ coder wsproxy ls
|
||||||
NAME URL STATUS STATUS
|
NAME URL STATUS STATUS
|
||||||
brazil-saopaulo https://brazil.example.com ok
|
brazil-saopaulo https://brazil.example.com ok
|
||||||
europe-frankfurt https://europe.example.com ok
|
europe-frankfurt https://europe.example.com ok
|
||||||
sydney https://sydney.example.com ok
|
sydney https://sydney.example.com ok
|
||||||
@ -153,8 +150,8 @@ coder wsproxy server
|
|||||||
|
|
||||||
### Running as a system service
|
### Running as a system service
|
||||||
|
|
||||||
If you've installed Coder via a [system package](../install/index.md), you can
|
If you've installed Coder via a [system package](../../install/index.md), you
|
||||||
configure the workspace proxy by settings in
|
can configure the workspace proxy by settings in
|
||||||
`/etc/coder.d/coder-workspace-proxy.env`
|
`/etc/coder.d/coder-workspace-proxy.env`
|
||||||
|
|
||||||
To run workspace proxy as a system service on the host:
|
To run workspace proxy as a system service on the host:
|
||||||
@ -202,49 +199,6 @@ FROM ghcr.io/coder/coder:latest
|
|||||||
ENTRYPOINT ["/opt/coder", "wsproxy", "server"]
|
ENTRYPOINT ["/opt/coder", "wsproxy", "server"]
|
||||||
```
|
```
|
||||||
|
|
||||||
### Managing via Terraform
|
|
||||||
|
|
||||||
The
|
|
||||||
[coderd Terraform Provider](https://registry.terraform.io/providers/coder/coderd/latest)
|
|
||||||
can also be used to create and manage workspace proxies in the same Terraform
|
|
||||||
configuration as your deployment.
|
|
||||||
|
|
||||||
```hcl
|
|
||||||
|
|
||||||
provider "coderd" {
|
|
||||||
url = "https://coder.example.com"
|
|
||||||
token = "****"
|
|
||||||
}
|
|
||||||
|
|
||||||
resource "coderd_workspace_proxy" "sydney-wsp" {
|
|
||||||
name = "sydney-wsp"
|
|
||||||
display_name = "Australia (Sydney)"
|
|
||||||
icon = "/emojis/1f1e6-1f1fa.png"
|
|
||||||
}
|
|
||||||
resource "kubernetes_deployment" "syd_wsproxy" {
|
|
||||||
metadata { /* ... */ }
|
|
||||||
spec {
|
|
||||||
template {
|
|
||||||
metadata { /* ... */ }
|
|
||||||
spec {
|
|
||||||
container {
|
|
||||||
name = "syd-wsp"
|
|
||||||
image = "ghcr.io/coder/coder:latest"
|
|
||||||
args = ["wsproxy", "server"]
|
|
||||||
env {
|
|
||||||
name = "CODER_PROXY_SESSION_TOKEN"
|
|
||||||
value = coderd_workspace_proxy.sydney-wsp.session_token
|
|
||||||
}
|
|
||||||
/* ... */
|
|
||||||
}
|
|
||||||
/* ... */
|
|
||||||
}
|
|
||||||
}
|
|
||||||
/* ... */
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Selecting a proxy
|
### Selecting a proxy
|
||||||
|
|
||||||
Users can select a workspace proxy at the top-right of the browser-based Coder
|
Users can select a workspace proxy at the top-right of the browser-based Coder
|
||||||
@ -252,9 +206,9 @@ dashboard. Workspace proxy preferences are cached by the web browser. If a proxy
|
|||||||
goes offline, the session will fall back to the primary proxy. This could take
|
goes offline, the session will fall back to the primary proxy. This could take
|
||||||
up to 60 seconds.
|
up to 60 seconds.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
## Step 3: Observability
|
## Observability
|
||||||
|
|
||||||
Coder workspace proxy exports metrics via the HTTP endpoint, which can be
|
Coder workspace proxy exports metrics via the HTTP endpoint, which can be
|
||||||
enabled using either the environment variable `CODER_PROMETHEUS_ENABLE` or the
|
enabled using either the environment variable `CODER_PROMETHEUS_ENABLE` or the
|
@ -10,18 +10,20 @@ are often benefits to running external provisioner daemons:
|
|||||||
|
|
||||||
- **Isolate APIs:** Deploy provisioners in isolated environments (on-prem, AWS,
|
- **Isolate APIs:** Deploy provisioners in isolated environments (on-prem, AWS,
|
||||||
Azure) instead of exposing APIs (Docker, Kubernetes, VMware) to the Coder
|
Azure) instead of exposing APIs (Docker, Kubernetes, VMware) to the Coder
|
||||||
server. See [Provider Authentication](../templates/authentication.md) for more
|
server. See
|
||||||
details.
|
[Provider Authentication](../admin/templates/extending-templates/provider-authentication.md)
|
||||||
|
for more details.
|
||||||
|
|
||||||
- **Isolate secrets**: Keep Coder unaware of cloud secrets, manage/rotate
|
- **Isolate secrets**: Keep Coder unaware of cloud secrets, manage/rotate
|
||||||
secrets on provisioner servers.
|
secrets on provisioner servers.
|
||||||
|
|
||||||
- **Reduce server load**: External provisioners reduce load and build queue
|
- **Reduce server load**: External provisioners reduce load and build queue
|
||||||
times from the Coder server. See
|
times from the Coder server. See
|
||||||
[Scaling Coder](scaling/scale-utility.md#recent-scale-tests) for more details.
|
[Scaling Coder](../admin/infrastructure/index.md#scale-tests) for more
|
||||||
|
details.
|
||||||
|
|
||||||
Each provisioner runs a single
|
Each provisioner runs a single
|
||||||
[concurrent workspace build](scaling/scale-testing.md#control-plane-provisioner).
|
[concurrent workspace build](../admin/infrastructure/scale-testing.md#control-plane-provisionerd).
|
||||||
For example, running 30 provisioner containers will allow 30 users to start
|
For example, running 30 provisioner containers will allow 30 users to start
|
||||||
workspaces at the same time.
|
workspaces at the same time.
|
||||||
|
|
||||||
@ -32,9 +34,7 @@ to learn how to start provisioners via Docker, Kubernetes, Systemd, etc.
|
|||||||
|
|
||||||
## Authentication
|
## Authentication
|
||||||
|
|
||||||
The provisioner daemon must authenticate with your Coder deployment. If you have
|
The provisioner daemon must authenticate with your Coder deployment.
|
||||||
multiple [organizations](./organizations.md), you'll need at least 1 provisioner
|
|
||||||
running for each organization.
|
|
||||||
|
|
||||||
<div class="tabs">
|
<div class="tabs">
|
||||||
|
|
||||||
@ -79,7 +79,7 @@ Kubernetes/Docker/etc.
|
|||||||
|
|
||||||
A user account with the role `Template Admin` or `Owner` can start provisioners
|
A user account with the role `Template Admin` or `Owner` can start provisioners
|
||||||
using their user account. This may be beneficial if you are running provisioners
|
using their user account. This may be beneficial if you are running provisioners
|
||||||
via [automation](./automation.md).
|
via [automation](../reference/index.md).
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
coder login https://<your-coder-url>
|
coder login https://<your-coder-url>
|
||||||
@ -208,7 +208,7 @@ Provisioners can broadly be categorized by scope: `organization` or `user`. The
|
|||||||
scope of a provisioner can be specified with
|
scope of a provisioner can be specified with
|
||||||
[`-tag=scope=<scope>`](../reference/cli/provisioner_start.md#t---tag) when
|
[`-tag=scope=<scope>`](../reference/cli/provisioner_start.md#t---tag) when
|
||||||
starting the provisioner daemon. Only users with at least the
|
starting the provisioner daemon. Only users with at least the
|
||||||
[Template Admin](../admin/users.md#roles) role or higher may create
|
[Template Admin](./users/index.md#roles) role or higher may create
|
||||||
organization-scoped provisioner daemons.
|
organization-scoped provisioner daemons.
|
||||||
|
|
||||||
There are two exceptions:
|
There are two exceptions:
|
||||||
|
@ -1,23 +0,0 @@
|
|||||||
# Role Based Access Control (RBAC)
|
|
||||||
|
|
||||||
Use RBAC to define which users and [groups](./groups.md) can use specific
|
|
||||||
templates in Coder. These can be defined via the Coder web UI,
|
|
||||||
[synced from your identity provider](./auth.md) or
|
|
||||||
[managed via Terraform](https://registry.terraform.io/providers/coder/coderd/latest/docs/resources/template).
|
|
||||||
|
|
||||||

|
|
||||||
|
|
||||||
The "Everyone" group makes a template accessible to all users. This can be
|
|
||||||
removed to make a template private.
|
|
||||||
|
|
||||||
## Permissions
|
|
||||||
|
|
||||||
You can set the following permissions:
|
|
||||||
|
|
||||||
- **Admin**: Read, use, edit, push, and delete
|
|
||||||
- **View**: Read, use
|
|
||||||
|
|
||||||
## Enabling this feature
|
|
||||||
|
|
||||||
This feature is only available with an
|
|
||||||
[Enterprise or Premium license](https://coder.com/pricing).
|
|
@ -6,7 +6,7 @@ Audit Logs allows **Auditors** to monitor user operations in their deployment.
|
|||||||
|
|
||||||
We track the following resources:
|
We track the following resources:
|
||||||
|
|
||||||
<!-- Code generated by 'make docs/admin/audit-logs.md'. DO NOT EDIT -->
|
<!-- Code generated by 'make docs/admin/security/audit-logs.md'. DO NOT EDIT -->
|
||||||
|
|
||||||
| <b>Resource<b> | |
|
| <b>Resource<b> | |
|
||||||
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
@ -30,7 +30,7 @@ We track the following resources:
|
|||||||
| WorkspaceBuild<br><i>start, stop</i> | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>build_number</td><td>false</td></tr><tr><td>created_at</td><td>false</td></tr><tr><td>daily_cost</td><td>false</td></tr><tr><td>deadline</td><td>false</td></tr><tr><td>id</td><td>false</td></tr><tr><td>initiator_by_avatar_url</td><td>false</td></tr><tr><td>initiator_by_username</td><td>false</td></tr><tr><td>initiator_id</td><td>false</td></tr><tr><td>job_id</td><td>false</td></tr><tr><td>max_deadline</td><td>false</td></tr><tr><td>provisioner_state</td><td>false</td></tr><tr><td>reason</td><td>false</td></tr><tr><td>template_version_id</td><td>true</td></tr><tr><td>transition</td><td>false</td></tr><tr><td>updated_at</td><td>false</td></tr><tr><td>workspace_id</td><td>false</td></tr></tbody></table> |
|
| WorkspaceBuild<br><i>start, stop</i> | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>build_number</td><td>false</td></tr><tr><td>created_at</td><td>false</td></tr><tr><td>daily_cost</td><td>false</td></tr><tr><td>deadline</td><td>false</td></tr><tr><td>id</td><td>false</td></tr><tr><td>initiator_by_avatar_url</td><td>false</td></tr><tr><td>initiator_by_username</td><td>false</td></tr><tr><td>initiator_id</td><td>false</td></tr><tr><td>job_id</td><td>false</td></tr><tr><td>max_deadline</td><td>false</td></tr><tr><td>provisioner_state</td><td>false</td></tr><tr><td>reason</td><td>false</td></tr><tr><td>template_version_id</td><td>true</td></tr><tr><td>transition</td><td>false</td></tr><tr><td>updated_at</td><td>false</td></tr><tr><td>workspace_id</td><td>false</td></tr></tbody></table> |
|
||||||
| WorkspaceProxy<br><i></i> | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>created_at</td><td>true</td></tr><tr><td>deleted</td><td>false</td></tr><tr><td>derp_enabled</td><td>true</td></tr><tr><td>derp_only</td><td>true</td></tr><tr><td>display_name</td><td>true</td></tr><tr><td>icon</td><td>true</td></tr><tr><td>id</td><td>true</td></tr><tr><td>name</td><td>true</td></tr><tr><td>region_id</td><td>true</td></tr><tr><td>token_hashed_secret</td><td>true</td></tr><tr><td>updated_at</td><td>false</td></tr><tr><td>url</td><td>true</td></tr><tr><td>version</td><td>true</td></tr><tr><td>wildcard_hostname</td><td>true</td></tr></tbody></table> |
|
| WorkspaceProxy<br><i></i> | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>created_at</td><td>true</td></tr><tr><td>deleted</td><td>false</td></tr><tr><td>derp_enabled</td><td>true</td></tr><tr><td>derp_only</td><td>true</td></tr><tr><td>display_name</td><td>true</td></tr><tr><td>icon</td><td>true</td></tr><tr><td>id</td><td>true</td></tr><tr><td>name</td><td>true</td></tr><tr><td>region_id</td><td>true</td></tr><tr><td>token_hashed_secret</td><td>true</td></tr><tr><td>updated_at</td><td>false</td></tr><tr><td>url</td><td>true</td></tr><tr><td>version</td><td>true</td></tr><tr><td>wildcard_hostname</td><td>true</td></tr></tbody></table> |
|
||||||
|
|
||||||
<!-- End generated by 'make docs/admin/audit-logs.md'. -->
|
<!-- End generated by 'make docs/admin/security/audit-logs.md'. -->
|
||||||
|
|
||||||
## Filtering logs
|
## Filtering logs
|
||||||
|
|
||||||
@ -70,15 +70,15 @@ audit trails.
|
|||||||
|
|
||||||
Audit logs can be accessed through our REST API. You can find detailed
|
Audit logs can be accessed through our REST API. You can find detailed
|
||||||
information about this in our
|
information about this in our
|
||||||
[endpoint documentation](../reference/api/audit.md#get-audit-logs).
|
[endpoint documentation](../../reference/api/audit.md#get-audit-logs).
|
||||||
|
|
||||||
## Service Logs
|
## Service Logs
|
||||||
|
|
||||||
Audit trails are also dispatched as service logs and can be captured and
|
Audit trails are also dispatched as service logs and can be captured and
|
||||||
categorized using any log management tool such as [Splunk](https://splunk.com).
|
categorized using any log management tool such as [Splunk](https://splunk.com).
|
||||||
|
|
||||||
Example of a [JSON formatted](../reference/cli/server.md#--log-json) audit log
|
Example of a [JSON formatted](../../reference/cli/server.md#--log-json) audit
|
||||||
entry:
|
log entry:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
@ -113,8 +113,8 @@ entry:
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
Example of a [human readable](../reference/cli/server.md#--log-human) audit log
|
Example of a [human readable](../../reference/cli/server.md#--log-human) audit
|
||||||
entry:
|
log entry:
|
||||||
|
|
||||||
```console
|
```console
|
||||||
2023-06-13 03:43:29.233 [info] coderd: audit_log ID=95f7c392-da3e-480c-a579-8909f145fbe2 Time="2023-06-13T03:43:29.230422Z" UserID=6c405053-27e3-484a-9ad7-bcb64e7bfde6 OrganizationID=00000000-0000-0000-0000-000000000000 Ip=<nil> UserAgent=<nil> ResourceType=workspace_build ResourceID=988ae133-5b73-41e3-a55e-e1e9d3ef0b66 ResourceTarget="" Action=start Diff="{}" StatusCode=200 AdditionalFields="{\"workspace_name\":\"linux-container\",\"build_number\":\"7\",\"build_reason\":\"initiator\",\"workspace_owner\":\"\"}" RequestID=9682b1b5-7b9f-4bf2-9a39-9463f8e41cd6 ResourceIcon=""
|
2023-06-13 03:43:29.233 [info] coderd: audit_log ID=95f7c392-da3e-480c-a579-8909f145fbe2 Time="2023-06-13T03:43:29.230422Z" UserID=6c405053-27e3-484a-9ad7-bcb64e7bfde6 OrganizationID=00000000-0000-0000-0000-000000000000 Ip=<nil> UserAgent=<nil> ResourceType=workspace_build ResourceID=988ae133-5b73-41e3-a55e-e1e9d3ef0b66 ResourceTarget="" Action=start Diff="{}" StatusCode=200 AdditionalFields="{\"workspace_name\":\"linux-container\",\"build_number\":\"7\",\"build_reason\":\"initiator\",\"workspace_owner\":\"\"}" RequestID=9682b1b5-7b9f-4bf2-9a39-9463f8e41cd6 ResourceIcon=""
|
||||||
@ -122,5 +122,5 @@ entry:
|
|||||||
|
|
||||||
## Enabling this feature
|
## Enabling this feature
|
||||||
|
|
||||||
This feature is only available with a
|
This feature is only available with an enterprise license.
|
||||||
[Premium or Enterprise license](https://coder.com/pricing).
|
[Learn more](../licensing/index.md)
|
@ -7,7 +7,7 @@ preventing attackers with database access from using them to impersonate users.
|
|||||||
## How it works
|
## How it works
|
||||||
|
|
||||||
Coder allows administrators to specify
|
Coder allows administrators to specify
|
||||||
[external token encryption keys](../reference/cli/server.md#external-token-encryption-keys).
|
[external token encryption keys](../../reference/cli/server.md#external-token-encryption-keys).
|
||||||
If configured, Coder will use these keys to encrypt external user tokens before
|
If configured, Coder will use these keys to encrypt external user tokens before
|
||||||
storing them in the database. The encryption algorithm used is AES-256-GCM with
|
storing them in the database. The encryption algorithm used is AES-256-GCM with
|
||||||
a 32-byte key length.
|
a 32-byte key length.
|
||||||
@ -47,7 +47,7 @@ Additional database fields may be encrypted in the future.
|
|||||||
|
|
||||||
- Ensure you have a valid backup of your database. **Do not skip this step.** If
|
- Ensure you have a valid backup of your database. **Do not skip this step.** If
|
||||||
you are using the built-in PostgreSQL database, you can run
|
you are using the built-in PostgreSQL database, you can run
|
||||||
[`coder server postgres-builtin-url`](../reference/cli/server_postgres-builtin-url.md)
|
[`coder server postgres-builtin-url`](../../reference/cli/server_postgres-builtin-url.md)
|
||||||
to get the connection URL.
|
to get the connection URL.
|
||||||
|
|
||||||
- Generate a 32-byte random key and base64-encode it. For example:
|
- Generate a 32-byte random key and base64-encode it. For example:
|
||||||
@ -90,7 +90,7 @@ if you need to rotate keys, you can perform the following procedure:
|
|||||||
- Generate a new encryption key following the same procedure as above.
|
- Generate a new encryption key following the same procedure as above.
|
||||||
|
|
||||||
- Add the above key to the list of
|
- Add the above key to the list of
|
||||||
[external token encryption keys](../reference/cli/server.md#--external-token-encryption-keys).
|
[external token encryption keys](../../reference/cli/server.md#--external-token-encryption-keys).
|
||||||
**The new key must appear first in the list**. For example, in the Kubernetes
|
**The new key must appear first in the list**. For example, in the Kubernetes
|
||||||
secret created above:
|
secret created above:
|
||||||
|
|
||||||
@ -110,13 +110,13 @@ data:
|
|||||||
encrypted with the old key(s).
|
encrypted with the old key(s).
|
||||||
|
|
||||||
- To re-encrypt all encrypted database fields with the new key, run
|
- To re-encrypt all encrypted database fields with the new key, run
|
||||||
[`coder server dbcrypt rotate`](../reference/cli/server_dbcrypt_rotate.md).
|
[`coder server dbcrypt rotate`](../../reference/cli/server_dbcrypt_rotate.md).
|
||||||
This command will re-encrypt all tokens with the specified new encryption key.
|
This command will re-encrypt all tokens with the specified new encryption key.
|
||||||
We recommend performing this action during a maintenance window.
|
We recommend performing this action during a maintenance window.
|
||||||
|
|
||||||
> Note: this command requires direct access to the database. If you are using
|
> Note: this command requires direct access to the database. If you are using
|
||||||
> the built-in PostgreSQL database, you can run
|
> the built-in PostgreSQL database, you can run
|
||||||
> [`coder server postgres-builtin-url`](../reference/cli/server_postgres-builtin-url.md)
|
> [`coder server postgres-builtin-url`](../../reference/cli/server_postgres-builtin-url.md)
|
||||||
> to get the connection URL.
|
> to get the connection URL.
|
||||||
|
|
||||||
- Once the above command completes successfully, remove the old encryption key
|
- Once the above command completes successfully, remove the old encryption key
|
||||||
@ -133,7 +133,7 @@ To disable encryption, perform the following actions:
|
|||||||
being written, which may cause the next step to fail.
|
being written, which may cause the next step to fail.
|
||||||
|
|
||||||
- Run
|
- Run
|
||||||
[`coder server dbcrypt decrypt`](../reference/cli/server_dbcrypt_decrypt.md).
|
[`coder server dbcrypt decrypt`](../../reference/cli/server_dbcrypt_decrypt.md).
|
||||||
This command will decrypt all encrypted user tokens and revoke all active
|
This command will decrypt all encrypted user tokens and revoke all active
|
||||||
encryption keys.
|
encryption keys.
|
||||||
|
|
||||||
@ -143,7 +143,7 @@ To disable encryption, perform the following actions:
|
|||||||
> to help prevent accidentally decrypting data.
|
> to help prevent accidentally decrypting data.
|
||||||
|
|
||||||
- Remove all
|
- Remove all
|
||||||
[external token encryption keys](../reference/cli/server.md#--external-token-encryption-keys)
|
[external token encryption keys](../../reference/cli/server.md#--external-token-encryption-keys)
|
||||||
from Coder's configuration.
|
from Coder's configuration.
|
||||||
|
|
||||||
- Start coderd. You can now safely delete the encryption keys from your secret
|
- Start coderd. You can now safely delete the encryption keys from your secret
|
||||||
@ -161,12 +161,12 @@ To delete all encrypted data from your database, perform the following actions:
|
|||||||
being written.
|
being written.
|
||||||
|
|
||||||
- Run
|
- Run
|
||||||
[`coder server dbcrypt delete`](../reference/cli/server_dbcrypt_delete.md).
|
[`coder server dbcrypt delete`](../../reference/cli/server_dbcrypt_delete.md).
|
||||||
This command will delete all encrypted user tokens and revoke all active
|
This command will delete all encrypted user tokens and revoke all active
|
||||||
encryption keys.
|
encryption keys.
|
||||||
|
|
||||||
- Remove all
|
- Remove all
|
||||||
[external token encryption keys](../reference/cli/server.md#--external-token-encryption-keys)
|
[external token encryption keys](../../reference/cli/server.md#--external-token-encryption-keys)
|
||||||
from Coder's configuration.
|
from Coder's configuration.
|
||||||
|
|
||||||
- Start coderd. You can now safely delete the encryption keys from your secret
|
- Start coderd. You can now safely delete the encryption keys from your secret
|
||||||
@ -175,11 +175,11 @@ To delete all encrypted data from your database, perform the following actions:
|
|||||||
## Troubleshooting
|
## Troubleshooting
|
||||||
|
|
||||||
- If Coder detects that the data stored in the database was not encrypted with
|
- If Coder detects that the data stored in the database was not encrypted with
|
||||||
any known keys, it will refuse to start. If you are seeing this behaviour,
|
any known keys, it will refuse to start. If you are seeing this behavior,
|
||||||
ensure that the encryption keys provided are correct.
|
ensure that the encryption keys provided are correct.
|
||||||
- If Coder detects that the data stored in the database was encrypted with a key
|
- If Coder detects that the data stored in the database was encrypted with a key
|
||||||
that is no longer active, it will refuse to start. If you are seeing this
|
that is no longer active, it will refuse to start. If you are seeing this
|
||||||
behaviour, ensure that the encryption keys provided are correct and that you
|
behavior, ensure that the encryption keys provided are correct and that you
|
||||||
have not revoked any keys that are still in use.
|
have not revoked any keys that are still in use.
|
||||||
- Decryption may fail if newly encrypted data is written while decryption is in
|
- Decryption may fail if newly encrypted data is written while decryption is in
|
||||||
progress. If this happens, ensure that all active coder instances are stopped,
|
progress. If this happens, ensure that all active coder instances are stopped,
|
@ -15,6 +15,6 @@ vulnerability.
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
| Description | Severity | Fix | Vulnerable Versions |
|
| Description | Severity | Fix | Vulnerable Versions |
|
||||||
| ---------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------- | ------------------- |
|
| --------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------- | ------------------- |
|
||||||
| [API tokens of deleted users not invalidated](./0001_user_apikeys_invalidation.md) | HIGH | [v0.23.0](https://github.com/coder/coder/releases/tag/v0.23.0) | v0.8.25 - v0.22.2 |
|
| [API tokens of deleted users not invalidated](https://github.com/coder/coder/blob/main/docs/security/0001_user_apikeys_invalidation.md) | HIGH | [v0.23.0](https://github.com/coder/coder/releases/tag/v0.23.0) | v0.8.25 - v0.22.2 |
|
@ -19,9 +19,10 @@ Often, this workflow is simply:
|
|||||||
1. Your users write them to a persistent file after they've built their
|
1. Your users write them to a persistent file after they've built their
|
||||||
workspace
|
workspace
|
||||||
|
|
||||||
[Template parameters](./templates/parameters.md) are a dangerous way to accept
|
[Template parameters](../templates/extending-templates/parameters.md) are a
|
||||||
secrets. We show parameters in cleartext around the product. Assume anyone with
|
dangerous way to accept secrets. We show parameters in cleartext around the
|
||||||
view access to a workspace can also see its parameters.
|
product. Assume anyone with view access to a workspace can also see its
|
||||||
|
parameters.
|
||||||
|
|
||||||
## SSH Keys
|
## SSH Keys
|
||||||
|
|
||||||
@ -32,7 +33,7 @@ environment variable.
|
|||||||
|
|
||||||
Users can view their public key in their account settings:
|
Users can view their public key in their account settings:
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
> Note: SSH keys are never stored in Coder workspaces, and are fetched only when
|
> Note: SSH keys are never stored in Coder workspaces, and are fetched only when
|
||||||
> SSH is invoked. The keys are held in-memory and never written to disk.
|
> SSH is invoked. The keys are held in-memory and never written to disk.
|
||||||
@ -49,7 +50,7 @@ which excludes obscure API providers.
|
|||||||
|
|
||||||
Dynamic secrets can be implemented in your template code like so:
|
Dynamic secrets can be implemented in your template code like so:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "twilio_iam_api_key" "api_key" {
|
resource "twilio_iam_api_key" "api_key" {
|
||||||
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
|
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
|
||||||
friendly_name = "Test API Key"
|
friendly_name = "Test API Key"
|
||||||
@ -76,11 +77,11 @@ While you can inject secrets into the workspace via environment variables, you
|
|||||||
can also show them in the Workspace UI with
|
can also show them in the Workspace UI with
|
||||||
[`coder_metadata`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/metadata).
|
[`coder_metadata`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/metadata).
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
Can be produced with
|
Can be produced with
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "twilio_iam_api_key" "api_key" {
|
resource "twilio_iam_api_key" "api_key" {
|
||||||
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
|
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
|
||||||
friendly_name = "Test API Key"
|
friendly_name = "Test API Key"
|
||||||
@ -90,9 +91,23 @@ resource "twilio_iam_api_key" "api_key" {
|
|||||||
resource "coder_metadata" "twilio_key" {
|
resource "coder_metadata" "twilio_key" {
|
||||||
resource_id = twilio_iam_api_key.api_key.id
|
resource_id = twilio_iam_api_key.api_key.id
|
||||||
item {
|
item {
|
||||||
key = "secret"
|
key = "Username"
|
||||||
value = twilio_iam_api_key.api_key.secret
|
value = "Administrator"
|
||||||
|
}
|
||||||
|
item {
|
||||||
|
key = "Password"
|
||||||
|
value = twilio_iam_api_key.api_key.secret
|
||||||
sensitive = true
|
sensitive = true
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Secrets Management
|
||||||
|
|
||||||
|
For more advanced secrets management, you can use a secrets management tool to
|
||||||
|
store and retrieve secrets in your workspace. For example, you can use
|
||||||
|
[HashiCorp Vault](https://www.vaultproject.io/) to inject secrets into your
|
||||||
|
workspace.
|
||||||
|
|
||||||
|
Refer to our [HashiCorp Vault Integration](../integrations/vault.md) guide for
|
||||||
|
more information on how to integrate HashiCorp Vault with Coder.
|
@ -6,7 +6,7 @@ requirements.
|
|||||||
You can access the Appearance settings by navigating to
|
You can access the Appearance settings by navigating to
|
||||||
`Deployment > Appearance`.
|
`Deployment > Appearance`.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
## Application Name
|
## Application Name
|
||||||
|
|
||||||
@ -20,7 +20,7 @@ page and in the top left corner of the dashboard. The default is the Coder logo.
|
|||||||
|
|
||||||
## Announcement Banners
|
## Announcement Banners
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
Announcement Banners let admins post important messages to all site users. Only
|
Announcement Banners let admins post important messages to all site users. Only
|
||||||
Site Owners may set the announcement banners.
|
Site Owners may set the announcement banners.
|
||||||
@ -28,17 +28,17 @@ Site Owners may set the announcement banners.
|
|||||||
Example: Use multiple announcement banners for concurrent deployment-wide
|
Example: Use multiple announcement banners for concurrent deployment-wide
|
||||||
updates, such as maintenance or new feature rollout.
|
updates, such as maintenance or new feature rollout.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
Example: Adhere to government network classification requirements and notify
|
Example: Adhere to government network classification requirements and notify
|
||||||
users of which network their Coder deployment is on.
|
users of which network their Coder deployment is on.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
## OIDC Login Button Customization
|
## OIDC Login Button Customization
|
||||||
|
|
||||||
[Use environment variables to customize](./auth.md#oidc-login-customization) the
|
[Use environment variables to customize](../users/oidc-auth.md#oidc-login-customization)
|
||||||
text and icon on the OIDC button on the Sign In page.
|
the text and icon on the OIDC button on the Sign In page.
|
||||||
|
|
||||||
## Support Links
|
## Support Links
|
||||||
|
|
||||||
@ -47,13 +47,13 @@ referring to internal company resources. The menu section replaces the original
|
|||||||
menu positions: documentation, report a bug to GitHub, or join the Discord
|
menu positions: documentation, report a bug to GitHub, or join the Discord
|
||||||
server.
|
server.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
### Icons
|
### Icons
|
||||||
|
|
||||||
The link icons are optional, and can be set to any url or
|
The link icons are optional, and can be set to any url or
|
||||||
[builtin icon](../templates/icons.md#bundled-icons), additionally `bug`, `chat`,
|
[builtin icon](../templates/extending-templates/icons.md#bundled-icons),
|
||||||
and `docs` are available as three special icons.
|
additionally `bug`, `chat`, and `docs` are available as three special icons.
|
||||||
|
|
||||||
### Configuration
|
### Configuration
|
||||||
|
|
@ -1,6 +1,8 @@
|
|||||||
|
# Configure Control Plane Access
|
||||||
|
|
||||||
Coder server's primary configuration is done via environment variables. For a
|
Coder server's primary configuration is done via environment variables. For a
|
||||||
full list of the options, run `coder server --help` or see our
|
full list of the options, run `coder server --help` or see our
|
||||||
[CLI documentation](../reference/cli/server.md).
|
[CLI documentation](../../reference/cli/server.md).
|
||||||
|
|
||||||
## Access URL
|
## Access URL
|
||||||
|
|
||||||
@ -39,9 +41,8 @@ coder server
|
|||||||
|
|
||||||
`CODER_WILDCARD_ACCESS_URL` is necessary for
|
`CODER_WILDCARD_ACCESS_URL` is necessary for
|
||||||
[port forwarding](../networking/port-forwarding.md#dashboard) via the dashboard
|
[port forwarding](../networking/port-forwarding.md#dashboard) via the dashboard
|
||||||
or running [coder_apps](../templates/index.md#coder-apps) on an absolute path.
|
or running [coder_apps](../templates/index.md) on an absolute path. Set this to
|
||||||
Set this to a wildcard subdomain that resolves to Coder (e.g.
|
a wildcard subdomain that resolves to Coder (e.g. `*.coder.example.com`).
|
||||||
`*.coder.example.com`).
|
|
||||||
|
|
||||||
If you are providing TLS certificates directly to the Coder server, either
|
If you are providing TLS certificates directly to the Coder server, either
|
||||||
|
|
||||||
@ -49,8 +50,8 @@ If you are providing TLS certificates directly to the Coder server, either
|
|||||||
2. Configure multiple certificates and keys via
|
2. Configure multiple certificates and keys via
|
||||||
[`coder.tls.secretNames`](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
|
[`coder.tls.secretNames`](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
|
||||||
in the Helm Chart, or
|
in the Helm Chart, or
|
||||||
[`--tls-cert-file`](../reference/cli/server.md#--tls-cert-file) and
|
[`--tls-cert-file`](../../reference/cli/server.md#--tls-cert-file) and
|
||||||
[`--tls-key-file`](../reference/cli/server.md#--tls-key-file) command line
|
[`--tls-key-file`](../../reference/cli/server.md#--tls-key-file) command line
|
||||||
options (these both take a comma separated list of files; list certificates
|
options (these both take a comma separated list of files; list certificates
|
||||||
and their respective keys in the same order).
|
and their respective keys in the same order).
|
||||||
|
|
||||||
@ -60,9 +61,9 @@ The Coder server can directly use TLS certificates with `CODER_TLS_ENABLE` and
|
|||||||
accompanying configuration flags. However, Coder can also run behind a
|
accompanying configuration flags. However, Coder can also run behind a
|
||||||
reverse-proxy to terminate TLS certificates from LetsEncrypt, for example.
|
reverse-proxy to terminate TLS certificates from LetsEncrypt, for example.
|
||||||
|
|
||||||
- [Apache](https://github.com/coder/coder/tree/main/examples/web-server/apache)
|
- [Apache](./web-server/apache/index.md)
|
||||||
- [Caddy](https://github.com/coder/coder/tree/main/examples/web-server/caddy)
|
- [Caddy](./web-server/caddy/index.md)
|
||||||
- [NGINX](https://github.com/coder/coder/tree/main/examples/web-server/nginx)
|
- [NGINX](./web-server/nginx/index.md)
|
||||||
|
|
||||||
### Kubernetes TLS configuration
|
### Kubernetes TLS configuration
|
||||||
|
|
||||||
@ -129,63 +130,24 @@ steps:
|
|||||||
6. Start your Coder deployment with
|
6. Start your Coder deployment with
|
||||||
`CODER_PG_CONNECTION_URL=<external-connection-string>`.
|
`CODER_PG_CONNECTION_URL=<external-connection-string>`.
|
||||||
|
|
||||||
## System packages
|
|
||||||
|
|
||||||
If you've installed Coder via a [system package](../install/index.md), you can
|
|
||||||
configure the server by setting the following variables in
|
|
||||||
`/etc/coder.d/coder.env`:
|
|
||||||
|
|
||||||
```env
|
|
||||||
# String. Specifies the external URL (HTTP/S) to access Coder.
|
|
||||||
CODER_ACCESS_URL=https://coder.example.com
|
|
||||||
|
|
||||||
# String. Address to serve the API and dashboard.
|
|
||||||
CODER_HTTP_ADDRESS=0.0.0.0:3000
|
|
||||||
|
|
||||||
# String. The URL of a PostgreSQL database to connect to. If empty, PostgreSQL binaries
|
|
||||||
# will be downloaded from Maven (https://repo1.maven.org/maven2) and store all
|
|
||||||
# data in the config root. Access the built-in database with "coder server postgres-builtin-url".
|
|
||||||
CODER_PG_CONNECTION_URL=
|
|
||||||
|
|
||||||
# Boolean. Specifies if TLS will be enabled.
|
|
||||||
CODER_TLS_ENABLE=
|
|
||||||
|
|
||||||
# If CODER_TLS_ENABLE=true, also set:
|
|
||||||
CODER_TLS_ADDRESS=0.0.0.0:3443
|
|
||||||
|
|
||||||
# String. Specifies the path to the certificate for TLS. It requires a PEM-encoded file.
|
|
||||||
# To configure the listener to use a CA certificate, concatenate the primary
|
|
||||||
# certificate and the CA certificate together. The primary certificate should
|
|
||||||
# appear first in the combined file.
|
|
||||||
CODER_TLS_CERT_FILE=
|
|
||||||
|
|
||||||
# String. Specifies the path to the private key for the certificate. It requires a
|
|
||||||
# PEM-encoded file.
|
|
||||||
CODER_TLS_KEY_FILE=
|
|
||||||
```
|
|
||||||
|
|
||||||
To run Coder as a system service on the host:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
# Use systemd to start Coder now and on reboot
|
|
||||||
sudo systemctl enable --now coder
|
|
||||||
|
|
||||||
# View the logs to ensure a successful start
|
|
||||||
journalctl -u coder.service -b
|
|
||||||
```
|
|
||||||
|
|
||||||
To restart Coder after applying system changes:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
sudo systemctl restart coder
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configuring Coder behind a proxy
|
## Configuring Coder behind a proxy
|
||||||
|
|
||||||
To configure Coder behind a corporate proxy, set the environment variables
|
To configure Coder behind a corporate proxy, set the environment variables
|
||||||
`HTTP_PROXY` and `HTTPS_PROXY`. Be sure to restart the server. Lowercase values
|
`HTTP_PROXY` and `HTTPS_PROXY`. Be sure to restart the server. Lowercase values
|
||||||
(e.g. `http_proxy`) are also respected in this case.
|
(e.g. `http_proxy`) are also respected in this case.
|
||||||
|
|
||||||
|
## External Authentication
|
||||||
|
|
||||||
|
Coder supports external authentication via OAuth2.0. This allows enabling
|
||||||
|
integrations with git providers, such as GitHub, GitLab, and Bitbucket etc.
|
||||||
|
|
||||||
|
External authentication can also be used to integrate with external services
|
||||||
|
like JFrog Artifactory and others.
|
||||||
|
|
||||||
|
Please refer to the [external authentication](../external-auth.md) section for
|
||||||
|
more information.
|
||||||
|
|
||||||
## Up Next
|
## Up Next
|
||||||
|
|
||||||
- [Learn how to upgrade Coder](./upgrade.md).
|
- [Learn how to setup and manage templates](../templates/index.md)
|
||||||
|
- [Setup external provisioners](../provisioners.md)
|
@ -2,7 +2,8 @@
|
|||||||
|
|
||||||
## Requirements
|
## Requirements
|
||||||
|
|
||||||
1. Start a Coder deployment and be sure to set the following [configuration values](https://coder.com/docs/admin/configure):
|
1. Start a Coder deployment and be sure to set the following
|
||||||
|
[configuration values](../../index.md):
|
||||||
|
|
||||||
```env
|
```env
|
||||||
CODER_HTTP_ADDRESS=127.0.0.1:3000
|
CODER_HTTP_ADDRESS=127.0.0.1:3000
|
||||||
@ -10,11 +11,16 @@
|
|||||||
CODER_WILDCARD_ACCESS_URL=*coder.example.com
|
CODER_WILDCARD_ACCESS_URL=*coder.example.com
|
||||||
```
|
```
|
||||||
|
|
||||||
Throughout the guide, be sure to replace `coder.example.com` with the domain you intend to use with Coder.
|
Throughout the guide, be sure to replace `coder.example.com` with the domain
|
||||||
|
you intend to use with Coder.
|
||||||
|
|
||||||
2. Configure your DNS provider to point your coder.example.com and \*.coder.example.com to your server's public IP address.
|
2. Configure your DNS provider to point your coder.example.com and
|
||||||
|
\*.coder.example.com to your server's public IP address.
|
||||||
|
|
||||||
> For example, to use `coder.example.com` as your subdomain, configure `coder.example.com` and `*.coder.example.com` to point to your server's public ip. This can be done by adding A records in your DNS provider's dashboard.
|
> For example, to use `coder.example.com` as your subdomain, configure
|
||||||
|
> `coder.example.com` and `*.coder.example.com` to point to your server's
|
||||||
|
> public ip. This can be done by adding A records in your DNS provider's
|
||||||
|
> dashboard.
|
||||||
|
|
||||||
3. Install Apache (assuming you're on Debian/Ubuntu):
|
3. Install Apache (assuming you're on Debian/Ubuntu):
|
||||||
|
|
||||||
@ -40,17 +46,25 @@
|
|||||||
|
|
||||||
## Install and configure LetsEncrypt Certbot
|
## Install and configure LetsEncrypt Certbot
|
||||||
|
|
||||||
1. Install LetsEncrypt Certbot: Refer to the [CertBot documentation](https://certbot.eff.org/instructions?ws=apache&os=ubuntufocal&tab=wildcard). Be sure to pick the wildcard tab and select your DNS provider for instructions to install the necessary DNS plugin.
|
1. Install LetsEncrypt Certbot: Refer to the
|
||||||
|
[CertBot documentation](https://certbot.eff.org/instructions?ws=apache&os=ubuntufocal&tab=wildcard).
|
||||||
|
Be sure to pick the wildcard tab and select your DNS provider for
|
||||||
|
instructions to install the necessary DNS plugin.
|
||||||
|
|
||||||
## Create DNS provider credentials
|
## Create DNS provider credentials
|
||||||
|
|
||||||
> This example assumes you're using CloudFlare as your DNS provider. For other providers, refer to the [CertBot documentation](https://eff-certbot.readthedocs.io/en/stable/using.html#dns-plugins).
|
> This example assumes you're using CloudFlare as your DNS provider. For other
|
||||||
|
> providers, refer to the
|
||||||
|
> [CertBot documentation](https://eff-certbot.readthedocs.io/en/stable/using.html#dns-plugins).
|
||||||
|
|
||||||
1. Create an API token for the DNS provider you're using: e.g. [CloudFlare](https://dash.cloudflare.com/profile/api-tokens) with the following permissions:
|
1. Create an API token for the DNS provider you're using: e.g.
|
||||||
|
[CloudFlare](https://developers.cloudflare.com/fundamentals/api/get-started/create-token)
|
||||||
|
with the following permissions:
|
||||||
|
|
||||||
- Zone - DNS - Edit
|
- Zone - DNS - Edit
|
||||||
|
|
||||||
2. Create a file in `.secrets/certbot/cloudflare.ini` with the following content:
|
2. Create a file in `.secrets/certbot/cloudflare.ini` with the following
|
||||||
|
content:
|
||||||
|
|
||||||
```ini
|
```ini
|
||||||
dns_cloudflare_api_token = YOUR_API_TOKEN
|
dns_cloudflare_api_token = YOUR_API_TOKEN
|
||||||
@ -78,7 +92,8 @@
|
|||||||
|
|
||||||
## Configure Apache
|
## Configure Apache
|
||||||
|
|
||||||
> This example assumes Coder is running locally on `127.0.0.1:3000` and that you're using `coder.example.com` as your subdomain.
|
> This example assumes Coder is running locally on `127.0.0.1:3000` and that
|
||||||
|
> you're using `coder.example.com` as your subdomain.
|
||||||
|
|
||||||
1. Create Apache configuration for Coder:
|
1. Create Apache configuration for Coder:
|
||||||
|
|
||||||
@ -153,4 +168,5 @@
|
|||||||
sudo certbot renew -q
|
sudo certbot renew -q
|
||||||
```
|
```
|
||||||
|
|
||||||
And that's it, you should now be able to access Coder at your sub(domain) e.g. `https://coder.example.com`.
|
And that's it, you should now be able to access Coder at your sub(domain) e.g.
|
||||||
|
`https://coder.example.com`.
|
@ -1,12 +1,15 @@
|
|||||||
# Caddy
|
# Caddy
|
||||||
|
|
||||||
This is an example configuration of how to use Coder with [caddy](https://caddyserver.com/docs). To use Caddy to generate TLS certificates, you'll need a domain name that resolves to your Caddy server.
|
This is an example configuration of how to use Coder with
|
||||||
|
[caddy](https://caddyserver.com/docs). To use Caddy to generate TLS
|
||||||
|
certificates, you'll need a domain name that resolves to your Caddy server.
|
||||||
|
|
||||||
## Getting started
|
## Getting started
|
||||||
|
|
||||||
### With docker-compose
|
### With docker-compose
|
||||||
|
|
||||||
1. [Install Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/)
|
1. [Install Docker](https://docs.docker.com/engine/install/) and
|
||||||
|
[Docker Compose](https://docs.docker.com/compose/install/)
|
||||||
|
|
||||||
1. Start with our example configuration
|
1. Start with our example configuration
|
||||||
|
|
||||||
@ -18,17 +21,22 @@ This is an example configuration of how to use Coder with [caddy](https://caddys
|
|||||||
|
|
||||||
# Clone coder/coder and copy the Caddy example
|
# Clone coder/coder and copy the Caddy example
|
||||||
git clone https://github.com/coder/coder /tmp/coder
|
git clone https://github.com/coder/coder /tmp/coder
|
||||||
mv /tmp/coder/examples/web-server/caddy $(pwd)
|
mv /tmp/coder/docs/admin/setup/web-server/caddy $(pwd)
|
||||||
```
|
```
|
||||||
|
|
||||||
1. Modify the [Caddyfile](./Caddyfile) and change the following values:
|
1. Modify the [Caddyfile](./Caddyfile) and change the following values:
|
||||||
|
|
||||||
- `localhost:3000`: Change to `coder:7080` (Coder container on Docker network)
|
- `localhost:3000`: Change to `coder:7080` (Coder container on Docker
|
||||||
- `email@example.com`: Email to request certificates from LetsEncrypt/ZeroSSL (does not have to be Coder admin email)
|
network)
|
||||||
|
- `email@example.com`: Email to request certificates from LetsEncrypt/ZeroSSL
|
||||||
|
(does not have to be Coder admin email)
|
||||||
- `coder.example.com`: Domain name you're using for Coder.
|
- `coder.example.com`: Domain name you're using for Coder.
|
||||||
- `*.coder.example.com`: Domain name for wildcard apps, commonly used for [dashboard port forwarding](https://coder.com/docs/networking/port-forwarding#dashboard). This is optional and can be removed.
|
- `*.coder.example.com`: Domain name for wildcard apps, commonly used for
|
||||||
|
[dashboard port forwarding](../../../networking/port-forwarding.md). This
|
||||||
|
is optional and can be removed.
|
||||||
|
|
||||||
1. Start Coder. Set `CODER_ACCESS_URL` and `CODER_WILDCARD_ACCESS_URL` to the domain you're using in your Caddyfile.
|
1. Start Coder. Set `CODER_ACCESS_URL` and `CODER_WILDCARD_ACCESS_URL` to the
|
||||||
|
domain you're using in your Caddyfile.
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
export CODER_ACCESS_URL=https://coder.example.com
|
export CODER_ACCESS_URL=https://coder.example.com
|
||||||
@ -38,28 +46,35 @@ This is an example configuration of how to use Coder with [caddy](https://caddys
|
|||||||
|
|
||||||
### Standalone
|
### Standalone
|
||||||
|
|
||||||
1. If you haven't already, [install Coder](https://coder.com/docs/install)
|
1. If you haven't already, [install Coder](../../../../install/index.md)
|
||||||
|
|
||||||
2. Install [Caddy Server](https://caddyserver.com/docs/install)
|
2. Install [Caddy Server](https://caddyserver.com/docs/install)
|
||||||
|
|
||||||
3. Copy our sample [Caddyfile](./Caddyfile) and change the following values:
|
3. Copy our sample [Caddyfile](./Caddyfile) and change the following values:
|
||||||
|
|
||||||
> If you're installed Caddy as a system package, update the default Caddyfile with `vim /etc/caddy/Caddyfile`
|
> If you're installed Caddy as a system package, update the default Caddyfile
|
||||||
|
> with `vim /etc/caddy/Caddyfile`
|
||||||
|
|
||||||
- `email@example.com`: Email to request certificates from LetsEncrypt/ZeroSSL (does not have to be Coder admin email)
|
- `email@example.com`: Email to request certificates from LetsEncrypt/ZeroSSL
|
||||||
|
(does not have to be Coder admin email)
|
||||||
- `coder.example.com`: Domain name you're using for Coder.
|
- `coder.example.com`: Domain name you're using for Coder.
|
||||||
- `*.coder.example.com`: Domain name for wildcard apps, commonly used for [dashboard port forwarding](https://coder.com/docs/networking/port-forwarding#dashboard). This is optional and can be removed.
|
- `*.coder.example.com`: Domain name for wildcard apps, commonly used for
|
||||||
- `localhost:3000`: Address Coder is running on. Modify this if you changed `CODER_HTTP_ADDRESS` in the Coder configuration.
|
[dashboard port forwarding](../../../networking/port-forwarding.md). This
|
||||||
- _DO NOT CHANGE the `ask http://example.com` line! Doing so will result in your certs potentially not being generated._
|
is optional and can be removed.
|
||||||
|
- `localhost:3000`: Address Coder is running on. Modify this if you changed
|
||||||
|
`CODER_HTTP_ADDRESS` in the Coder configuration.
|
||||||
|
- _DO NOT CHANGE the `ask http://example.com` line! Doing so will result in
|
||||||
|
your certs potentially not being generated._
|
||||||
|
|
||||||
4. [Configure Coder](https://coder.com/docs/admin/configure) and change the following values:
|
4. [Configure Coder](../../index.md) and change the following values:
|
||||||
|
|
||||||
- `CODER_ACCESS_URL`: root domain (e.g. `https://coder.example.com`)
|
- `CODER_ACCESS_URL`: root domain (e.g. `https://coder.example.com`)
|
||||||
- `CODER_WILDCARD_ACCESS_URL`: wildcard domain (e.g. `*.example.com`).
|
- `CODER_WILDCARD_ACCESS_URL`: wildcard domain (e.g. `*.example.com`).
|
||||||
|
|
||||||
5. Start the Caddy server:
|
5. Start the Caddy server:
|
||||||
|
|
||||||
If you're [keeping Caddy running](https://caddyserver.com/docs/running) via a system service:
|
If you're [keeping Caddy running](https://caddyserver.com/docs/running) via a
|
||||||
|
system service:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
sudo systemctl restart caddy
|
sudo systemctl restart caddy
|
||||||
@ -71,7 +86,8 @@ This is an example configuration of how to use Coder with [caddy](https://caddys
|
|||||||
caddy run
|
caddy run
|
||||||
```
|
```
|
||||||
|
|
||||||
6. Optionally, use [ufw](https://wiki.ubuntu.com/UncomplicatedFirewall) or another firewall to disable external traffic outside of Caddy.
|
6. Optionally, use [ufw](https://wiki.ubuntu.com/UncomplicatedFirewall) or
|
||||||
|
another firewall to disable external traffic outside of Caddy.
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
# Check status of UncomplicatedFirewall
|
# Check status of UncomplicatedFirewall
|
||||||
@ -91,21 +107,39 @@ This is an example configuration of how to use Coder with [caddy](https://caddys
|
|||||||
sudo ufw enable
|
sudo ufw enable
|
||||||
```
|
```
|
||||||
|
|
||||||
7. Navigate to your Coder URL! A TLS certificate should be auto-generated on your first visit.
|
7. Navigate to your Coder URL! A TLS certificate should be auto-generated on
|
||||||
|
your first visit.
|
||||||
|
|
||||||
## Generating wildcard certificates
|
## Generating wildcard certificates
|
||||||
|
|
||||||
By default, this configuration uses Caddy's [on-demand TLS](https://caddyserver.com/docs/caddyfile/options#on-demand-tls) to generate a certificate for each subdomain (e.g. `app1.coder.example.com`, `app2.coder.example.com`). When users visit new subdomains, such as accessing [ports on a workspace](../../../docs/networking/port-forwarding.md), the request will take an additional 5-30 seconds since a new certificate is being generated.
|
By default, this configuration uses Caddy's
|
||||||
|
[on-demand TLS](https://caddyserver.com/docs/caddyfile/options#on-demand-tls) to
|
||||||
|
generate a certificate for each subdomain (e.g. `app1.coder.example.com`,
|
||||||
|
`app2.coder.example.com`). When users visit new subdomains, such as accessing
|
||||||
|
[ports on a workspace](../../../networking/port-forwarding.md), the request will
|
||||||
|
take an additional 5-30 seconds since a new certificate is being generated.
|
||||||
|
|
||||||
For production deployments, we recommend configuring Caddy to generate a wildcard certificate, which requires an explicit DNS challenge and additional Caddy modules.
|
For production deployments, we recommend configuring Caddy to generate a
|
||||||
|
wildcard certificate, which requires an explicit DNS challenge and additional
|
||||||
|
Caddy modules.
|
||||||
|
|
||||||
1. Install a custom Caddy build that includes the [caddy-dns](https://github.com/caddy-dns) module for your DNS provider (e.g. CloudFlare, Route53).
|
1. Install a custom Caddy build that includes the
|
||||||
|
[caddy-dns](https://github.com/caddy-dns) module for your DNS provider (e.g.
|
||||||
|
CloudFlare, Route53).
|
||||||
|
|
||||||
- Docker: [Build an custom Caddy image](https://github.com/docker-library/docs/tree/master/caddy#adding-custom-caddy-modules) with the module for your DNS provider. Be sure to reference the new image in the `docker-compose.yaml`.
|
- Docker:
|
||||||
|
[Build an custom Caddy image](https://github.com/docker-library/docs/tree/master/caddy#adding-custom-caddy-modules)
|
||||||
|
with the module for your DNS provider. Be sure to reference the new image
|
||||||
|
in the `docker-compose.yaml`.
|
||||||
|
|
||||||
- Standalone: [Download a custom Caddy build](https://caddyserver.com/download) with the module for your DNS provider. If you're using Debian/Ubuntu, you [can configure the Caddy package](https://caddyserver.com/docs/build#package-support-files-for-custom-builds-for-debianubunturaspbian) to use the new build.
|
- Standalone:
|
||||||
|
[Download a custom Caddy build](https://caddyserver.com/download) with the
|
||||||
|
module for your DNS provider. If you're using Debian/Ubuntu, you
|
||||||
|
[can configure the Caddy package](https://caddyserver.com/docs/build#package-support-files-for-custom-builds-for-debianubunturaspbian)
|
||||||
|
to use the new build.
|
||||||
|
|
||||||
2. Edit your `Caddyfile` and add the necessary credentials/API tokens to solve the DNS challenge for wildcard certificates.
|
2. Edit your `Caddyfile` and add the necessary credentials/API tokens to solve
|
||||||
|
the DNS challenge for wildcard certificates.
|
||||||
|
|
||||||
For example, for AWS Route53:
|
For example, for AWS Route53:
|
||||||
|
|
||||||
@ -127,11 +161,14 @@ For production deployments, we recommend configuring Caddy to generate a wildcar
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
> Configuration reference from [caddy-dns/route53](https://github.com/caddy-dns/route53).
|
> Configuration reference from
|
||||||
|
> [caddy-dns/route53](https://github.com/caddy-dns/route53).
|
||||||
|
|
||||||
And for CloudFlare:
|
And for CloudFlare:
|
||||||
|
|
||||||
Generate a [token](https://dash.cloudflare.com/profile/api-tokens) with the following permissions:
|
Generate a
|
||||||
|
[token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token)
|
||||||
|
with the following permissions:
|
||||||
|
|
||||||
- Zone:Zone:Edit
|
- Zone:Zone:Edit
|
||||||
|
|
||||||
@ -146,4 +183,5 @@ For production deployments, we recommend configuring Caddy to generate a wildcar
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
> Configuration reference from [caddy-dns/cloudflare](https://github.com/caddy-dns/cloudflare).
|
> Configuration reference from
|
||||||
|
> [caddy-dns/cloudflare](https://github.com/caddy-dns/cloudflare).
|
@ -2,7 +2,8 @@
|
|||||||
|
|
||||||
## Requirements
|
## Requirements
|
||||||
|
|
||||||
1. Start a Coder deployment and be sure to set the following [configuration values](https://coder.com/docs/admin/configure):
|
1. Start a Coder deployment and be sure to set the following
|
||||||
|
[configuration values](../../index.md):
|
||||||
|
|
||||||
```env
|
```env
|
||||||
CODER_HTTP_ADDRESS=127.0.0.1:3000
|
CODER_HTTP_ADDRESS=127.0.0.1:3000
|
||||||
@ -10,11 +11,16 @@
|
|||||||
CODER_WILDCARD_ACCESS_URL=*.coder.example.com
|
CODER_WILDCARD_ACCESS_URL=*.coder.example.com
|
||||||
```
|
```
|
||||||
|
|
||||||
Throughout the guide, be sure to replace `coder.example.com` with the domain you intend to use with Coder.
|
Throughout the guide, be sure to replace `coder.example.com` with the domain
|
||||||
|
you intend to use with Coder.
|
||||||
|
|
||||||
2. Configure your DNS provider to point your coder.example.com and \*.coder.example.com to your server's public IP address.
|
2. Configure your DNS provider to point your coder.example.com and
|
||||||
|
\*.coder.example.com to your server's public IP address.
|
||||||
|
|
||||||
> For example, to use `coder.example.com` as your subdomain, configure `coder.example.com` and `*.coder.example.com` to point to your server's public ip. This can be done by adding A records in your DNS provider's dashboard.
|
> For example, to use `coder.example.com` as your subdomain, configure
|
||||||
|
> `coder.example.com` and `*.coder.example.com` to point to your server's
|
||||||
|
> public ip. This can be done by adding A records in your DNS provider's
|
||||||
|
> dashboard.
|
||||||
|
|
||||||
3. Install NGINX (assuming you're on Debian/Ubuntu):
|
3. Install NGINX (assuming you're on Debian/Ubuntu):
|
||||||
|
|
||||||
@ -30,7 +36,8 @@
|
|||||||
|
|
||||||
## Adding Coder deployment subdomain
|
## Adding Coder deployment subdomain
|
||||||
|
|
||||||
> This example assumes Coder is running locally on `127.0.0.1:3000` and that you're using `coder.example.com` as your subdomain.
|
> This example assumes Coder is running locally on `127.0.0.1:3000` and that
|
||||||
|
> you're using `coder.example.com` as your subdomain.
|
||||||
|
|
||||||
1. Create NGINX configuration for this app:
|
1. Create NGINX configuration for this app:
|
||||||
|
|
||||||
@ -46,17 +53,25 @@
|
|||||||
|
|
||||||
## Install and configure LetsEncrypt Certbot
|
## Install and configure LetsEncrypt Certbot
|
||||||
|
|
||||||
1. Install LetsEncrypt Certbot: Refer to the [CertBot documentation](https://certbot.eff.org/instructions?ws=apache&os=ubuntufocal&tab=wildcard). Be sure to pick the wildcard tab and select your DNS provider for instructions to install the necessary DNS plugin.
|
1. Install LetsEncrypt Certbot: Refer to the
|
||||||
|
[CertBot documentation](https://certbot.eff.org/instructions?ws=apache&os=ubuntufocal&tab=wildcard).
|
||||||
|
Be sure to pick the wildcard tab and select your DNS provider for
|
||||||
|
instructions to install the necessary DNS plugin.
|
||||||
|
|
||||||
## Create DNS provider credentials
|
## Create DNS provider credentials
|
||||||
|
|
||||||
> This example assumes you're using CloudFlare as your DNS provider. For other providers, refer to the [CertBot documentation](https://eff-certbot.readthedocs.io/en/stable/using.html#dns-plugins).
|
> This example assumes you're using CloudFlare as your DNS provider. For other
|
||||||
|
> providers, refer to the
|
||||||
|
> [CertBot documentation](https://eff-certbot.readthedocs.io/en/stable/using.html#dns-plugins).
|
||||||
|
|
||||||
1. Create an API token for the DNS provider you're using: e.g. [CloudFlare](https://dash.cloudflare.com/profile/api-tokens) with the following permissions:
|
1. Create an API token for the DNS provider you're using: e.g.
|
||||||
|
[CloudFlare](https://developers.cloudflare.com/fundamentals/api/get-started/create-token)
|
||||||
|
with the following permissions:
|
||||||
|
|
||||||
- Zone - DNS - Edit
|
- Zone - DNS - Edit
|
||||||
|
|
||||||
2. Create a file in `.secrets/certbot/cloudflare.ini` with the following content:
|
2. Create a file in `.secrets/certbot/cloudflare.ini` with the following
|
||||||
|
content:
|
||||||
|
|
||||||
```ini
|
```ini
|
||||||
dns_cloudflare_api_token = YOUR_API_TOKEN
|
dns_cloudflare_api_token = YOUR_API_TOKEN
|
||||||
@ -160,4 +175,5 @@
|
|||||||
sudo systemctl restart nginx
|
sudo systemctl restart nginx
|
||||||
```
|
```
|
||||||
|
|
||||||
And that's it, you should now be able to access Coder at your sub(domain) e.g. `https://coder.example.com`.
|
And that's it, you should now be able to access Coder at your sub(domain) e.g.
|
||||||
|
`https://coder.example.com`.
|
164
docs/admin/templates/creating-templates.md
Normal file
164
docs/admin/templates/creating-templates.md
Normal file
@ -0,0 +1,164 @@
|
|||||||
|
# Creating Templates
|
||||||
|
|
||||||
|
Users with the `Template Administrator` role or above can create templates
|
||||||
|
within Coder.
|
||||||
|
|
||||||
|
## From a starter template
|
||||||
|
|
||||||
|
In most cases, it is best to start with a starter template.
|
||||||
|
|
||||||
|
<div class="tabs">
|
||||||
|
|
||||||
|
### Web UI
|
||||||
|
|
||||||
|
After navigating to the Templates page in the Coder dashboard, choose
|
||||||
|
`Create Template > Choose a starter template`.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
From there, select a starter template for desired underlying infrastructure for
|
||||||
|
workspaces.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
Give your template a name, description, and icon and press `Create template`.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
> **⚠️ Note**: If template creation fails, Coder is likely not authorized to
|
||||||
|
> deploy infrastructure in the given location. Learn how to configure
|
||||||
|
> [provisioner authentication](#TODO).
|
||||||
|
|
||||||
|
### CLI
|
||||||
|
|
||||||
|
You can the [Coder CLI](../../install/cli.md) to manage templates for Coder.
|
||||||
|
After [logging in](#TODO) to your deployment, create a folder to store your
|
||||||
|
templates:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# This snippet applies to macOS and Linux only
|
||||||
|
mkdir $HOME/coder-templates
|
||||||
|
cd $HOME/coder-templates
|
||||||
|
```
|
||||||
|
|
||||||
|
Use the [`templates init`](../../reference/cli/templates_init.md) command to
|
||||||
|
pull a starter template:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
coder templates init
|
||||||
|
```
|
||||||
|
|
||||||
|
After pulling the template to your local machine (e.g. `aws-linux`), you can
|
||||||
|
rename it:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# This snippet applies to macOS and Linux only
|
||||||
|
mv aws-linux universal-template
|
||||||
|
cd universal-template
|
||||||
|
```
|
||||||
|
|
||||||
|
Next, push it to Coder with the
|
||||||
|
[`templates push`](../../reference/cli/templates_push.md) command:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
coder templates push
|
||||||
|
```
|
||||||
|
|
||||||
|
> ⚠️ Note: If `template push` fails, Coder is likely not authorized to deploy
|
||||||
|
> infrastructure in the given location. Learn how to configure
|
||||||
|
> [provisioner authentication](../provisioners.md).
|
||||||
|
|
||||||
|
You can edit the metadata of the template such as the display name with the
|
||||||
|
[`templates edit`](../../reference/cli/templates_edit.md) command:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
coder templates edit universal-template \
|
||||||
|
--display-name "Universal Template" \
|
||||||
|
--description "Virtual machine configured with Java, Python, Typescript, IntelliJ IDEA, and Ruby. Use this for starter projects. " \
|
||||||
|
--icon "/emojis/2b50.png"
|
||||||
|
```
|
||||||
|
|
||||||
|
### CI/CD
|
||||||
|
|
||||||
|
Follow the [change management](./managing-templates/change-management.md) guide
|
||||||
|
to manage templates via GitOps.
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
## From an existing template
|
||||||
|
|
||||||
|
You can duplicate an existing template in your Coder deployment. This will copy
|
||||||
|
the template code and metadata, allowing you to make changes without affecting
|
||||||
|
the original template.
|
||||||
|
|
||||||
|
<div class="tabs">
|
||||||
|
|
||||||
|
### Web UI
|
||||||
|
|
||||||
|
After navigating to the page for a template, use the dropdown menu on the right
|
||||||
|
to `Duplicate`.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
Give the new template a name, icon, and description.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
Press `Create template`. After the build, you will be taken to the new template
|
||||||
|
page.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
### CLI
|
||||||
|
|
||||||
|
First, ensure you are logged in to the control plane as a user with permissions
|
||||||
|
to read and write permissions.
|
||||||
|
|
||||||
|
```console
|
||||||
|
coder login
|
||||||
|
```
|
||||||
|
|
||||||
|
You can list the available templates with the following CLI invocation.
|
||||||
|
|
||||||
|
```console
|
||||||
|
coder templates list
|
||||||
|
```
|
||||||
|
|
||||||
|
After identified the template you'd like to work from, clone it into a directory
|
||||||
|
with a name you'd like to assign to the new modified template.
|
||||||
|
|
||||||
|
```console
|
||||||
|
coder templates pull <template-name> ./<new-template-name>
|
||||||
|
```
|
||||||
|
|
||||||
|
Then, you can make modifications to the existing template in this directory and
|
||||||
|
push them to the control plane using the `-d` flag to specify the directory.
|
||||||
|
|
||||||
|
```console
|
||||||
|
coder templates push <new-template-name> -d ./<new-template-name>
|
||||||
|
```
|
||||||
|
|
||||||
|
You will then see your new template in the dashboard.
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
## From scratch (advanced)
|
||||||
|
|
||||||
|
There may be cases where you want to create a template from scratch. You can use
|
||||||
|
[any Terraform provider](https://registry.terraform.com) with Coder to create
|
||||||
|
templates for additional clouds (e.g. Hetzner, Alibaba) or orchestrators
|
||||||
|
(VMware, Proxmox) that we do not provide example templates for.
|
||||||
|
|
||||||
|
Refer to the following resources:
|
||||||
|
|
||||||
|
- [Tutorial: Create a template from scratch](../../tutorials/template-from-scratch.md)
|
||||||
|
- [Extending templates](./extending-templates/index.md): Features and concepts
|
||||||
|
around templates (agents, parameters, variables, etc)
|
||||||
|
- [Coder Registry](https://registry.coder.com/templates): Official and community
|
||||||
|
templates for Coder
|
||||||
|
- [Coder Terraform Provider Reference](https://registry.terraform.io/providers/coder/coder)
|
||||||
|
|
||||||
|
### Next steps
|
||||||
|
|
||||||
|
- [Extending templates](./extending-templates/index.md)
|
||||||
|
- [Managing templates](./managing-templates/index.md)
|
@ -1,6 +1,6 @@
|
|||||||
# Agent metadata
|
# Agent metadata
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
You can show live operational metrics to workspace users with agent metadata. It
|
You can show live operational metrics to workspace users with agent metadata. It
|
||||||
is the dynamic complement of [resource metadata](./resource-metadata.md).
|
is the dynamic complement of [resource metadata](./resource-metadata.md).
|
||||||
@ -15,14 +15,14 @@ All of these examples use
|
|||||||
for the script declaration. With heredoc strings, you can script without messy
|
for the script declaration. With heredoc strings, you can script without messy
|
||||||
escape codes, just as if you were working in your terminal.
|
escape codes, just as if you were working in your terminal.
|
||||||
|
|
||||||
Some of the examples use the [`coder stat`](../reference/cli/stat.md) command.
|
Some of the examples use the [`coder stat`](../../../reference/cli/stat.md)
|
||||||
This is useful for determining CPU and memory usage of the VM or container that
|
command. This is useful for determining CPU and memory usage of the VM or
|
||||||
the workspace is running in, which is more accurate than resource usage about
|
container that the workspace is running in, which is more accurate than resource
|
||||||
the workspace's host.
|
usage about the workspace's host.
|
||||||
|
|
||||||
Here's a standard set of metadata snippets for Linux agents:
|
Here's a standard set of metadata snippets for Linux agents:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "coder_agent" "main" {
|
resource "coder_agent" "main" {
|
||||||
os = "linux"
|
os = "linux"
|
||||||
...
|
...
|
@ -23,7 +23,7 @@ inside Coder workspaces. See [Systemd in Docker](#systemd-in-docker).
|
|||||||
After [installing Sysbox](https://github.com/nestybox/sysbox#installation) on
|
After [installing Sysbox](https://github.com/nestybox/sysbox#installation) on
|
||||||
the Coder host, modify your template to use the sysbox-runc runtime:
|
the Coder host, modify your template to use the sysbox-runc runtime:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "docker_container" "workspace" {
|
resource "docker_container" "workspace" {
|
||||||
# ...
|
# ...
|
||||||
name = "coder-${data.coder_workspace.me.owner}-${lower(data.coder_workspace.me.name)}"
|
name = "coder-${data.coder_workspace.me.owner}-${lower(data.coder_workspace.me.name)}"
|
||||||
@ -55,7 +55,7 @@ After
|
|||||||
modify your template to use the sysbox-runc RuntimeClass. This requires the
|
modify your template to use the sysbox-runc RuntimeClass. This requires the
|
||||||
Kubernetes Terraform provider version 2.16.0 or greater.
|
Kubernetes Terraform provider version 2.16.0 or greater.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
terraform {
|
terraform {
|
||||||
required_providers {
|
required_providers {
|
||||||
coder = {
|
coder = {
|
||||||
@ -175,7 +175,7 @@ $ kubectl create secret docker-registry <name> \
|
|||||||
--docker-email=<service-account-email>
|
--docker-email=<service-account-email>
|
||||||
```
|
```
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
env {
|
env {
|
||||||
name = "CODER_IMAGE_PULL_SECRET"
|
name = "CODER_IMAGE_PULL_SECRET"
|
||||||
value_from {
|
value_from {
|
||||||
@ -278,7 +278,7 @@ your nodes cannot run Sysbox.
|
|||||||
|
|
||||||
### Use a privileged sidecar container in Docker-based templates
|
### Use a privileged sidecar container in Docker-based templates
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "coder_agent" "main" {
|
resource "coder_agent" "main" {
|
||||||
os = "linux"
|
os = "linux"
|
||||||
arch = "amd64"
|
arch = "amd64"
|
||||||
@ -315,7 +315,7 @@ resource "docker_container" "workspace" {
|
|||||||
|
|
||||||
### Use a privileged sidecar container in Kubernetes-based templates
|
### Use a privileged sidecar container in Kubernetes-based templates
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
terraform {
|
terraform {
|
||||||
required_providers {
|
required_providers {
|
||||||
coder = {
|
coder = {
|
||||||
@ -387,7 +387,7 @@ After
|
|||||||
modify your template to use the sysbox-runc RuntimeClass. This requires the
|
modify your template to use the sysbox-runc RuntimeClass. This requires the
|
||||||
Kubernetes Terraform provider version 2.16.0 or greater.
|
Kubernetes Terraform provider version 2.16.0 or greater.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
terraform {
|
terraform {
|
||||||
required_providers {
|
required_providers {
|
||||||
coder = {
|
coder = {
|
96
docs/admin/templates/extending-templates/external-auth.md
Normal file
96
docs/admin/templates/extending-templates/external-auth.md
Normal file
@ -0,0 +1,96 @@
|
|||||||
|
# External Authentication
|
||||||
|
|
||||||
|
Coder integrates with any OpenID Connect provider to automate away the need for
|
||||||
|
developers to authenticate with external services within their workspace. This
|
||||||
|
can be used to authenticate with git providers, private registries, or any other
|
||||||
|
service that requires authentication.
|
||||||
|
|
||||||
|
## External Auth Providers
|
||||||
|
|
||||||
|
External auth providers are configured using environment variables in the Coder
|
||||||
|
Control Plane. See
|
||||||
|
|
||||||
|
## Git Providers
|
||||||
|
|
||||||
|
When developers use `git` inside their workspace, they are prompted to
|
||||||
|
authenticate. After that, Coder will store and refresh tokens for future
|
||||||
|
operations.
|
||||||
|
|
||||||
|
<video autoplay playsinline loop>
|
||||||
|
<source src="https://github.com/coder/coder/blob/main/site/static/external-auth.mp4?raw=true" type="video/mp4">
|
||||||
|
Your browser does not support the video tag.
|
||||||
|
</video>
|
||||||
|
|
||||||
|
### Require git authentication in templates
|
||||||
|
|
||||||
|
If your template requires git authentication (e.g. running `git clone` in the
|
||||||
|
[startup_script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)),
|
||||||
|
you can require users authenticate via git prior to creating a workspace:
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
### Native git authentication will auto-refresh tokens
|
||||||
|
|
||||||
|
<blockquote class="info">
|
||||||
|
<p>
|
||||||
|
This is the preferred authentication method.
|
||||||
|
</p>
|
||||||
|
</blockquote>
|
||||||
|
|
||||||
|
By default, the coder agent will configure native `git` authentication via the
|
||||||
|
`GIT_ASKPASS` environment variable. Meaning, with no additional configuration,
|
||||||
|
external authentication will work with native `git` commands.
|
||||||
|
|
||||||
|
To check the auth token being used **from inside a running workspace**, run:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
# If the exit code is non-zero, then the user is not authenticated with the
|
||||||
|
# external provider.
|
||||||
|
coder external-auth access-token <external-auth-id>
|
||||||
|
```
|
||||||
|
|
||||||
|
Note: Some IDE's override the `GIT_ASKPASS` environment variable and need to be
|
||||||
|
configured.
|
||||||
|
|
||||||
|
**VSCode**
|
||||||
|
|
||||||
|
Use the
|
||||||
|
[Coder](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote)
|
||||||
|
extension to automatically configure these settings for you!
|
||||||
|
|
||||||
|
Otherwise, you can manually configure the following settings:
|
||||||
|
|
||||||
|
- Set `git.terminalAuthentication` to `false`
|
||||||
|
- Set `git.useIntegratedAskPass` to `false`
|
||||||
|
|
||||||
|
### Hard coded tokens do not auto-refresh
|
||||||
|
|
||||||
|
If the token is required to be inserted into the workspace, for example
|
||||||
|
[GitHub cli](https://cli.github.com/), the auth token can be inserted from the
|
||||||
|
template. This token will not auto-refresh. The following example will
|
||||||
|
authenticate via GitHub and auto-clone a repo into the `~/coder` directory.
|
||||||
|
|
||||||
|
```tf
|
||||||
|
data "coder_external_auth" "github" {
|
||||||
|
# Matches the ID of the external auth provider in Coder.
|
||||||
|
id = "github"
|
||||||
|
}
|
||||||
|
|
||||||
|
resource "coder_agent" "dev" {
|
||||||
|
os = "linux"
|
||||||
|
arch = "amd64"
|
||||||
|
dir = "~/coder"
|
||||||
|
env = {
|
||||||
|
GITHUB_TOKEN : data.coder_external_auth.github.access_token
|
||||||
|
}
|
||||||
|
startup_script = <<EOF
|
||||||
|
if [ ! -d ~/coder ]; then
|
||||||
|
git clone https://github.com/coder/coder
|
||||||
|
fi
|
||||||
|
EOF
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
See the
|
||||||
|
[Terraform provider documentation](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/external_auth)
|
||||||
|
for all available options.
|
@ -1,7 +1,5 @@
|
|||||||
# Icons
|
# Icons
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
Coder uses icons in several places, including ones that can be configured
|
Coder uses icons in several places, including ones that can be configured
|
||||||
throughout the app, or specified in your Terraform. They're specified by a URL,
|
throughout the app, or specified in your Terraform. They're specified by a URL,
|
||||||
which can be to an image hosted on a CDN of your own, or one of the icons that
|
which can be to an image hosted on a CDN of your own, or one of the icons that
|
||||||
@ -24,7 +22,7 @@ come bundled with your Coder deployment.
|
|||||||
|
|
||||||
These can all be configured to use an icon by setting the `icon` field.
|
These can all be configured to use an icon by setting the `icon` field.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_parameter" "my_parameter" {
|
data "coder_parameter" "my_parameter" {
|
||||||
icon = "/icon/coder.svg"
|
icon = "/icon/coder.svg"
|
||||||
|
|
||||||
@ -34,7 +32,7 @@ come bundled with your Coder deployment.
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
- [**Authentication Providers**](https://coder.com/docs/v2/latest/admin/external-auth):
|
- [**Authentication Providers**](https://coder.com/docs/admin/external-auth):
|
||||||
|
|
||||||
- Use icons for external authentication providers to make them recognizable.
|
- Use icons for external authentication providers to make them recognizable.
|
||||||
You can set an icon for each provider by setting the
|
You can set an icon for each provider by setting the
|
||||||
@ -46,7 +44,7 @@ come bundled with your Coder deployment.
|
|||||||
CODER_EXTERNAL_AUTH_1_ICON=/icon/google.svg
|
CODER_EXTERNAL_AUTH_1_ICON=/icon/google.svg
|
||||||
```
|
```
|
||||||
|
|
||||||
- [**Support Links**](../admin/appearance.md#support-links):
|
- [**Support Links**](../../setup/appearance.md#support-links):
|
||||||
|
|
||||||
- Use icons for support links to make them recognizable. You can set the
|
- Use icons for support links to make them recognizable. You can set the
|
||||||
`icon` field for each link in `CODER_SUPPORT_LINKS` array.
|
`icon` field for each link in `CODER_SUPPORT_LINKS` array.
|
||||||
@ -62,7 +60,7 @@ You can also view the entire list, with search and previews, by navigating to
|
|||||||
/icons on your Coder deployment. E.g. [https://coder.example.com/icons](#). This
|
/icons on your Coder deployment. E.g. [https://coder.example.com/icons](#). This
|
||||||
can be particularly useful in airgapped deployments.
|
can be particularly useful in airgapped deployments.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
## External icons
|
## External icons
|
||||||
|
|
93
docs/admin/templates/extending-templates/index.md
Normal file
93
docs/admin/templates/extending-templates/index.md
Normal file
@ -0,0 +1,93 @@
|
|||||||
|
# Extending templates
|
||||||
|
|
||||||
|
There are a variety of Coder-native features to extend the configuration of your
|
||||||
|
development environments. Many of the following features are defined in your
|
||||||
|
templates using the
|
||||||
|
[Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs).
|
||||||
|
The provider docs will provide code examples for usage; alternatively, you can
|
||||||
|
view our
|
||||||
|
[example templates](https://github.com/coder/coder/tree/main/examples/templates)
|
||||||
|
to get started.
|
||||||
|
|
||||||
|
## Workspace agents
|
||||||
|
|
||||||
|
For users to connect to a workspace, the template must include a
|
||||||
|
[`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent).
|
||||||
|
The associated agent will facilitate
|
||||||
|
[workspace connections](../../../user-guides/workspace-access/index.md) via SSH,
|
||||||
|
port forwarding, and IDEs. The agent may also display real-time
|
||||||
|
[workspace metadata](./agent-metadata.md) like resource usage.
|
||||||
|
|
||||||
|
```tf
|
||||||
|
resource "coder_agent" "dev" {
|
||||||
|
os = "linux"
|
||||||
|
arch = "amd64"
|
||||||
|
dir = "/workspace"
|
||||||
|
display_apps {
|
||||||
|
vscode = true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
You can also leverage [resource metadata](./resource-metadata.md) to display
|
||||||
|
static resource information from your template.
|
||||||
|
|
||||||
|
Templates must include some computational resource to start the agent. All
|
||||||
|
processes on the workspace are then spawned from the agent. It also provides all
|
||||||
|
information displayed in the dashboard's workspace view.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
Multiple agents may be used in a single template or even a single resource. Each
|
||||||
|
agent may have it's own apps, startup script, and metadata. This can be used to
|
||||||
|
associate multiple containers or VMs with a workspace.
|
||||||
|
|
||||||
|
## Resource persistence
|
||||||
|
|
||||||
|
The resources you define in a template may be _ephemeral_ or _persistent_.
|
||||||
|
Persistent resources stay provisioned when workspaces are stopped, where as
|
||||||
|
ephemeral resources are destroyed and recreated on restart. All resources are
|
||||||
|
destroyed when a workspace is deleted.
|
||||||
|
|
||||||
|
> You can read more about how resource behavior and workspace state in the
|
||||||
|
> [workspace lifecycle documentation](../../../user-guides/workspace-lifecycle.md).
|
||||||
|
|
||||||
|
Template resources follow the
|
||||||
|
[behavior of Terraform resources](https://developer.hashicorp.com/terraform/language/resources/behavior#how-terraform-applies-a-configuration)
|
||||||
|
and can be further configured using the
|
||||||
|
[lifecycle argument](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle).
|
||||||
|
|
||||||
|
A common configuration is a template whose only persistent resource is the home
|
||||||
|
directory. This allows the developer to retain their work while ensuring the
|
||||||
|
rest of their environment is consistently up-to-date on each workspace restart.
|
||||||
|
|
||||||
|
When a workspace is deleted, the Coder server essentially runs a
|
||||||
|
[terraform destroy](https://www.terraform.io/cli/commands/destroy) to remove all
|
||||||
|
resources associated with the workspace.
|
||||||
|
|
||||||
|
> Terraform's
|
||||||
|
> [prevent-destroy](https://www.terraform.io/language/meta-arguments/lifecycle#prevent_destroy)
|
||||||
|
> and
|
||||||
|
> [ignore-changes](https://www.terraform.io/language/meta-arguments/lifecycle#ignore_changes)
|
||||||
|
> meta-arguments can be used to prevent accidental data loss.
|
||||||
|
|
||||||
|
## Coder apps
|
||||||
|
|
||||||
|
Additional IDEs, documentation, or services can be associated to your workspace
|
||||||
|
using the
|
||||||
|
[`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app)
|
||||||
|
resource.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
Note that some apps are associated to the agent by default as
|
||||||
|
[`display_apps`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#nested-schema-for-display_apps)
|
||||||
|
and can be hidden directly in the
|
||||||
|
[`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent)
|
||||||
|
resource. You can arrange the display orientation of Coder apps in your template
|
||||||
|
using [resource ordering](./resource-ordering.md).
|
||||||
|
|
||||||
|
Check out our [module registry](https://registry.coder.com/modules) for
|
||||||
|
additional Coder apps from the team and our OSS community.
|
||||||
|
|
||||||
|
<children></children>
|
@ -8,7 +8,7 @@ You can store these modules externally from your Coder deployment, like in a git
|
|||||||
repository or a Terraform registry. This example shows how to reference a module
|
repository or a Terraform registry. This example shows how to reference a module
|
||||||
from your template:
|
from your template:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_workspace" "me" {}
|
data "coder_workspace" "me" {}
|
||||||
|
|
||||||
module "coder-base" {
|
module "coder-base" {
|
||||||
@ -82,7 +82,7 @@ to resolve modules via [Artifactory](https://jfrog.com/artifactory/).
|
|||||||
5. Create a file `.terraformrc` with following content and mount at
|
5. Create a file `.terraformrc` with following content and mount at
|
||||||
`/home/coder/.terraformrc` within the Coder provisioner.
|
`/home/coder/.terraformrc` within the Coder provisioner.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
provider_installation {
|
provider_installation {
|
||||||
direct {
|
direct {
|
||||||
exclude = ["registry.terraform.io/*/*"]
|
exclude = ["registry.terraform.io/*/*"]
|
||||||
@ -95,7 +95,7 @@ to resolve modules via [Artifactory](https://jfrog.com/artifactory/).
|
|||||||
|
|
||||||
6. Update module source as,
|
6. Update module source as,
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
module "module-name" {
|
module "module-name" {
|
||||||
source = "https://example.jfrog.io/tf__coder/module-name/coder"
|
source = "https://example.jfrog.io/tf__coder/module-name/coder"
|
||||||
version = "1.0.0"
|
version = "1.0.0"
|
||||||
@ -111,14 +111,16 @@ Based on the instructions
|
|||||||
|
|
||||||
#### Example template
|
#### Example template
|
||||||
|
|
||||||
We have an example template [here](../../examples/jfrog/remote/main.tf) that
|
We have an example template
|
||||||
uses our [JFrog Docker](../../examples/jfrog/docker/main.tf) template as the
|
[here](https://github.com/coder/coder/blob/main/examples/jfrog/remote/main.tf)
|
||||||
underlying module.
|
that uses our
|
||||||
|
[JFrog Docker](https://github.com/coder/coder/blob/main/examples/jfrog/docker/main.tf)
|
||||||
|
template as the underlying module.
|
||||||
|
|
||||||
### Private git repository
|
### Private git repository
|
||||||
|
|
||||||
If you are importing a module from a private git repository, the Coder server or
|
If you are importing a module from a private git repository, the Coder server or
|
||||||
[provisioner](../admin/provisioners.md) needs git credentials. Since this token
|
[provisioner](../../provisioners.md) needs git credentials. Since this token
|
||||||
will only be used for cloning your repositories with modules, it is best to
|
will only be used for cloning your repositories with modules, it is best to
|
||||||
create a token with access limited to the repository and no extra permissions.
|
create a token with access limited to the repository and no extra permissions.
|
||||||
In GitHub, you can generate a
|
In GitHub, you can generate a
|
||||||
@ -188,12 +190,9 @@ coder:
|
|||||||
readOnly: true
|
readOnly: true
|
||||||
```
|
```
|
||||||
|
|
||||||
### Next up
|
### Next steps
|
||||||
|
|
||||||
Learn more about
|
- JFrog's
|
||||||
|
[Terraform Registry support](https://jfrog.com/help/r/jfrog-artifactory-documentation/terraform-registry)
|
||||||
- JFrog's Terraform Registry support
|
- [Configuring the JFrog toolchain inside a workspace](../../integrations/jfrog-artifactory.md)
|
||||||
[here](https://jfrog.com/help/r/jfrog-artifactory-documentation/terraform-registry).
|
- [Coder Module Registry](https://registry.coder.com/modules)
|
||||||
- Configuring the JFrog toolchain inside a workspace
|
|
||||||
[here](../guides/artifactory-integration.md).
|
|
||||||
- Coder Module Registry [here](https://registry.coder.com/modules)
|
|
@ -4,7 +4,7 @@ A template can prompt the user for additional information when creating
|
|||||||
workspaces with
|
workspaces with
|
||||||
[_parameters_](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter).
|
[_parameters_](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter).
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
The user can set parameters in the dashboard UI and CLI.
|
The user can set parameters in the dashboard UI and CLI.
|
||||||
|
|
||||||
@ -14,7 +14,7 @@ parameters like instance size, geographical location, repository URL, etc.
|
|||||||
|
|
||||||
This example lets a developer choose a Docker host for the workspace:
|
This example lets a developer choose a Docker host for the workspace:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_parameter" "docker_host" {
|
data "coder_parameter" "docker_host" {
|
||||||
name = "Region"
|
name = "Region"
|
||||||
description = "Which region would you like to deploy to?"
|
description = "Which region would you like to deploy to?"
|
||||||
@ -44,7 +44,7 @@ data "coder_parameter" "docker_host" {
|
|||||||
|
|
||||||
From there, a template can refer to a parameter's value:
|
From there, a template can refer to a parameter's value:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
provider "docker" {
|
provider "docker" {
|
||||||
host = data.coder_parameter.docker_host.value
|
host = data.coder_parameter.docker_host.value
|
||||||
}
|
}
|
||||||
@ -56,7 +56,7 @@ A Coder parameter can have one of these types:
|
|||||||
|
|
||||||
- `string`
|
- `string`
|
||||||
- `bool`
|
- `bool`
|
||||||
- `number`.
|
- `number`
|
||||||
- `list(string)`
|
- `list(string)`
|
||||||
|
|
||||||
To specify a default value for a parameter with the `list(string)` type, use a
|
To specify a default value for a parameter with the `list(string)` type, use a
|
||||||
@ -64,7 +64,7 @@ JSON array and the Terraform
|
|||||||
[jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode)
|
[jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode)
|
||||||
function. For example:
|
function. For example:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_parameter" "security_groups" {
|
data "coder_parameter" "security_groups" {
|
||||||
name = "Security groups"
|
name = "Security groups"
|
||||||
icon = "/icon/aws.png"
|
icon = "/icon/aws.png"
|
||||||
@ -83,7 +83,7 @@ data "coder_parameter" "security_groups" {
|
|||||||
|
|
||||||
A `string` parameter can provide a set of options to limit the user's choices:
|
A `string` parameter can provide a set of options to limit the user's choices:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_parameter" "docker_host" {
|
data "coder_parameter" "docker_host" {
|
||||||
name = "Region"
|
name = "Region"
|
||||||
description = "Which region would you like to deploy to?"
|
description = "Which region would you like to deploy to?"
|
||||||
@ -145,7 +145,7 @@ Example:
|
|||||||
A parameter is _required_ if it doesn't have the `default` property. The user
|
A parameter is _required_ if it doesn't have the `default` property. The user
|
||||||
**must** provide a value to this parameter before creating a workspace:
|
**must** provide a value to this parameter before creating a workspace:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_parameter" "account_name" {
|
data "coder_parameter" "account_name" {
|
||||||
name = "Account name"
|
name = "Account name"
|
||||||
description = "Cloud account name"
|
description = "Cloud account name"
|
||||||
@ -156,7 +156,7 @@ data "coder_parameter" "account_name" {
|
|||||||
If a parameter contains the `default` property, Coder will use this value if the
|
If a parameter contains the `default` property, Coder will use this value if the
|
||||||
user does not specify any:
|
user does not specify any:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_parameter" "base_image" {
|
data "coder_parameter" "base_image" {
|
||||||
name = "Base image"
|
name = "Base image"
|
||||||
description = "Base machine image to download"
|
description = "Base machine image to download"
|
||||||
@ -167,7 +167,7 @@ data "coder_parameter" "base_image" {
|
|||||||
Admins can also set the `default` property to an empty value so that the
|
Admins can also set the `default` property to an empty value so that the
|
||||||
parameter field can remain empty:
|
parameter field can remain empty:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_parameter" "dotfiles_url" {
|
data "coder_parameter" "dotfiles_url" {
|
||||||
name = "dotfiles URL"
|
name = "dotfiles URL"
|
||||||
description = "Git repository with dotfiles"
|
description = "Git repository with dotfiles"
|
||||||
@ -189,7 +189,7 @@ resources like volumes, regions, and so on.
|
|||||||
|
|
||||||
Example:
|
Example:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_parameter" "region" {
|
data "coder_parameter" "region" {
|
||||||
name = "Region"
|
name = "Region"
|
||||||
description = "Region where the workspace is hosted"
|
description = "Region where the workspace is hosted"
|
||||||
@ -212,7 +212,7 @@ project without using cache.
|
|||||||
Since these parameters are ephemeral in nature, subsequent builds proceed in the
|
Since these parameters are ephemeral in nature, subsequent builds proceed in the
|
||||||
standard manner:
|
standard manner:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_parameter" "force_rebuild" {
|
data "coder_parameter" "force_rebuild" {
|
||||||
name = "force_rebuild"
|
name = "force_rebuild"
|
||||||
type = "bool"
|
type = "bool"
|
||||||
@ -236,7 +236,7 @@ You can also specify its monotonicity as `increasing` or `decreasing` to verify
|
|||||||
the current and new values. Use the `monotonic` attribute for resources that
|
the current and new values. Use the `monotonic` attribute for resources that
|
||||||
can't be shrunk or grown without implications, like disk volume size.
|
can't be shrunk or grown without implications, like disk volume size.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_parameter" "instances" {
|
data "coder_parameter" "instances" {
|
||||||
name = "Instances"
|
name = "Instances"
|
||||||
type = "number"
|
type = "number"
|
||||||
@ -253,7 +253,7 @@ It is possible to override the default `error` message for a `number` parameter,
|
|||||||
along with its associated `min` and/or `max` properties. The following message
|
along with its associated `min` and/or `max` properties. The following message
|
||||||
placeholders are available `{min}`, `{max}`, and `{value}`.
|
placeholders are available `{min}`, `{max}`, and `{value}`.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_parameter" "instances" {
|
data "coder_parameter" "instances" {
|
||||||
name = "Instances"
|
name = "Instances"
|
||||||
type = "number"
|
type = "number"
|
||||||
@ -276,7 +276,7 @@ validations such as `monotonic`.
|
|||||||
You can validate a `string` parameter to match a regular expression. The `regex`
|
You can validate a `string` parameter to match a regular expression. The `regex`
|
||||||
property requires a corresponding `error` property.
|
property requires a corresponding `error` property.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_parameter" "project_id" {
|
data "coder_parameter" "project_id" {
|
||||||
name = "Project ID"
|
name = "Project ID"
|
||||||
description = "Alpha-numeric project ID"
|
description = "Alpha-numeric project ID"
|
@ -16,8 +16,8 @@ monitoring stack, such as CloudWatch, for further analysis or long-term storage.
|
|||||||
Please note that these logs are not recorded or captured by the Coder
|
Please note that these logs are not recorded or captured by the Coder
|
||||||
organization in any way, shape, or form.
|
organization in any way, shape, or form.
|
||||||
|
|
||||||
> This is an [Enterprise](https://coder.com/docs/v2/latest/enterprise) feature.
|
> This is an [Premium or Enterprise](https://coder.com/pricing) feature. To
|
||||||
> To learn more about Coder Enterprise, please
|
> learn more about Coder Enterprise, please
|
||||||
> [contact sales](https://coder.com/contact).
|
> [contact sales](https://coder.com/contact).
|
||||||
|
|
||||||
## How this works
|
## How this works
|
@ -8,10 +8,10 @@ You can use `coder_metadata` to show Terraform resource attributes like these:
|
|||||||
|
|
||||||
- Compute resources
|
- Compute resources
|
||||||
- IP addresses
|
- IP addresses
|
||||||
- [Secrets](../secrets.md#displaying-secrets)
|
- [Secrets](../../security/secrets.md#displaying-secrets)
|
||||||
- Important file paths
|
- Important file paths
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
<blockquote class="info">
|
<blockquote class="info">
|
||||||
Coder automatically generates the <code>type</code> metadata.
|
Coder automatically generates the <code>type</code> metadata.
|
||||||
@ -25,7 +25,7 @@ You can also present automatically updating, dynamic values with
|
|||||||
Expose the disk size, deployment name, and persistent directory in a Kubernetes
|
Expose the disk size, deployment name, and persistent directory in a Kubernetes
|
||||||
template with:
|
template with:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "kubernetes_persistent_volume_claim" "root" {
|
resource "kubernetes_persistent_volume_claim" "root" {
|
||||||
...
|
...
|
||||||
}
|
}
|
||||||
@ -64,7 +64,7 @@ Some resources don't need to be exposed in the dashboard's UI. This helps keep
|
|||||||
the workspace view clean for developers. To hide a resource, use the `hide`
|
the workspace view clean for developers. To hide a resource, use the `hide`
|
||||||
attribute:
|
attribute:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "coder_metadata" "hide_serviceaccount" {
|
resource "coder_metadata" "hide_serviceaccount" {
|
||||||
count = data.coder_workspace.me.start_count
|
count = data.coder_workspace.me.start_count
|
||||||
resource_id = kubernetes_service_account.user_data.id
|
resource_id = kubernetes_service_account.user_data.id
|
||||||
@ -81,7 +81,7 @@ resource "coder_metadata" "hide_serviceaccount" {
|
|||||||
To use custom icons for your resource metadata, use the `icon` attribute. It
|
To use custom icons for your resource metadata, use the `icon` attribute. It
|
||||||
must be a valid path or URL.
|
must be a valid path or URL.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "coder_metadata" "resource_with_icon" {
|
resource "coder_metadata" "resource_with_icon" {
|
||||||
count = data.coder_workspace.me.start_count
|
count = data.coder_workspace.me.start_count
|
||||||
resource_id = kubernetes_service_account.user_data.id
|
resource_id = kubernetes_service_account.user_data.id
|
||||||
@ -107,5 +107,5 @@ how to use the builtin icons [here](./icons.md).
|
|||||||
|
|
||||||
## Up next
|
## Up next
|
||||||
|
|
||||||
- [Secrets](../secrets.md)
|
- [Secrets](../../security/secrets.md)
|
||||||
- [Agent metadata](./agent-metadata.md)
|
- [Agent metadata](./agent-metadata.md)
|
@ -16,7 +16,7 @@ The `order` property of `coder_parameter` resource allows specifying the order
|
|||||||
of parameters in UI forms. In the below example, `project_id` will appear
|
of parameters in UI forms. In the below example, `project_id` will appear
|
||||||
_before_ `account_id`:
|
_before_ `account_id`:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_parameter" "project_id" {
|
data "coder_parameter" "project_id" {
|
||||||
name = "project_id"
|
name = "project_id"
|
||||||
display_name = "Project ID"
|
display_name = "Project ID"
|
||||||
@ -37,7 +37,7 @@ data "coder_parameter" "account_id" {
|
|||||||
Agent resources within the UI left pane are sorted based on the `order`
|
Agent resources within the UI left pane are sorted based on the `order`
|
||||||
property, followed by `name`, ensuring a consistent and intuitive arrangement.
|
property, followed by `name`, ensuring a consistent and intuitive arrangement.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "coder_agent" "primary" {
|
resource "coder_agent" "primary" {
|
||||||
...
|
...
|
||||||
|
|
||||||
@ -59,7 +59,7 @@ The `coder_agent` exposes metadata to present operational metrics in the UI.
|
|||||||
Metrics defined with Terraform `metadata` blocks can be ordered using additional
|
Metrics defined with Terraform `metadata` blocks can be ordered using additional
|
||||||
`order` property; otherwise, they are sorted by `key`.
|
`order` property; otherwise, they are sorted by `key`.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "coder_agent" "main" {
|
resource "coder_agent" "main" {
|
||||||
...
|
...
|
||||||
|
|
||||||
@ -107,7 +107,7 @@ workspace view.
|
|||||||
Only template defined applications can be arranged. _VS Code_ or _Terminal_
|
Only template defined applications can be arranged. _VS Code_ or _Terminal_
|
||||||
buttons are static.
|
buttons are static.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "coder_app" "code-server" {
|
resource "coder_app" "code-server" {
|
||||||
agent_id = coder_agent.main.id
|
agent_id = coder_agent.main.id
|
||||||
slug = "code-server"
|
slug = "code-server"
|
||||||
@ -135,7 +135,7 @@ The options for Coder parameters maintain the same order as in the file
|
|||||||
structure. This simplifies management and ensures consistency between
|
structure. This simplifies management and ensures consistency between
|
||||||
configuration files and UI presentation.
|
configuration files and UI presentation.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_parameter" "database_region" {
|
data "coder_parameter" "database_region" {
|
||||||
name = "database_region"
|
name = "database_region"
|
||||||
display_name = "Database Region"
|
display_name = "Database Region"
|
||||||
@ -166,7 +166,7 @@ In cases where multiple item properties exist, the order is inherited from the
|
|||||||
file, facilitating seamless integration between a Coder template and UI
|
file, facilitating seamless integration between a Coder template and UI
|
||||||
presentation.
|
presentation.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "coder_metadata" "attached_volumes" {
|
resource "coder_metadata" "attached_volumes" {
|
||||||
resource_id = docker_image.main.id
|
resource_id = docker_image.main.id
|
||||||
|
|
@ -24,7 +24,7 @@ meta-argument.
|
|||||||
In this example, Coder will provision or tear down the `docker_container`
|
In this example, Coder will provision or tear down the `docker_container`
|
||||||
resource:
|
resource:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_workspace" "me" {
|
data "coder_workspace" "me" {
|
||||||
}
|
}
|
||||||
|
|
||||||
@ -39,7 +39,7 @@ resource "docker_container" "workspace" {
|
|||||||
|
|
||||||
Take this example resource:
|
Take this example resource:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_workspace" "me" {
|
data "coder_workspace" "me" {
|
||||||
}
|
}
|
||||||
|
|
||||||
@ -57,7 +57,7 @@ To prevent this, use immutable IDs:
|
|||||||
- `coder_workspace.me.owner_id`
|
- `coder_workspace.me.owner_id`
|
||||||
- `coder_workspace.me.id`
|
- `coder_workspace.me.id`
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_workspace" "me" {
|
data "coder_workspace" "me" {
|
||||||
}
|
}
|
||||||
|
|
||||||
@ -78,7 +78,7 @@ You can prevent Terraform from recreating a resource under any circumstance by
|
|||||||
setting the
|
setting the
|
||||||
[`ignore_changes = all` directive in the `lifecycle` block](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#ignore_changes).
|
[`ignore_changes = all` directive in the `lifecycle` block](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#ignore_changes).
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_workspace" "me" {
|
data "coder_workspace" "me" {
|
||||||
}
|
}
|
||||||
|
|
@ -6,7 +6,7 @@ construction of customizable templates. Unlike parameters, which are primarily
|
|||||||
for workspace customization, template variables remain under the control of the
|
for workspace customization, template variables remain under the control of the
|
||||||
template author, ensuring workspace users cannot modify them.
|
template author, ensuring workspace users cannot modify them.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
variable "CLOUD_API_KEY" {
|
variable "CLOUD_API_KEY" {
|
||||||
type = string
|
type = string
|
||||||
description = "API key for the service"
|
description = "API key for the service"
|
||||||
@ -53,7 +53,7 @@ variables, you can employ a straightforward solution:
|
|||||||
|
|
||||||
1. Create a `terraform.tfvars` file in in the template directory:
|
1. Create a `terraform.tfvars` file in in the template directory:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
coder_image = newimage:tag
|
coder_image = newimage:tag
|
||||||
```
|
```
|
||||||
|
|
@ -1,22 +1,11 @@
|
|||||||
# Web IDEs
|
# Web IDEs
|
||||||
|
|
||||||
By default, Coder workspaces allow connections via:
|
|
||||||
|
|
||||||
- Web terminal
|
|
||||||
- SSH (plus any [SSH-compatible IDE](../ides.md))
|
|
||||||
|
|
||||||
It's common to also let developers to connect via web IDEs for uses cases like
|
|
||||||
zero trust networks, data science, contractors, and infrequent code
|
|
||||||
contributors.
|
|
||||||
|
|
||||||

|
|
||||||
|
|
||||||
In Coder, web IDEs are defined as
|
In Coder, web IDEs are defined as
|
||||||
[coder_app](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app)
|
[coder_app](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app)
|
||||||
resources in the template. With our generic model, any web application can be
|
resources in the template. With our generic model, any web application can be
|
||||||
used as a Coder application. For example:
|
used as a Coder application. For example:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
# Add button to open Portainer in the workspace dashboard
|
# Add button to open Portainer in the workspace dashboard
|
||||||
# Note: Portainer must be already running in the workspace
|
# Note: Portainer must be already running in the workspace
|
||||||
resource "coder_app" "portainer" {
|
resource "coder_app" "portainer" {
|
||||||
@ -34,33 +23,6 @@ resource "coder_app" "portainer" {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## External URLs
|
|
||||||
|
|
||||||
Any URL external to the Coder deployment is accessible as a `coder_app`. e.g.,
|
|
||||||
Dropbox, Slack, Discord, GitHub
|
|
||||||
|
|
||||||
```hcl
|
|
||||||
resource "coder_app" "pubslack" {
|
|
||||||
agent_id = coder_agent.coder.id
|
|
||||||
display_name = "Coder Public Slack"
|
|
||||||
slug = "pubslack"
|
|
||||||
url = "https://coder-com.slack.com/"
|
|
||||||
icon = "/icon/slack.svg"
|
|
||||||
external = true
|
|
||||||
}
|
|
||||||
|
|
||||||
resource "coder_app" "discord" {
|
|
||||||
agent_id = coder_agent.coder.id
|
|
||||||
display_name = "Coder Discord"
|
|
||||||
slug = "discord"
|
|
||||||
url = "https://discord.com/invite/coder"
|
|
||||||
icon = "/icon/discord.svg"
|
|
||||||
external = true
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||

|
|
||||||
|
|
||||||
## code-server
|
## code-server
|
||||||
|
|
||||||
[code-server](https://github.com/coder/coder) is our supported method of running
|
[code-server](https://github.com/coder/coder) is our supported method of running
|
||||||
@ -73,7 +35,7 @@ cd your-template/
|
|||||||
vim main.tf
|
vim main.tf
|
||||||
```
|
```
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "coder_agent" "main" {
|
resource "coder_agent" "main" {
|
||||||
arch = "amd64"
|
arch = "amd64"
|
||||||
os = "linux"
|
os = "linux"
|
||||||
@ -113,7 +75,7 @@ RUN code-server --install-extension eamodio.gitlens
|
|||||||
You'll also need to specify a `coder_app` resource related to the agent. This is
|
You'll also need to specify a `coder_app` resource related to the agent. This is
|
||||||
how code-server is displayed on the workspace page.
|
how code-server is displayed on the workspace page.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "coder_app" "code-server" {
|
resource "coder_app" "code-server" {
|
||||||
agent_id = coder_agent.main.id
|
agent_id = coder_agent.main.id
|
||||||
slug = "code-server"
|
slug = "code-server"
|
||||||
@ -131,7 +93,7 @@ resource "coder_app" "code-server" {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
## VS Code Web
|
## VS Code Web
|
||||||
|
|
||||||
@ -142,7 +104,7 @@ command. To add VS Code web as a web IDE, you have two options.
|
|||||||
[vscode-web module](https://registry.coder.com/modules/vscode-web) from the
|
[vscode-web module](https://registry.coder.com/modules/vscode-web) from the
|
||||||
coder registry.
|
coder registry.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
module "vscode-web" {
|
module "vscode-web" {
|
||||||
source = "registry.coder.com/modules/vscode-web/coder"
|
source = "registry.coder.com/modules/vscode-web/coder"
|
||||||
version = "1.0.14"
|
version = "1.0.14"
|
||||||
@ -154,7 +116,7 @@ command. To add VS Code web as a web IDE, you have two options.
|
|||||||
2. Install and start in your `startup_script` and create a corresponding
|
2. Install and start in your `startup_script` and create a corresponding
|
||||||
`coder_app`
|
`coder_app`
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "coder_agent" "main" {
|
resource "coder_agent" "main" {
|
||||||
arch = "amd64"
|
arch = "amd64"
|
||||||
os = "linux"
|
os = "linux"
|
||||||
@ -175,7 +137,7 @@ command. To add VS Code web as a web IDE, you have two options.
|
|||||||
|
|
||||||
You also need to add a `coder_app` resource for this.
|
You also need to add a `coder_app` resource for this.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
# VS Code Web
|
# VS Code Web
|
||||||
resource "coder_app" "vscode-web" {
|
resource "coder_app" "vscode-web" {
|
||||||
agent_id = coder_agent.coder.id
|
agent_id = coder_agent.coder.id
|
||||||
@ -188,12 +150,28 @@ command. To add VS Code web as a web IDE, you have two options.
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Jupyter Notebook
|
||||||
|
|
||||||
|
To use Jupyter Notebook in your workspace, you can install it by using the
|
||||||
|
[Jupyter Notebook module](https://registry.coder.com/modules/jupyter-notebook)
|
||||||
|
from the Coder registry:
|
||||||
|
|
||||||
|
```tf
|
||||||
|
module "jupyter-notebook" {
|
||||||
|
source = "registry.coder.com/modules/jupyter-notebook/coder"
|
||||||
|
version = "1.0.19"
|
||||||
|
agent_id = coder_agent.example.id
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
## JupyterLab
|
## JupyterLab
|
||||||
|
|
||||||
Configure your agent and `coder_app` like so to use Jupyter. Notice the
|
Configure your agent and `coder_app` like so to use Jupyter. Notice the
|
||||||
`subdomain=true` configuration:
|
`subdomain=true` configuration:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_workspace" "me" {}
|
data "coder_workspace" "me" {}
|
||||||
|
|
||||||
resource "coder_agent" "coder" {
|
resource "coder_agent" "coder" {
|
||||||
@ -223,24 +201,31 @@ resource "coder_app" "jupyter" {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Or Alternatively, you can use the JupyterLab module from the Coder registry:
|
||||||
|
|
||||||
|
```tf
|
||||||
|
module "jupyter" {
|
||||||
|
source = "registry.coder.com/modules/jupyter-lab/coder"
|
||||||
|
version = "1.0.0"
|
||||||
|
agent_id = coder_agent.main.id
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
If you cannot enable a
|
If you cannot enable a
|
||||||
[wildcard subdomain](https://coder.com/docs/admin/configure#wildcard-access-url),
|
[wildcard subdomain](../../../admin/setup/index.md#wildcard-access-url), you can
|
||||||
you can configure the template to run Jupyter on a path. There is however
|
configure the template to run Jupyter on a path. There is however
|
||||||
[security risk](https://coder.com/docs/cli/server#--dangerous-allow-path-app-sharing)
|
[security risk](../../../reference/cli/server.md#--dangerous-allow-path-app-sharing)
|
||||||
running an app on a path and the template code is more complicated with coder
|
running an app on a path and the template code is more complicated with coder
|
||||||
value substitution to recreate the path structure.
|
value substitution to recreate the path structure.
|
||||||
|
|
||||||
[This](https://github.com/sharkymark/v2-templates/tree/main/src/pod-with-jupyter-path)
|

|
||||||
is a community template example.
|
|
||||||
|
|
||||||

|
|
||||||
|
|
||||||
## RStudio
|
## RStudio
|
||||||
|
|
||||||
Configure your agent and `coder_app` like so to use RStudio. Notice the
|
Configure your agent and `coder_app` like so to use RStudio. Notice the
|
||||||
`subdomain=true` configuration:
|
`subdomain=true` configuration:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "coder_agent" "coder" {
|
resource "coder_agent" "coder" {
|
||||||
os = "linux"
|
os = "linux"
|
||||||
arch = "amd64"
|
arch = "amd64"
|
||||||
@ -252,7 +237,6 @@ resource "coder_agent" "coder" {
|
|||||||
EOT
|
EOT
|
||||||
}
|
}
|
||||||
|
|
||||||
# rstudio
|
|
||||||
resource "coder_app" "rstudio" {
|
resource "coder_app" "rstudio" {
|
||||||
agent_id = coder_agent.coder.id
|
agent_id = coder_agent.coder.id
|
||||||
slug = "rstudio"
|
slug = "rstudio"
|
||||||
@ -274,21 +258,21 @@ If you cannot enable a
|
|||||||
[wildcard subdomain](https://coder.com/docs/admin/configure#wildcard-access-url),
|
[wildcard subdomain](https://coder.com/docs/admin/configure#wildcard-access-url),
|
||||||
you can configure the template to run RStudio on a path using an NGINX reverse
|
you can configure the template to run RStudio on a path using an NGINX reverse
|
||||||
proxy in the template. There is however
|
proxy in the template. There is however
|
||||||
[security risk](https://coder.com/docs/cli/server#--dangerous-allow-path-app-sharing)
|
[security risk](https://coder.com/docs/reference/cli/server#--dangerous-allow-path-app-sharing)
|
||||||
running an app on a path and the template code is more complicated with coder
|
running an app on a path and the template code is more complicated with coder
|
||||||
value substitution to recreate the path structure.
|
value substitution to recreate the path structure.
|
||||||
|
|
||||||
[This](https://github.com/sempie/coder-templates/tree/main/rstudio) is a
|
[This](https://github.com/sempie/coder-templates/tree/main/rstudio) is a
|
||||||
community template example.
|
community template example.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
## Airflow
|
## Airflow
|
||||||
|
|
||||||
Configure your agent and `coder_app` like so to use Airflow. Notice the
|
Configure your agent and `coder_app` like so to use Airflow. Notice the
|
||||||
`subdomain=true` configuration:
|
`subdomain=true` configuration:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "coder_agent" "coder" {
|
resource "coder_agent" "coder" {
|
||||||
os = "linux"
|
os = "linux"
|
||||||
arch = "amd64"
|
arch = "amd64"
|
||||||
@ -305,7 +289,7 @@ resource "coder_app" "airflow" {
|
|||||||
agent_id = coder_agent.coder.id
|
agent_id = coder_agent.coder.id
|
||||||
slug = "airflow"
|
slug = "airflow"
|
||||||
display_name = "Airflow"
|
display_name = "Airflow"
|
||||||
icon = "https://upload.wikimedia.org/wikipedia/commons/d/de/AirflowLogo.png"
|
icon = "/icon/airflow.svg"
|
||||||
url = "http://localhost:8080"
|
url = "http://localhost:8080"
|
||||||
subdomain = true
|
subdomain = true
|
||||||
share = "owner"
|
share = "owner"
|
||||||
@ -318,13 +302,28 @@ resource "coder_app" "airflow" {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||

|
or use the [Airflow module](https://registry.coder.com/modules/apache-airflow)
|
||||||
|
from the Coder registry:
|
||||||
|
|
||||||
|
```tf
|
||||||
|
module "airflow" {
|
||||||
|
source = "registry.coder.com/modules/airflow/coder"
|
||||||
|
version = "1.0.13"
|
||||||
|
agent_id = coder_agent.main.id
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
## File Browser
|
## File Browser
|
||||||
|
|
||||||
|
To access the contents of a workspace directory in a browser, you can use File
|
||||||
|
Browser. File Browser is a lightweight file manager that allows you to view and
|
||||||
|
manipulate files in a web browser.
|
||||||
|
|
||||||
Show and manipulate the contents of the `/home/coder` directory in a browser.
|
Show and manipulate the contents of the `/home/coder` directory in a browser.
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
resource "coder_agent" "coder" {
|
resource "coder_agent" "coder" {
|
||||||
os = "linux"
|
os = "linux"
|
||||||
arch = "amd64"
|
arch = "amd64"
|
||||||
@ -355,11 +354,23 @@ resource "coder_app" "filebrowser" {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||

|
Or alternatively, you can use the
|
||||||
|
[`filebrowser`](https://registry.coder.com/modules/filebrowser) module from the
|
||||||
|
Coder registry:
|
||||||
|
|
||||||
|
```tf
|
||||||
|
module "filebrowser" {
|
||||||
|
source = "registry.coder.com/modules/filebrowser/coder"
|
||||||
|
version = "1.0.8"
|
||||||
|
agent_id = coder_agent.main.id
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
## SSH Fallback
|
## SSH Fallback
|
||||||
|
|
||||||
If you prefer to run web IDEs in localhost, you can port forward using
|
If you prefer to run web IDEs in localhost, you can port forward using
|
||||||
[SSH](../ides.md#ssh) or the Coder CLI `port-forward` sub-command. Some web IDEs
|
[SSH](../../../user-guides/workspace-access/index.md#ssh) or the Coder CLI
|
||||||
may not support URL base path adjustment so port forwarding is the only
|
`port-forward` sub-command. Some web IDEs may not support URL base path
|
||||||
approach.
|
adjustment so port forwarding is the only approach.
|
@ -14,7 +14,7 @@ can enable dynamic tag selection and modify static template tags.
|
|||||||
Here is a sample `coder_workspace_tags` data resource with a few workspace tags
|
Here is a sample `coder_workspace_tags` data resource with a few workspace tags
|
||||||
specified:
|
specified:
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
data "coder_workspace_tags" "custom_workspace_tags" {
|
data "coder_workspace_tags" "custom_workspace_tags" {
|
||||||
tags = {
|
tags = {
|
||||||
"zone" = "developers"
|
"zone" = "developers"
|
62
docs/admin/templates/index.md
Normal file
62
docs/admin/templates/index.md
Normal file
@ -0,0 +1,62 @@
|
|||||||
|
# Template
|
||||||
|
|
||||||
|
Templates are written in
|
||||||
|
[Terraform](https://developer.hashicorp.com/terraform/intro) and define the
|
||||||
|
underlying infrastructure that all Coder workspaces run on.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
<small>The "Starter Templates" page within the Coder dashboard.</small>
|
||||||
|
|
||||||
|
## Learn the concepts
|
||||||
|
|
||||||
|
While templates are written in standard Terraform, it's important to learn the
|
||||||
|
Coder-specific concepts behind templates. The best way to learn the concepts is
|
||||||
|
by
|
||||||
|
[creating a basic template from scratch](../../tutorials/template-from-scratch.md).
|
||||||
|
If you are unfamiliar with Terraform, see
|
||||||
|
[Hashicorp's Tutorials](https://developer.hashicorp.com/terraform/tutorials) for
|
||||||
|
common cloud providers.
|
||||||
|
|
||||||
|
## Starter templates
|
||||||
|
|
||||||
|
After learning the basics, use starter templates to import a template with
|
||||||
|
sensible defaults for popular platforms (e.g. AWS, Kubernetes, Docker, etc).
|
||||||
|
Docs:
|
||||||
|
[Create a template from a starter template](./creating-templates.md#from-a-starter-template).
|
||||||
|
|
||||||
|
## Extending templates
|
||||||
|
|
||||||
|
It's often necessary to extend the template to make it generally useful to end
|
||||||
|
users. Common modifications are:
|
||||||
|
|
||||||
|
- Your image(s) (e.g. a Docker image with languages and tools installed). Docs:
|
||||||
|
[Image management](./managing-templates/image-management.md).
|
||||||
|
- Additional parameters (e.g. disk size, instance type, or region). Docs:
|
||||||
|
[Template parameters](./extending-templates/parameters.md).
|
||||||
|
- Additional IDEs (e.g. JetBrains) or features (e.g. dotfiles, RDP). Docs:
|
||||||
|
[Adding IDEs and features](./extending-templates/index.md).
|
||||||
|
|
||||||
|
Learn more about the various ways you can
|
||||||
|
[extend your templates](./extending-templates/index.md).
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
We recommend starting with a universal template that can be used for basic
|
||||||
|
tasks. As your Coder deployment grows, you can create more templates to meet the
|
||||||
|
needs of different teams.
|
||||||
|
|
||||||
|
- [Image management](./managing-templates/image-management.md): Learn how to
|
||||||
|
create and publish images for use within Coder workspaces & templates.
|
||||||
|
- [Dev Container support](./managing-templates/devcontainers.md): Enable dev
|
||||||
|
containers to allow teams to bring their own tools into Coder workspaces.
|
||||||
|
- [Template hardening](./extending-templates/resource-persistence.md#-bulletproofing):
|
||||||
|
Configure your template to prevent certain resources from being destroyed
|
||||||
|
(e.g. user disks).
|
||||||
|
- [Manage templates with Ci/Cd pipelines](./managing-templates/change-management.md):
|
||||||
|
Learn how to source control your templates and use GitOps to ensure template
|
||||||
|
changes are reviewed and tested.
|
||||||
|
- [Permissions and Policies](./template-permissions.md): Control who may access
|
||||||
|
and modify your template.
|
||||||
|
|
||||||
|
<children></children>
|
@ -5,7 +5,7 @@ automating the creation of new versions in CI/CD pipelines.
|
|||||||
|
|
||||||
These pipelines will require tokens for your deployment. To cap token lifetime
|
These pipelines will require tokens for your deployment. To cap token lifetime
|
||||||
on creation,
|
on creation,
|
||||||
[configure Coder server to set a shorter max token lifetime](../reference/cli/server.md#--max-token-lifetime).
|
[configure Coder server to set a shorter max token lifetime](../../../reference/cli/server.md#--max-token-lifetime).
|
||||||
|
|
||||||
## coderd Terraform Provider
|
## coderd Terraform Provider
|
||||||
|
|
||||||
@ -16,7 +16,7 @@ pipelines. To run the provider in a CI/CD pipeline, and to prevent drift, you'll
|
|||||||
need to store the Terraform state
|
need to store the Terraform state
|
||||||
[remotely](https://developer.hashicorp.com/terraform/language/backend).
|
[remotely](https://developer.hashicorp.com/terraform/language/backend).
|
||||||
|
|
||||||
```hcl
|
```tf
|
||||||
terraform {
|
terraform {
|
||||||
required_providers {
|
required_providers {
|
||||||
coderd = {
|
coderd = {
|
||||||
@ -62,8 +62,8 @@ For an example, see how we push our development image and template
|
|||||||
|
|
||||||
## Coder CLI
|
## Coder CLI
|
||||||
|
|
||||||
You can also [install Coder](../install/) to automate pushing new template
|
You can also [install Coder](../../../install/cli.md) to automate pushing new
|
||||||
versions in CI/CD pipelines.
|
template versions in CI/CD pipelines.
|
||||||
|
|
||||||
```console
|
```console
|
||||||
# Install the Coder CLI
|
# Install the Coder CLI
|
||||||
@ -87,3 +87,9 @@ coder templates push --yes $CODER_TEMPLATE_NAME \
|
|||||||
--directory $CODER_TEMPLATE_DIR \
|
--directory $CODER_TEMPLATE_DIR \
|
||||||
--name=$CODER_TEMPLATE_VERSION # Version name is optional
|
--name=$CODER_TEMPLATE_VERSION # Version name is optional
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Next steps
|
||||||
|
|
||||||
|
- [Coder CLI Reference](../../../reference/cli/templates.md)
|
||||||
|
- [Coderd Terraform Provider Reference](https://registry.terraform.io/providers/coder/coderd/latest/docs)
|
||||||
|
- [Coderd API Reference](../../../reference/index.md)
|
@ -91,8 +91,8 @@ inside a folder containing the Terraform source code for a given template.
|
|||||||
|
|
||||||
This will create a new file named `.terraform.lock.hcl` in the current
|
This will create a new file named `.terraform.lock.hcl` in the current
|
||||||
directory. When you next run
|
directory. When you next run
|
||||||
[`coder templates push`](../reference/cli/templates_push.md), the lock file will
|
[`coder templates push`](../../../reference/cli/templates_push.md), the lock
|
||||||
be stored alongside with the other template source code.
|
file will be stored alongside with the other template source code.
|
||||||
|
|
||||||
> Note: Terraform best practices also recommend checking in your
|
> Note: Terraform best practices also recommend checking in your
|
||||||
> `.terraform.lock.hcl` into Git or other VCS.
|
> `.terraform.lock.hcl` into Git or other VCS.
|
@ -20,10 +20,10 @@ Coder:
|
|||||||
## How it works
|
## How it works
|
||||||
|
|
||||||
A Coder admin adds a devcontainer-compatible template to Coder (envbuilder).
|
A Coder admin adds a devcontainer-compatible template to Coder (envbuilder).
|
||||||
Then developers enter their repository URL as a [parameter](./parameters.md)
|
Then developers enter their repository URL as a
|
||||||
when they create their workspace.
|
[parameter](../extending-templates/parameters.md) when they create their
|
||||||
[Envbuilder](https://github.com/coder/envbuilder) clones the repo and builds a
|
workspace. [Envbuilder](https://github.com/coder/envbuilder) clones the repo and
|
||||||
container from the `devcontainer.json` specified in the repo.
|
builds a container from the `devcontainer.json` specified in the repo.
|
||||||
|
|
||||||
When using the [Envbuilder Terraform provider](#provider), a previously built
|
When using the [Envbuilder Terraform provider](#provider), a previously built
|
||||||
and cached image can be re-used directly, allowing instantaneous dev container
|
and cached image can be re-used directly, allowing instantaneous dev container
|
||||||
@ -47,10 +47,10 @@ iterate on their development environments.
|
|||||||
Docker socket from the VM inside the container to enable Docker inside the
|
Docker socket from the VM inside the container to enable Docker inside the
|
||||||
workspace.
|
workspace.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
Your template can prompt the user for a repo URL with
|
Your template can prompt the user for a repo URL with
|
||||||
[Parameters](./parameters.md).
|
[Parameters](../extending-templates/parameters.md).
|
||||||
|
|
||||||
## Authentication
|
## Authentication
|
||||||
|
|
73
docs/admin/templates/managing-templates/image-management.md
Normal file
73
docs/admin/templates/managing-templates/image-management.md
Normal file
@ -0,0 +1,73 @@
|
|||||||
|
# Image Management
|
||||||
|
|
||||||
|
While Coder provides example
|
||||||
|
[base container images](https://github.com/coder/enterprise-images) for
|
||||||
|
workspaces, it's often best to create custom images that matches the needs of
|
||||||
|
your users. This document serves a guide to operational maturity with some best
|
||||||
|
practices around managing workspaces images for Coder.
|
||||||
|
|
||||||
|
1. Create a minimal base image
|
||||||
|
2. Create golden image(s) with standard tooling
|
||||||
|
3. Allow developers to bring their own images and customizations with Dev
|
||||||
|
Containers
|
||||||
|
|
||||||
|
> Note: An image is just one of the many properties defined within the template.
|
||||||
|
> Templates can pull images from a public image registry (e.g. Docker Hub) or an
|
||||||
|
> internal one., thanks to Terraform.
|
||||||
|
|
||||||
|
## Create a minimal base image
|
||||||
|
|
||||||
|
While you may not use this directly in Coder templates, it's useful to have a
|
||||||
|
minimal base image is a small image that contains only the necessary
|
||||||
|
dependencies to work in your network and work with Coder. Here are some things
|
||||||
|
to consider:
|
||||||
|
|
||||||
|
- `curl`, `wget`, or `busybox` is required to download and run
|
||||||
|
[the agent](https://github.com/coder/coder/blob/main/provisionersdk/scripts/bootstrap_linux.sh)
|
||||||
|
- `git` is recommended so developers can clone repositories
|
||||||
|
- If the Coder server is using a certificate from an internal certificate
|
||||||
|
authority (CA), you'll need to add or mount these into your image
|
||||||
|
- Other generic utilities that will be required by all users, such as `ssh`,
|
||||||
|
`docker`, `bash`, `jq`, and/or internal tooling
|
||||||
|
- Consider creating (and starting the container with) a non-root user
|
||||||
|
|
||||||
|
> See Coder's
|
||||||
|
> [example base image](https://github.com/coder/enterprise-images/tree/main/images/minimal)
|
||||||
|
> for reference.
|
||||||
|
|
||||||
|
## Create general-purpose golden image(s) with standard tooling
|
||||||
|
|
||||||
|
It's often practical to have a few golden images that contain standard tooling
|
||||||
|
for developers. These images should contain a number of languages (e.g. Python,
|
||||||
|
Java, TypeScript), IDEs (VS Code, JetBrains, PyCharm), and other tools (e.g.
|
||||||
|
`docker`). Unlike project-specific images (which are also important), general
|
||||||
|
purpose images are great for:
|
||||||
|
|
||||||
|
- **Scripting:** Developers may just want to hop in a Coder workspace to run
|
||||||
|
basic scripts or queries.
|
||||||
|
- **Day 1 Onboarding:** New developers can quickly get started with a familiar
|
||||||
|
environment without having to browse through (or create) an image
|
||||||
|
- **Basic Projects:** Developers can use these images for simple projects that
|
||||||
|
don't require any specific tooling outside of the standard libraries. As the
|
||||||
|
project gets more complex, its best to move to a project-specific image.
|
||||||
|
- **"Golden Path" Projects:** If your developer platform offers specific tech
|
||||||
|
stacks and types of projects, the golden image can be a good starting point
|
||||||
|
for those projects.
|
||||||
|
|
||||||
|
> This is often referred to as a "sandbox" or "kitchen sink" image. Since large
|
||||||
|
> multi-purpose container images can quickly become difficult to maintain, it's
|
||||||
|
> important to keep the number of general-purpose images to a minimum (2-3 in
|
||||||
|
> most cases) with a well-defined scope.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
- [Universal Dev Containers Image](https://github.com/devcontainers/images/tree/main/src/universal)
|
||||||
|
|
||||||
|
## Allow developers to bring their own images and customizations with Dev Containers
|
||||||
|
|
||||||
|
While golden images are great for general use cases, developers will often need
|
||||||
|
specific tooling for their projects. The [Dev Container](https://containers.dev)
|
||||||
|
specification allows developers to define their projects dependencies within a
|
||||||
|
`devcontainer.json` in their Git repository.
|
||||||
|
|
||||||
|
- [Learn how to integrate Dev Containers with Coder](./devcontainers.md)
|
95
docs/admin/templates/managing-templates/index.md
Normal file
95
docs/admin/templates/managing-templates/index.md
Normal file
@ -0,0 +1,95 @@
|
|||||||
|
# Working with templates
|
||||||
|
|
||||||
|
You create and edit Coder templates as [Terraform](../../../start/coder-tour.md)
|
||||||
|
configuration files (`.tf`) and any supporting files, like a README or
|
||||||
|
configuration files for other services.
|
||||||
|
|
||||||
|
## Who creates templates?
|
||||||
|
|
||||||
|
The [Template Admin](../../../admin/users/groups-roles.md#roles) role (and
|
||||||
|
above) can create templates. End users, like developers, create workspaces from
|
||||||
|
them. Templates can also be [managed with git](./change-management.md), allowing
|
||||||
|
any developer to propose changes to a template.
|
||||||
|
|
||||||
|
You can give different users and groups access to templates with
|
||||||
|
[role-based access control](../template-permissions.md).
|
||||||
|
|
||||||
|
## Starter templates
|
||||||
|
|
||||||
|
We provide starter templates for common cloud providers, like AWS, and
|
||||||
|
orchestrators, like Kubernetes. From there, you can modify them to use your own
|
||||||
|
images, VPC, cloud credentials, and so on. Coder supports all Terraform
|
||||||
|
resources and properties, so fear not if your favorite cloud provider isn't
|
||||||
|
here!
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
If you prefer to use Coder on the
|
||||||
|
[command line](../../../reference/cli/index.md), `coder templates init`.
|
||||||
|
|
||||||
|
> Coder starter templates are also available on our
|
||||||
|
> [GitHub repo](https://github.com/coder/coder/tree/main/examples/templates).
|
||||||
|
|
||||||
|
## Community Templates
|
||||||
|
|
||||||
|
As well as Coder's starter templates, you can see a list of community templates
|
||||||
|
by our users
|
||||||
|
[here](https://github.com/coder/coder/blob/main/examples/templates/community-templates.md).
|
||||||
|
|
||||||
|
## Editing templates
|
||||||
|
|
||||||
|
Our starter templates are meant to be modified for your use cases. You can edit
|
||||||
|
any template's files directly in the Coder dashboard.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
If you'd prefer to use the CLI, use `coder templates pull`, edit the template
|
||||||
|
files, then `coder templates push`.
|
||||||
|
|
||||||
|
> Even if you are a Terraform expert, we suggest reading our
|
||||||
|
> [guided tour of a template](../../../tutorials/template-from-scratch.md).
|
||||||
|
|
||||||
|
## Updating templates
|
||||||
|
|
||||||
|
Coder tracks a template's versions, keeping all developer workspaces up-to-date.
|
||||||
|
When you publish a new version, developers are notified to get the latest
|
||||||
|
infrastructure, software, or security patches. Learn more about
|
||||||
|
[change management](./change-management.md).
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
### Template update policies (enterprise) (premium)
|
||||||
|
|
||||||
|
Enterprise template admins may want workspaces to always remain on the latest
|
||||||
|
version of their parent template. To do so, enable **Template Update Policies**
|
||||||
|
in the template's general settings. All non-admin users of the template will be
|
||||||
|
forced to update their workspaces before starting them once the setting is
|
||||||
|
applied. Workspaces which leverage autostart or start-on-connect will be
|
||||||
|
automatically updated on the next startup.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
## Delete templates
|
||||||
|
|
||||||
|
You can delete a template using both the coder CLI and UI. Only
|
||||||
|
[template admins and owners](../../users/groups-roles.md#roles) can delete a
|
||||||
|
template, and the template must not have any running workspaces associated to
|
||||||
|
it.
|
||||||
|
|
||||||
|
In the UI, navigate to the template you want to delete, and select the dropdown
|
||||||
|
in the right-hand corner of the page to delete the template.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
Using the CLI, login to Coder and run the following command to delete a
|
||||||
|
template:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
coder templates delete <template-name>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Next steps
|
||||||
|
|
||||||
|
- [Image management](./image-management.md)
|
||||||
|
- [Devcontainer templates](./devcontainers.md)
|
||||||
|
- [Change management](./change-management.md)
|
103
docs/admin/templates/managing-templates/schedule.md
Normal file
103
docs/admin/templates/managing-templates/schedule.md
Normal file
@ -0,0 +1,103 @@
|
|||||||
|
# Workspace Scheduling
|
||||||
|
|
||||||
|
You can configure a template to control how workspaces are started and stopped.
|
||||||
|
You can also manage the lifecycle of failed or inactive workspaces.
|
||||||
|
|
||||||
|

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

|
||||||
|
|
||||||
|
Admins can define the default quiet hours for all users with the
|
||||||
|
`--default-quiet-hours-schedule` flag or `CODER_DEFAULT_QUIET_HOURS_SCHEDULE`
|
||||||
|
environment variable. The value should be a cron expression such as
|
||||||
|
`CRON_TZ=America/Chicago 30 2 * * *` which would set the default quiet hours to
|
||||||
|
2:30 AM in the America/Chicago timezone. The cron schedule can only have a
|
||||||
|
minute and hour component. The default schedule is UTC 00:00. It is recommended
|
||||||
|
to set the default quiet hours to a time when most users are not expected to be
|
||||||
|
using Coder.
|
||||||
|
|
||||||
|
Admins can force users to use the default quiet hours with the
|
||||||
|
[CODER_ALLOW_CUSTOM_QUIET_HOURS](../../../reference/cli/server.md#allow-custom-quiet-hours)
|
||||||
|
environment variable. Users will still be able to see the page, but will be
|
||||||
|
unable to set a custom time or timezone. If users have already set a custom
|
||||||
|
quiet hours schedule, it will be ignored and the default will be used instead.
|
@ -15,8 +15,8 @@ approach for "Open in Coder" flows.
|
|||||||
|
|
||||||
### 1. Set up git authentication
|
### 1. Set up git authentication
|
||||||
|
|
||||||
See [External Authentication](../admin/external-auth.md) to set up git
|
See [External Authentication](../external-auth.md) to set up git authentication
|
||||||
authentication in your Coder deployment.
|
in your Coder deployment.
|
||||||
|
|
||||||
### 2. Modify your template to auto-clone repos
|
### 2. Modify your template to auto-clone repos
|
||||||
|
|
||||||
@ -53,7 +53,7 @@ resource "coder_agent" "dev" {
|
|||||||
> - `coder` (relative to the home directory)
|
> - `coder` (relative to the home directory)
|
||||||
|
|
||||||
If you want the template to support any repository via
|
If you want the template to support any repository via
|
||||||
[parameters](./parameters.md)
|
[parameters](./extending-templates/parameters.md)
|
||||||
|
|
||||||
```hcl
|
```hcl
|
||||||
# Require external authentication to use this template
|
# Require external authentication to use this template
|
||||||
@ -104,7 +104,7 @@ This can be used to pre-fill the git repo URL, disk size, image, etc.
|
|||||||
[](https://YOUR_ACCESS_URL/templates/YOUR_TEMPLATE/workspace?param.git_repo=https://github.com/coder/slog¶m.home_disk_size%20%28GB%29=20)
|
[](https://YOUR_ACCESS_URL/templates/YOUR_TEMPLATE/workspace?param.git_repo=https://github.com/coder/slog¶m.home_disk_size%20%28GB%29=20)
|
||||||
```
|
```
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
### 5. Optional: disable specific parameter fields by including their names as
|
### 5. Optional: disable specific parameter fields by including their names as
|
||||||
|
|
@ -1,6 +1,8 @@
|
|||||||
# Permissions
|
# Permissions (enterprise) (premium)
|
||||||
|
|
||||||

|
Licensed Coder administrators can control who can use and modify the template.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
Permissions allow you to control who can use and modify the template. Both
|
Permissions allow you to control who can use and modify the template. Both
|
||||||
individual user and groups can be added to the access list for a template.
|
individual user and groups can be added to the access list for a template.
|
||||||
@ -14,6 +16,6 @@ By default the `Everyone` group is assigned to each template meaning any Coder
|
|||||||
user can use the template to create a workspace. To prevent this, disable the
|
user can use the template to create a workspace. To prevent this, disable the
|
||||||
`Allow everyone to use the template` setting when creating a template.
|
`Allow everyone to use the template` setting when creating a template.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
Permissions is an enterprise-only feature.
|
Permissions is an enterprise-only feature.
|
@ -21,7 +21,7 @@ practices:
|
|||||||
|
|
||||||
- Ensure the resource has `curl` installed (alternatively, `wget` or `busybox`)
|
- Ensure the resource has `curl` installed (alternatively, `wget` or `busybox`)
|
||||||
- Ensure the resource can `curl` your Coder
|
- Ensure the resource can `curl` your Coder
|
||||||
[access URL](../admin/configure.md#access-url)
|
[access URL](../../admin/setup/index.md#access-url)
|
||||||
- Manually connect to the resource and check the agent logs (e.g.,
|
- Manually connect to the resource and check the agent logs (e.g.,
|
||||||
`kubectl exec`, `docker exec` or AWS console)
|
`kubectl exec`, `docker exec` or AWS console)
|
||||||
- The Coder agent logs are typically stored in `/tmp/coder-agent.log`
|
- The Coder agent logs are typically stored in `/tmp/coder-agent.log`
|
||||||
@ -31,7 +31,7 @@ practices:
|
|||||||
`/tmp/coder-shutdown-script.log`
|
`/tmp/coder-shutdown-script.log`
|
||||||
- This can also happen if the websockets are not being forwarded correctly when
|
- This can also happen if the websockets are not being forwarded correctly when
|
||||||
running Coder behind a reverse proxy.
|
running Coder behind a reverse proxy.
|
||||||
[Read our reverse-proxy docs](../admin/configure.md#tls--reverse-proxy)
|
[Read our reverse-proxy docs](../../admin/setup/index.md#tls--reverse-proxy)
|
||||||
|
|
||||||
## Startup script issues
|
## Startup script issues
|
||||||
|
|
84
docs/admin/users/github-auth.md
Normal file
84
docs/admin/users/github-auth.md
Normal file
@ -0,0 +1,84 @@
|
|||||||
|
## GitHub
|
||||||
|
|
||||||
|
### Step 1: Configure the OAuth application in GitHub
|
||||||
|
|
||||||
|
First,
|
||||||
|
[register a GitHub OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/).
|
||||||
|
GitHub will ask you for the following Coder parameters:
|
||||||
|
|
||||||
|
- **Homepage URL**: Set to your Coder deployments
|
||||||
|
[`CODER_ACCESS_URL`](../../reference/cli/server.md#--access-url) (e.g.
|
||||||
|
`https://coder.domain.com`)
|
||||||
|
- **User Authorization Callback URL**: Set to `https://coder.domain.com`
|
||||||
|
|
||||||
|
> Note: If you want to allow multiple coder deployments hosted on subdomains
|
||||||
|
> e.g. coder1.domain.com, coder2.domain.com, to be able to authenticate with the
|
||||||
|
> same GitHub OAuth app, then you can set **User Authorization Callback URL** to
|
||||||
|
> the `https://domain.com`
|
||||||
|
|
||||||
|
Note the Client ID and Client Secret generated by GitHub. You will use these
|
||||||
|
values in the next step.
|
||||||
|
|
||||||
|
Coder will need permission to access user email addresses. Find the "Account
|
||||||
|
Permissions" settings for your app and select "read-only" for "Email addresses".
|
||||||
|
|
||||||
|
### Step 2: Configure Coder with the OAuth credentials
|
||||||
|
|
||||||
|
Navigate to your Coder host and run the following command to start up the Coder
|
||||||
|
server:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
coder server --oauth2-github-allow-signups=true --oauth2-github-allowed-orgs="your-org" --oauth2-github-client-id="8d1...e05" --oauth2-github-client-secret="57ebc9...02c24c"
|
||||||
|
```
|
||||||
|
|
||||||
|
> For GitHub Enterprise support, specify the
|
||||||
|
> `--oauth2-github-enterprise-base-url` flag.
|
||||||
|
|
||||||
|
Alternatively, if you are running Coder as a system service, you can achieve the
|
||||||
|
same result as the command above by adding the following environment variables
|
||||||
|
to the `/etc/coder.d/coder.env` file:
|
||||||
|
|
||||||
|
```env
|
||||||
|
CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
|
||||||
|
CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
|
||||||
|
CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05"
|
||||||
|
CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note:** To allow everyone to signup using GitHub, set:
|
||||||
|
|
||||||
|
```env
|
||||||
|
CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
|
||||||
|
```
|
||||||
|
|
||||||
|
Once complete, run `sudo service coder restart` to reboot Coder.
|
||||||
|
|
||||||
|
If deploying Coder via Helm, you can set the above environment variables in the
|
||||||
|
`values.yaml` file as such:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
coder:
|
||||||
|
env:
|
||||||
|
- name: CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS
|
||||||
|
value: "true"
|
||||||
|
- name: CODER_OAUTH2_GITHUB_CLIENT_ID
|
||||||
|
value: "533...des"
|
||||||
|
- name: CODER_OAUTH2_GITHUB_CLIENT_SECRET
|
||||||
|
value: "G0CSP...7qSM"
|
||||||
|
# If setting allowed orgs, comment out CODER_OAUTH2_GITHUB_ALLOW_EVERYONE and its value
|
||||||
|
- name: CODER_OAUTH2_GITHUB_ALLOWED_ORGS
|
||||||
|
value: "your-org"
|
||||||
|
# If allowing everyone, comment out CODER_OAUTH2_GITHUB_ALLOWED_ORGS and it's value
|
||||||
|
#- name: CODER_OAUTH2_GITHUB_ALLOW_EVERYONE
|
||||||
|
# value: "true"
|
||||||
|
```
|
||||||
|
|
||||||
|
To upgrade Coder, run:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
> We recommend requiring and auditing MFA usage for all users in your GitHub
|
||||||
|
> organizations. This can be enforced from the organization settings page in the
|
||||||
|
> "Authentication security" sidebar tab.
|
44
docs/admin/users/groups-roles.md
Normal file
44
docs/admin/users/groups-roles.md
Normal file
@ -0,0 +1,44 @@
|
|||||||
|
# Groups and Roles
|
||||||
|
|
||||||
|
Groups and roles can be manually assigned in Coder. For production deployments,
|
||||||
|
these can also be [managed and synced by the identity provider](./idp-sync.md).
|
||||||
|
|
||||||
|
## Groups
|
||||||
|
|
||||||
|
Groups are logical segmentations of users in Coder and can be used to control
|
||||||
|
which templates developers can use. For example:
|
||||||
|
|
||||||
|
- Users within the `devops` group can access the `AWS-VM` template
|
||||||
|
- Users within the `data-science` group can access the `Jupyter-Kubernetes`
|
||||||
|
template
|
||||||
|
|
||||||
|
## Roles
|
||||||
|
|
||||||
|
Roles determine which actions users can take within the platform.
|
||||||
|
|
||||||
|
| | Auditor | User Admin | Template Admin | Owner |
|
||||||
|
| --------------------------------------------------------------- | ------- | ---------- | -------------- | ----- |
|
||||||
|
| Add and remove Users | | ✅ | | ✅ |
|
||||||
|
| Manage groups (enterprise) (premium) | | ✅ | | ✅ |
|
||||||
|
| Change User roles | | | | ✅ |
|
||||||
|
| Manage **ALL** Templates | | | ✅ | ✅ |
|
||||||
|
| View **ALL** Workspaces | | | ✅ | ✅ |
|
||||||
|
| Update and delete **ALL** Workspaces | | | | ✅ |
|
||||||
|
| Run [external provisioners](../provisioners.md) | | | ✅ | ✅ |
|
||||||
|
| Execute and use **ALL** Workspaces | | | | ✅ |
|
||||||
|
| View all user operation [Audit Logs](../security/audit-logs.md) | ✅ | | | ✅ |
|
||||||
|
|
||||||
|
A user may have one or more roles. All users have an implicit Member role that
|
||||||
|
may use personal workspaces.
|
||||||
|
|
||||||
|
### Security notes
|
||||||
|
|
||||||
|
A malicious Template Admin could write a template that executes commands on the
|
||||||
|
host (or `coder server` container), which potentially escalates their privileges
|
||||||
|
or shuts down the Coder server. To avoid this, run
|
||||||
|
[external provisioners](../provisioners.md).
|
||||||
|
|
||||||
|
In low-trust environments, we do not recommend giving users direct access to
|
||||||
|
edit templates. Instead, use
|
||||||
|
[CI/CD pipelines to update templates](../templates/managing-templates/change-management.md)
|
||||||
|
with proper security scans and code reviews in place.
|
31
docs/admin/users/headless-auth.md
Normal file
31
docs/admin/users/headless-auth.md
Normal file
@ -0,0 +1,31 @@
|
|||||||
|
# Headless Authentication
|
||||||
|
|
||||||
|
Headless user accounts that cannot use the web UI to log in to Coder. This is
|
||||||
|
useful for creating accounts for automated systems, such as CI/CD pipelines or
|
||||||
|
for users who only consume Coder via another client/API.
|
||||||
|
|
||||||
|
> You must have the User Admin role or above to create headless users.
|
||||||
|
|
||||||
|
## Create a headless user
|
||||||
|
|
||||||
|
<div class="tabs">
|
||||||
|
|
||||||
|
## CLI
|
||||||
|
|
||||||
|
```sh
|
||||||
|
coder users create \
|
||||||
|
--email="coder-bot@coder.com" \
|
||||||
|
--username="coder-bot" \
|
||||||
|
--login-type="none \
|
||||||
|
```
|
||||||
|
|
||||||
|
## UI
|
||||||
|
|
||||||
|
Navigate to the `Users` > `Create user` in the topbar
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
To make API or CLI requests on behalf of the headless user, learn how to
|
||||||
|
[generate API tokens on behalf of a user](./sessions-tokens.md#generate-a-long-lived-api-token-on-behalf-of-another-user).
|
@ -1,260 +1,11 @@
|
|||||||
# Authentication
|
# IDP Sync (enterprise) (premium)
|
||||||
|
|
||||||
By default, Coder is accessible via password authentication. Coder does not
|
|
||||||
recommend using password authentication in production, and recommends using an
|
|
||||||
authentication provider with properly configured multi-factor authentication
|
|
||||||
(MFA). It is your responsibility to ensure the auth provider enforces MFA
|
|
||||||
correctly.
|
|
||||||
|
|
||||||
The following steps explain how to set up GitHub OAuth or OpenID Connect.
|
|
||||||
|
|
||||||
## GitHub
|
|
||||||
|
|
||||||
### Step 1: Configure the OAuth application in GitHub
|
|
||||||
|
|
||||||
First,
|
|
||||||
[register a GitHub OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/).
|
|
||||||
GitHub will ask you for the following Coder parameters:
|
|
||||||
|
|
||||||
- **Homepage URL**: Set to your Coder deployments
|
|
||||||
[`CODER_ACCESS_URL`](../reference/cli/server.md#--access-url) (e.g.
|
|
||||||
`https://coder.domain.com`)
|
|
||||||
- **User Authorization Callback URL**: Set to `https://coder.domain.com`
|
|
||||||
|
|
||||||
> Note: If you want to allow multiple coder deployments hosted on subdomains
|
|
||||||
> e.g. coder1.domain.com, coder2.domain.com, to be able to authenticate with the
|
|
||||||
> same GitHub OAuth app, then you can set **User Authorization Callback URL** to
|
|
||||||
> the `https://domain.com`
|
|
||||||
|
|
||||||
Note the Client ID and Client Secret generated by GitHub. You will use these
|
|
||||||
values in the next step.
|
|
||||||
|
|
||||||
Coder will need permission to access user email addresses. Find the "Account
|
|
||||||
Permissions" settings for your app and select "read-only" for "Email addresses".
|
|
||||||
|
|
||||||
### Step 2: Configure Coder with the OAuth credentials
|
|
||||||
|
|
||||||
Navigate to your Coder host and run the following command to start up the Coder
|
|
||||||
server:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
coder server --oauth2-github-allow-signups=true --oauth2-github-allowed-orgs="your-org" --oauth2-github-client-id="8d1...e05" --oauth2-github-client-secret="57ebc9...02c24c"
|
|
||||||
```
|
|
||||||
|
|
||||||
> For GitHub Enterprise support, specify the
|
|
||||||
> `--oauth2-github-enterprise-base-url` flag.
|
|
||||||
|
|
||||||
Alternatively, if you are running Coder as a system service, you can achieve the
|
|
||||||
same result as the command above by adding the following environment variables
|
|
||||||
to the `/etc/coder.d/coder.env` file:
|
|
||||||
|
|
||||||
```env
|
|
||||||
CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
|
|
||||||
CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
|
|
||||||
CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05"
|
|
||||||
CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c"
|
|
||||||
```
|
|
||||||
|
|
||||||
**Note:** To allow everyone to signup using GitHub, set:
|
|
||||||
|
|
||||||
```env
|
|
||||||
CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
|
|
||||||
```
|
|
||||||
|
|
||||||
Once complete, run `sudo service coder restart` to reboot Coder.
|
|
||||||
|
|
||||||
If deploying Coder via Helm, you can set the above environment variables in the
|
|
||||||
`values.yaml` file as such:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
coder:
|
|
||||||
env:
|
|
||||||
- name: CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS
|
|
||||||
value: "true"
|
|
||||||
- name: CODER_OAUTH2_GITHUB_CLIENT_ID
|
|
||||||
value: "533...des"
|
|
||||||
- name: CODER_OAUTH2_GITHUB_CLIENT_SECRET
|
|
||||||
value: "G0CSP...7qSM"
|
|
||||||
# If setting allowed orgs, comment out CODER_OAUTH2_GITHUB_ALLOW_EVERYONE and its value
|
|
||||||
- name: CODER_OAUTH2_GITHUB_ALLOWED_ORGS
|
|
||||||
value: "your-org"
|
|
||||||
# If allowing everyone, comment out CODER_OAUTH2_GITHUB_ALLOWED_ORGS and it's value
|
|
||||||
#- name: CODER_OAUTH2_GITHUB_ALLOW_EVERYONE
|
|
||||||
# value: "true"
|
|
||||||
```
|
|
||||||
|
|
||||||
To upgrade Coder, run:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
> We recommend requiring and auditing MFA usage for all users in your GitHub
|
|
||||||
> organizations. This can be enforced from the organization settings page in the
|
|
||||||
> "Authentication security" sidebar tab.
|
|
||||||
|
|
||||||
## OpenID Connect
|
|
||||||
|
|
||||||
The following steps through how to integrate any OpenID Connect provider (Okta,
|
|
||||||
Active Directory, etc.) to Coder.
|
|
||||||
|
|
||||||
### Step 1: Set Redirect URI with your OIDC provider
|
|
||||||
|
|
||||||
Your OIDC provider will ask you for the following parameter:
|
|
||||||
|
|
||||||
- **Redirect URI**: Set to `https://coder.domain.com/api/v2/users/oidc/callback`
|
|
||||||
|
|
||||||
### Step 2: Configure Coder with the OpenID Connect credentials
|
|
||||||
|
|
||||||
Navigate to your Coder host and run the following command to start up the Coder
|
|
||||||
server:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
coder server --oidc-issuer-url="https://issuer.corp.com" --oidc-email-domain="your-domain-1,your-domain-2" --oidc-client-id="533...des" --oidc-client-secret="G0CSP...7qSM"
|
|
||||||
```
|
|
||||||
|
|
||||||
If you are running Coder as a system service, you can achieve the same result as
|
|
||||||
the command above by adding the following environment variables to the
|
|
||||||
`/etc/coder.d/coder.env` file:
|
|
||||||
|
|
||||||
```env
|
|
||||||
CODER_OIDC_ISSUER_URL="https://issuer.corp.com"
|
|
||||||
CODER_OIDC_EMAIL_DOMAIN="your-domain-1,your-domain-2"
|
|
||||||
CODER_OIDC_CLIENT_ID="533...des"
|
|
||||||
CODER_OIDC_CLIENT_SECRET="G0CSP...7qSM"
|
|
||||||
```
|
|
||||||
|
|
||||||
Once complete, run `sudo service coder restart` to reboot Coder.
|
|
||||||
|
|
||||||
If deploying Coder via Helm, you can set the above environment variables in the
|
|
||||||
`values.yaml` file as such:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
coder:
|
|
||||||
env:
|
|
||||||
- name: CODER_OIDC_ISSUER_URL
|
|
||||||
value: "https://issuer.corp.com"
|
|
||||||
- name: CODER_OIDC_EMAIL_DOMAIN
|
|
||||||
value: "your-domain-1,your-domain-2"
|
|
||||||
- name: CODER_OIDC_CLIENT_ID
|
|
||||||
value: "533...des"
|
|
||||||
- name: CODER_OIDC_CLIENT_SECRET
|
|
||||||
value: "G0CSP...7qSM"
|
|
||||||
```
|
|
||||||
|
|
||||||
To upgrade Coder, run:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
## OIDC Claims
|
|
||||||
|
|
||||||
When a user logs in for the first time via OIDC, Coder will merge both the
|
|
||||||
claims from the ID token and the claims obtained from hitting the upstream
|
|
||||||
provider's `userinfo` endpoint, and use the resulting data as a basis for
|
|
||||||
creating a new user or looking up an existing user.
|
|
||||||
|
|
||||||
To troubleshoot claims, set `CODER_VERBOSE=true` and follow the logs while
|
|
||||||
signing in via OIDC as a new user. Coder will log the claim fields returned by
|
|
||||||
the upstream identity provider in a message containing the string
|
|
||||||
`got oidc claims`, as well as the user info returned.
|
|
||||||
|
|
||||||
> **Note:** If you need to ensure that Coder only uses information from the ID
|
|
||||||
> token and does not hit the UserInfo endpoint, you can set the configuration
|
|
||||||
> option `CODER_OIDC_IGNORE_USERINFO=true`.
|
|
||||||
|
|
||||||
### Email Addresses
|
|
||||||
|
|
||||||
By default, Coder will look for the OIDC claim named `email` and use that value
|
|
||||||
for the newly created user's email address.
|
|
||||||
|
|
||||||
If your upstream identity provider users a different claim, you can set
|
|
||||||
`CODER_OIDC_EMAIL_FIELD` to the desired claim.
|
|
||||||
|
|
||||||
> **Note** If this field is not present, Coder will attempt to use the claim
|
|
||||||
> field configured for `username` as an email address. If this field is not a
|
|
||||||
> valid email address, OIDC logins will fail.
|
|
||||||
|
|
||||||
### Email Address Verification
|
|
||||||
|
|
||||||
Coder requires all OIDC email addresses to be verified by default. If the
|
|
||||||
`email_verified` claim is present in the token response from the identity
|
|
||||||
provider, Coder will validate that its value is `true`. If needed, you can
|
|
||||||
disable this behavior with the following setting:
|
|
||||||
|
|
||||||
```env
|
|
||||||
CODER_OIDC_IGNORE_EMAIL_VERIFIED=true
|
|
||||||
```
|
|
||||||
|
|
||||||
> **Note:** This will cause Coder to implicitly treat all OIDC emails as
|
|
||||||
> "verified", regardless of what the upstream identity provider says.
|
|
||||||
|
|
||||||
### Usernames
|
|
||||||
|
|
||||||
When a new user logs in via OIDC, Coder will by default use the value of the
|
|
||||||
claim field named `preferred_username` as the the username.
|
|
||||||
|
|
||||||
If your upstream identity provider uses a different claim, you can set
|
|
||||||
`CODER_OIDC_USERNAME_FIELD` to the desired claim.
|
|
||||||
|
|
||||||
> **Note:** If this claim is empty, the email address will be stripped of the
|
|
||||||
> domain, and become the username (e.g. `example@coder.com` becomes `example`).
|
|
||||||
> To avoid conflicts, Coder may also append a random word to the resulting
|
|
||||||
> username.
|
|
||||||
|
|
||||||
## OIDC Login Customization
|
|
||||||
|
|
||||||
If you'd like to change the OpenID Connect button text and/or icon, you can
|
|
||||||
configure them like so:
|
|
||||||
|
|
||||||
```env
|
|
||||||
CODER_OIDC_SIGN_IN_TEXT="Sign in with Gitea"
|
|
||||||
CODER_OIDC_ICON_URL=https://gitea.io/images/gitea.png
|
|
||||||
```
|
|
||||||
|
|
||||||
To change the icon and text above the OpenID Connect button, see application
|
|
||||||
name and logo url in [appearance](./appearance.md) settings.
|
|
||||||
|
|
||||||
## Disable Built-in Authentication
|
|
||||||
|
|
||||||
To remove email and password login, set the following environment variable on
|
|
||||||
your Coder deployment:
|
|
||||||
|
|
||||||
```env
|
|
||||||
CODER_DISABLE_PASSWORD_AUTH=true
|
|
||||||
```
|
|
||||||
|
|
||||||
## SCIM (enterprise) (premium)
|
|
||||||
|
|
||||||
Coder supports user provisioning and deprovisioning via SCIM 2.0 with header
|
|
||||||
authentication. Upon deactivation, users are
|
|
||||||
[suspended](./users.md#suspend-a-user) and are not deleted.
|
|
||||||
[Configure](./configure.md) your SCIM application with an auth key and supply it
|
|
||||||
the Coder server.
|
|
||||||
|
|
||||||
```env
|
|
||||||
CODER_SCIM_AUTH_HEADER="your-api-key"
|
|
||||||
```
|
|
||||||
|
|
||||||
## TLS
|
|
||||||
|
|
||||||
If your OpenID Connect provider requires client TLS certificates for
|
|
||||||
authentication, you can configure them like so:
|
|
||||||
|
|
||||||
```env
|
|
||||||
CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
|
|
||||||
CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
|
|
||||||
```
|
|
||||||
|
|
||||||
## Group Sync (enterprise) (premium)
|
|
||||||
|
|
||||||
If your OpenID Connect provider supports group claims, you can configure Coder
|
If your OpenID Connect provider supports group claims, you can configure Coder
|
||||||
to synchronize groups in your auth provider to groups within Coder. To enable
|
to synchronize groups in your auth provider to groups within Coder. To enable
|
||||||
group sync, ensure that the `groups` claim is being sent by your OpenID
|
group sync, ensure that the `groups` claim is being sent by your OpenID
|
||||||
provider. You might need to request an additional
|
provider. You might need to request an additional
|
||||||
[scope](../reference/cli/server.md#--oidc-scopes) or additional configuration on
|
[scope](../../reference/cli/server.md#--oidc-scopes) or additional configuration
|
||||||
the OpenID provider side.
|
on the OpenID provider side.
|
||||||
|
|
||||||
If group sync is enabled, the user's groups will be controlled by the OIDC
|
If group sync is enabled, the user's groups will be controlled by the OIDC
|
||||||
provider. This means manual group additions/removals will be overwritten on the
|
provider. This means manual group additions/removals will be overwritten on the
|
||||||
@ -283,7 +34,8 @@ the OIDC provider. See
|
|||||||
> ones include `groups`, `memberOf`, and `roles`.
|
> ones include `groups`, `memberOf`, and `roles`.
|
||||||
|
|
||||||
Next configure the Coder server to read groups from the claim name with the
|
Next configure the Coder server to read groups from the claim name with the
|
||||||
[OIDC group field](../reference/cli/server.md#--oidc-group-field) server flag:
|
[OIDC group field](../../reference/cli/server.md#--oidc-group-field) server
|
||||||
|
flag:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
# as an environment variable
|
# as an environment variable
|
||||||
@ -301,7 +53,7 @@ names in Coder and removed from groups that the user no longer belongs to.
|
|||||||
For cases when an OIDC provider only returns group IDs ([Azure AD][azure-gids])
|
For cases when an OIDC provider only returns group IDs ([Azure AD][azure-gids])
|
||||||
or you want to have different group names in Coder than in your OIDC provider,
|
or you want to have different group names in Coder than in your OIDC provider,
|
||||||
you can configure mapping between the two with the
|
you can configure mapping between the two with the
|
||||||
[OIDC group mapping](../reference/cli/server.md#--oidc-group-mapping) server
|
[OIDC group mapping](../../reference/cli/server.md#--oidc-group-mapping) server
|
||||||
flag.
|
flag.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
@ -339,7 +91,7 @@ For deployments with multiple [organizations](./organizations.md), you must
|
|||||||
configure group sync at the organization level. In future Coder versions, you
|
configure group sync at the organization level. In future Coder versions, you
|
||||||
will be able to configure this in the UI. For now, you must use CLI commands.
|
will be able to configure this in the UI. For now, you must use CLI commands.
|
||||||
|
|
||||||
First confirm you have the [Coder CLI](../install/index.md) installed and are
|
First confirm you have the [Coder CLI](../../install/index.md) installed and are
|
||||||
logged in with a user who is an Owner or Organization Admin role. Next, confirm
|
logged in with a user who is an Owner or Organization Admin role. Next, confirm
|
||||||
that your OIDC provider is sending a groups claim by logging in with OIDC and
|
that your OIDC provider is sending a groups claim by logging in with OIDC and
|
||||||
visiting the following URL:
|
visiting the following URL:
|
||||||
@ -420,7 +172,7 @@ coder organizations settings set group-sync \
|
|||||||
|
|
||||||
Visit the Coder UI to confirm these changes:
|
Visit the Coder UI to confirm these changes:
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
@ -430,7 +182,7 @@ You can limit which groups from your identity provider can log in to Coder with
|
|||||||
[CODER_OIDC_ALLOWED_GROUPS](https://coder.com/docs/cli/server#--oidc-allowed-groups).
|
[CODER_OIDC_ALLOWED_GROUPS](https://coder.com/docs/cli/server#--oidc-allowed-groups).
|
||||||
Users who are not in a matching group will see the following error:
|
Users who are not in a matching group will see the following error:
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
## Role sync (enterprise) (premium)
|
## Role sync (enterprise) (premium)
|
||||||
|
|
||||||
@ -460,10 +212,10 @@ the OIDC provider. See
|
|||||||
> Depending on the OIDC provider, this claim may be named differently.
|
> Depending on the OIDC provider, this claim may be named differently.
|
||||||
|
|
||||||
Next configure the Coder server to read groups from the claim name with the
|
Next configure the Coder server to read groups from the claim name with the
|
||||||
[OIDC role field](../reference/cli/server.md#--oidc-user-role-field) server
|
[OIDC role field](../../reference/cli/server.md#--oidc-user-role-field) server
|
||||||
flag:
|
flag:
|
||||||
|
|
||||||
Set the following in your Coder server [configuration](./configure.md).
|
Set the following in your Coder server [configuration](../setup/index.md).
|
||||||
|
|
||||||
```env
|
```env
|
||||||
# Depending on your identity provider configuration, you may need to explicitly request a "roles" scope
|
# Depending on your identity provider configuration, you may need to explicitly request a "roles" scope
|
||||||
@ -546,7 +298,7 @@ coder organizations settings set role-sync \
|
|||||||
|
|
||||||
Visit the Coder UI to confirm these changes:
|
Visit the Coder UI to confirm these changes:
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
@ -575,7 +327,7 @@ the OIDC provider. See
|
|||||||
> ones include `groups`, `memberOf`, and `roles`.
|
> ones include `groups`, `memberOf`, and `roles`.
|
||||||
|
|
||||||
Next configure the Coder server to read groups from the claim name with the
|
Next configure the Coder server to read groups from the claim name with the
|
||||||
[OIDC organization field](../reference/cli/server.md#--oidc-organization-field)
|
[OIDC organization field](../../reference/cli/server.md#--oidc-organization-field)
|
||||||
server flag:
|
server flag:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
@ -589,7 +341,7 @@ Next, fetch the corresponding organization IDs using the following endpoint:
|
|||||||
https://[coder.example.com]/api/v2/organizations
|
https://[coder.example.com]/api/v2/organizations
|
||||||
```
|
```
|
||||||
|
|
||||||
Set the following in your Coder server [configuration](./configure.md).
|
Set the following in your Coder server [configuration](../setup/index.md).
|
||||||
|
|
||||||
```env
|
```env
|
||||||
CODER_OIDC_ORGANIZATION_MAPPING='{"data-scientists":["d8d9daef-e273-49ff-a832-11fe2b2d4ab1", "70be0908-61b5-4fb5-aba4-4dfb3a6c5787"]}'
|
CODER_OIDC_ORGANIZATION_MAPPING='{"data-scientists":["d8d9daef-e273-49ff-a832-11fe2b2d4ab1", "70be0908-61b5-4fb5-aba4-4dfb3a6c5787"]}'
|
||||||
@ -614,8 +366,8 @@ Some common issues when enabling group/role sync.
|
|||||||
|
|
||||||
If you are running into issues with group/role sync, is best to view your Coder
|
If you are running into issues with group/role sync, is best to view your Coder
|
||||||
server logs and enable
|
server logs and enable
|
||||||
[verbose mode](https://coder.com/docs/v2/v2.5.1/cli#-v---verbose). To reduce
|
[verbose mode](../../reference/cli/index.md#-v---verbose). To reduce noise, you
|
||||||
noise, you can filter for only logs related to group/role sync:
|
can filter for only logs related to group/role sync:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
CODER_VERBOSE=true
|
CODER_VERBOSE=true
|
@ -1,48 +1,33 @@
|
|||||||
# Users
|
# Users
|
||||||
|
|
||||||
This article walks you through the user roles available in Coder and creating
|
By default, Coder is accessible via password authentication. For production
|
||||||
and managing users.
|
deployments, we recommend using an SSO authentication provider with multi-factor
|
||||||
|
authentication (MFA). It is your responsibility to ensure the auth provider
|
||||||
|
enforces MFA correctly.
|
||||||
|
|
||||||
|
## Configuring SSO
|
||||||
|
|
||||||
|
- [OpenID Connect](./oidc-auth.md) (e.g. Okta, KeyCloak, PingFederate, Azure AD)
|
||||||
|
- [GitHub](./github-auth.md) (or GitHub Enterprise)
|
||||||
|
|
||||||
|
## Groups
|
||||||
|
|
||||||
|
Multiple users can be organized into logical groups to control which templates
|
||||||
|
they can use. While groups can be manually created in Coder, we recommend
|
||||||
|
syncing them from your identity provider.
|
||||||
|
|
||||||
|
- [Learn more about Groups](./groups-roles.md)
|
||||||
|
- [Group & Role Sync](./idp-sync.md)
|
||||||
|
|
||||||
## Roles
|
## Roles
|
||||||
|
|
||||||
Coder offers these user roles in the community edition:
|
Roles determine which actions users can take within the platform. Typically,
|
||||||
|
most developers in your organization have the `Member` role, allowing them to
|
||||||
|
create workspaces. Other roles have administrative capabilities such as
|
||||||
|
auditing, managing users, and managing templates.
|
||||||
|
|
||||||
| | Auditor | User Admin | Template Admin | Owner |
|
- [Learn more about Roles](./groups-roles.md)
|
||||||
| ----------------------------------------------------- | ------- | ---------- | -------------- | ----- |
|
- [Group & Role Sync](./idp-sync.md)
|
||||||
| Add and remove Users | | ✅ | | ✅ |
|
|
||||||
| Manage groups (premium) | | ✅ | | ✅ |
|
|
||||||
| Change User roles | | | | ✅ |
|
|
||||||
| Manage **ALL** Templates | | | ✅ | ✅ |
|
|
||||||
| View **ALL** Workspaces | | | ✅ | ✅ |
|
|
||||||
| Update and delete **ALL** Workspaces | | | | ✅ |
|
|
||||||
| Run [external provisioners](./provisioners.md) | | | ✅ | ✅ |
|
|
||||||
| Execute and use **ALL** Workspaces | | | | ✅ |
|
|
||||||
| View all user operation [Audit Logs](./audit-logs.md) | ✅ | | | ✅ |
|
|
||||||
|
|
||||||
A user may have one or more roles. All users have an implicit Member role that
|
|
||||||
may use personal workspaces.
|
|
||||||
|
|
||||||
## Custom Roles (Premium) (Beta)
|
|
||||||
|
|
||||||
Coder v2.16+ deployments can configure custom roles on the
|
|
||||||
[Organization](./organizations.md) level.
|
|
||||||
|
|
||||||

|
|
||||||
|
|
||||||
> Note: This requires a Premium license.
|
|
||||||
> [Contact your account team](https://coder.com/contact) for more details.
|
|
||||||
|
|
||||||
## Security notes
|
|
||||||
|
|
||||||
A malicious Template Admin could write a template that executes commands on the
|
|
||||||
host (or `coder server` container), which potentially escalates their privileges
|
|
||||||
or shuts down the Coder server. To avoid this, run
|
|
||||||
[external provisioners](./provisioners.md).
|
|
||||||
|
|
||||||
In low-trust environments, we do not recommend giving users direct access to
|
|
||||||
edit templates. Instead, use
|
|
||||||
[CI/CD pipelines to update templates](../templates/change-management.md) with
|
|
||||||
proper security scans and code reviews in place.
|
|
||||||
|
|
||||||
## User status
|
## User status
|
||||||
|
|
158
docs/admin/users/oidc-auth.md
Normal file
158
docs/admin/users/oidc-auth.md
Normal file
@ -0,0 +1,158 @@
|
|||||||
|
# OpenID Connect
|
||||||
|
|
||||||
|
The following steps through how to integrate any OpenID Connect provider (Okta,
|
||||||
|
Active Directory, etc.) to Coder.
|
||||||
|
|
||||||
|
## Step 1: Set Redirect URI with your OIDC provider
|
||||||
|
|
||||||
|
Your OIDC provider will ask you for the following parameter:
|
||||||
|
|
||||||
|
- **Redirect URI**: Set to `https://coder.domain.com/api/v2/users/oidc/callback`
|
||||||
|
|
||||||
|
## Step 2: Configure Coder with the OpenID Connect credentials
|
||||||
|
|
||||||
|
Navigate to your Coder host and run the following command to start up the Coder
|
||||||
|
server:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
coder server --oidc-issuer-url="https://issuer.corp.com" --oidc-email-domain="your-domain-1,your-domain-2" --oidc-client-id="533...des" --oidc-client-secret="G0CSP...7qSM"
|
||||||
|
```
|
||||||
|
|
||||||
|
If you are running Coder as a system service, you can achieve the same result as
|
||||||
|
the command above by adding the following environment variables to the
|
||||||
|
`/etc/coder.d/coder.env` file:
|
||||||
|
|
||||||
|
```env
|
||||||
|
CODER_OIDC_ISSUER_URL="https://issuer.corp.com"
|
||||||
|
CODER_OIDC_EMAIL_DOMAIN="your-domain-1,your-domain-2"
|
||||||
|
CODER_OIDC_CLIENT_ID="533...des"
|
||||||
|
CODER_OIDC_CLIENT_SECRET="G0CSP...7qSM"
|
||||||
|
```
|
||||||
|
|
||||||
|
Once complete, run `sudo service coder restart` to reboot Coder.
|
||||||
|
|
||||||
|
If deploying Coder via Helm, you can set the above environment variables in the
|
||||||
|
`values.yaml` file as such:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
coder:
|
||||||
|
env:
|
||||||
|
- name: CODER_OIDC_ISSUER_URL
|
||||||
|
value: "https://issuer.corp.com"
|
||||||
|
- name: CODER_OIDC_EMAIL_DOMAIN
|
||||||
|
value: "your-domain-1,your-domain-2"
|
||||||
|
- name: CODER_OIDC_CLIENT_ID
|
||||||
|
value: "533...des"
|
||||||
|
- name: CODER_OIDC_CLIENT_SECRET
|
||||||
|
value: "G0CSP...7qSM"
|
||||||
|
```
|
||||||
|
|
||||||
|
To upgrade Coder, run:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
## OIDC Claims
|
||||||
|
|
||||||
|
When a user logs in for the first time via OIDC, Coder will merge both the
|
||||||
|
claims from the ID token and the claims obtained from hitting the upstream
|
||||||
|
provider's `userinfo` endpoint, and use the resulting data as a basis for
|
||||||
|
creating a new user or looking up an existing user.
|
||||||
|
|
||||||
|
To troubleshoot claims, set `CODER_VERBOSE=true` and follow the logs while
|
||||||
|
signing in via OIDC as a new user. Coder will log the claim fields returned by
|
||||||
|
the upstream identity provider in a message containing the string
|
||||||
|
`got oidc claims`, as well as the user info returned.
|
||||||
|
|
||||||
|
> **Note:** If you need to ensure that Coder only uses information from the ID
|
||||||
|
> token and does not hit the UserInfo endpoint, you can set the configuration
|
||||||
|
> option `CODER_OIDC_IGNORE_USERINFO=true`.
|
||||||
|
|
||||||
|
### Email Addresses
|
||||||
|
|
||||||
|
By default, Coder will look for the OIDC claim named `email` and use that value
|
||||||
|
for the newly created user's email address.
|
||||||
|
|
||||||
|
If your upstream identity provider users a different claim, you can set
|
||||||
|
`CODER_OIDC_EMAIL_FIELD` to the desired claim.
|
||||||
|
|
||||||
|
> **Note** If this field is not present, Coder will attempt to use the claim
|
||||||
|
> field configured for `username` as an email address. If this field is not a
|
||||||
|
> valid email address, OIDC logins will fail.
|
||||||
|
|
||||||
|
### Email Address Verification
|
||||||
|
|
||||||
|
Coder requires all OIDC email addresses to be verified by default. If the
|
||||||
|
`email_verified` claim is present in the token response from the identity
|
||||||
|
provider, Coder will validate that its value is `true`. If needed, you can
|
||||||
|
disable this behavior with the following setting:
|
||||||
|
|
||||||
|
```env
|
||||||
|
CODER_OIDC_IGNORE_EMAIL_VERIFIED=true
|
||||||
|
```
|
||||||
|
|
||||||
|
> **Note:** This will cause Coder to implicitly treat all OIDC emails as
|
||||||
|
> "verified", regardless of what the upstream identity provider says.
|
||||||
|
|
||||||
|
### Usernames
|
||||||
|
|
||||||
|
When a new user logs in via OIDC, Coder will by default use the value of the
|
||||||
|
claim field named `preferred_username` as the the username.
|
||||||
|
|
||||||
|
If your upstream identity provider uses a different claim, you can set
|
||||||
|
`CODER_OIDC_USERNAME_FIELD` to the desired claim.
|
||||||
|
|
||||||
|
> **Note:** If this claim is empty, the email address will be stripped of the
|
||||||
|
> domain, and become the username (e.g. `example@coder.com` becomes `example`).
|
||||||
|
> To avoid conflicts, Coder may also append a random word to the resulting
|
||||||
|
> username.
|
||||||
|
|
||||||
|
## OIDC Login Customization
|
||||||
|
|
||||||
|
If you'd like to change the OpenID Connect button text and/or icon, you can
|
||||||
|
configure them like so:
|
||||||
|
|
||||||
|
```env
|
||||||
|
CODER_OIDC_SIGN_IN_TEXT="Sign in with Gitea"
|
||||||
|
CODER_OIDC_ICON_URL=https://gitea.io/images/gitea.png
|
||||||
|
```
|
||||||
|
|
||||||
|
To change the icon and text above the OpenID Connect button, see application
|
||||||
|
name and logo url in [appearance](../setup/appearance.md) settings.
|
||||||
|
|
||||||
|
## Disable Built-in Authentication
|
||||||
|
|
||||||
|
To remove email and password login, set the following environment variable on
|
||||||
|
your Coder deployment:
|
||||||
|
|
||||||
|
```env
|
||||||
|
CODER_DISABLE_PASSWORD_AUTH=true
|
||||||
|
```
|
||||||
|
|
||||||
|
## SCIM (enterprise) (premium)
|
||||||
|
|
||||||
|
Coder supports user provisioning and deprovisioning via SCIM 2.0 with header
|
||||||
|
authentication. Upon deactivation, users are
|
||||||
|
[suspended](./index.md#suspend-a-user) and are not deleted.
|
||||||
|
[Configure](../setup/index.md) your SCIM application with an auth key and supply
|
||||||
|
it the Coder server.
|
||||||
|
|
||||||
|
```env
|
||||||
|
CODER_SCIM_AUTH_HEADER="your-api-key"
|
||||||
|
```
|
||||||
|
|
||||||
|
## TLS
|
||||||
|
|
||||||
|
If your OpenID Connect provider requires client TLS certificates for
|
||||||
|
authentication, you can configure them like so:
|
||||||
|
|
||||||
|
```env
|
||||||
|
CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
|
||||||
|
CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
|
||||||
|
```
|
||||||
|
|
||||||
|
### Next steps
|
||||||
|
|
||||||
|
- [Group Sync](./idp-sync.md)
|
||||||
|
- [Groups & Roles](./groups-roles.md)
|
@ -1,7 +1,8 @@
|
|||||||
# Organizations (Premium)
|
# Organizations (Premium)
|
||||||
|
|
||||||
> Note: Organizations requires a [Premium license](../licensing.md). For more
|
> Note: Organizations requires a
|
||||||
> details, [contact your account team](https://coder.com/contact).
|
> [Premium license](https://coder.com/pricing#compare-plans). For more details,
|
||||||
|
> [contact your account team](https://coder.com/contact).
|
||||||
|
|
||||||
Organizations can be used to segment and isolate resources inside a Coder
|
Organizations can be used to segment and isolate resources inside a Coder
|
||||||
deployment for different user groups or projects.
|
deployment for different user groups or projects.
|
||||||
@ -11,7 +12,7 @@ deployment for different user groups or projects.
|
|||||||
Here is an example of how one could use organizations to run a Coder deployment
|
Here is an example of how one could use organizations to run a Coder deployment
|
||||||
with multiple platform teams, all with unique resources:
|
with multiple platform teams, all with unique resources:
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
## The default organization
|
## The default organization
|
||||||
|
|
||||||
@ -20,21 +21,21 @@ All Coder deployments start with one organization called `Coder`.
|
|||||||
To edit the organization details, navigate to `Deployment -> Organizations` in
|
To edit the organization details, navigate to `Deployment -> Organizations` in
|
||||||
the top bar:
|
the top bar:
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
From there, you can manage the name, icon, description, users, and groups:
|
From there, you can manage the name, icon, description, users, and groups:
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
## Additional organizations
|
## Additional organizations
|
||||||
|
|
||||||
Any additional organizations have unique admins, users, templates, provisioners,
|
Any additional organizations have unique admins, users, templates, provisioners,
|
||||||
groups, and workspaces. Each organization must have at least one
|
groups, and workspaces. Each organization must have at least one
|
||||||
[provisioner](./provisioners.md) as the built-in provisioner only applies to the
|
[provisioner](../provisioners.md) as the built-in provisioner only applies to
|
||||||
default organization.
|
the default organization.
|
||||||
|
|
||||||
You can configure [organization/role/group sync](./auth.md) from your identity
|
You can configure [organization/role/group sync](./idp-sync.md) from your
|
||||||
provider to avoid manually assigning users to organizations.
|
identity provider to avoid manually assigning users to organizations.
|
||||||
|
|
||||||
## Creating an organization
|
## Creating an organization
|
||||||
|
|
||||||
@ -49,17 +50,16 @@ provider to avoid manually assigning users to organizations.
|
|||||||
Within the sidebar, click `New organization` to create an organization. In this
|
Within the sidebar, click `New organization` to create an organization. In this
|
||||||
example, we'll create the `data-platform` org.
|
example, we'll create the `data-platform` org.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
From there, let's deploy a provisioner and template for this organization.
|
From there, let's deploy a provisioner and template for this organization.
|
||||||
|
|
||||||
### 2. Deploy a provisioner
|
### 2. Deploy a provisioner
|
||||||
|
|
||||||
[Provisioners](../admin/provisioners.md) are organization-scoped and are
|
[Provisioners](../provisioners.md) are organization-scoped and are responsible
|
||||||
responsible for executing Terraform/OpenTofu to provision the infrastructure for
|
for executing Terraform/OpenTofu to provision the infrastructure for workspaces
|
||||||
workspaces and testing templates. Before creating templates, we must deploy at
|
and testing templates. Before creating templates, we must deploy at least one
|
||||||
least one provisioner as the built-in provisioners are scoped to the default
|
provisioner as the built-in provisioners are scoped to the default organization.
|
||||||
organization.
|
|
||||||
|
|
||||||
Using Coder CLI, run the following command to create a key that will be used to
|
Using Coder CLI, run the following command to create a key that will be used to
|
||||||
authenticate the provisioner:
|
authenticate the provisioner:
|
||||||
@ -74,7 +74,7 @@ Successfully created provisioner key data-cluster! Save this authentication toke
|
|||||||
Next, start the provisioner with the key on your desired platform. In this
|
Next, start the provisioner with the key on your desired platform. In this
|
||||||
example, we'll start it using the Coder CLI on a host with Docker. For
|
example, we'll start it using the Coder CLI on a host with Docker. For
|
||||||
instructions on using other platforms like Kubernetes, see our
|
instructions on using other platforms like Kubernetes, see our
|
||||||
[provisioner documentation](../admin/provisioners.md).
|
[provisioner documentation](../provisioners.md).
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
export CODER_URL=https://<your-coder-url>
|
export CODER_URL=https://<your-coder-url>
|
||||||
@ -87,24 +87,24 @@ coder provisionerd start --org <org-name>
|
|||||||
Once you've started a provisioner, you can create a template. You'll notice the
|
Once you've started a provisioner, you can create a template. You'll notice the
|
||||||
"Create Template" screen now has an organization dropdown:
|
"Create Template" screen now has an organization dropdown:
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
### 5. Add members
|
### 5. Add members
|
||||||
|
|
||||||
Navigate to `Deployment->Organizations` to add members to your organization.
|
Navigate to `Deployment->Organizations` to add members to your organization.
|
||||||
Once added, they will be able to see the organization-specific templates.
|
Once added, they will be able to see the organization-specific templates.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
### 6. Create a workspace
|
### 6. Create a workspace
|
||||||
|
|
||||||
Now, users in the data platform organization will see the templates related to
|
Now, users in the data platform organization will see the templates related to
|
||||||
their organization. Users can be in multiple organizations.
|
their organization. Users can be in multiple organizations.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
## Beta
|
## Beta
|
||||||
|
|
||||||
Organizations is in beta. If you encounter any issues, please
|
As of v2.16.0, Organizations is in beta. If you encounter any issues, please
|
||||||
[file an issue](https://github.com/coder/coder/issues/new) or contact your
|
[file an issue](https://github.com/coder/coder/issues/new) or contact your
|
||||||
account team.
|
account team.
|
27
docs/admin/users/password-auth.md
Normal file
27
docs/admin/users/password-auth.md
Normal file
@ -0,0 +1,27 @@
|
|||||||
|
# Password Authentication
|
||||||
|
|
||||||
|
Coder has password authentication enabled by default. The account created during
|
||||||
|
setup is a username/password account.
|
||||||
|
|
||||||
|
## Disable password authentication
|
||||||
|
|
||||||
|
To disable password authentication, use the
|
||||||
|
[`CODER_DISABLE_PASSWORD_AUTH`](../../reference/cli/server.md#--disable-password-auth)
|
||||||
|
flag on the Coder server.
|
||||||
|
|
||||||
|
## Restore the `Owner` user
|
||||||
|
|
||||||
|
If you remove the admin user account (or forget the password), you can run the
|
||||||
|
[`coder server create-admin-user`](../../reference/cli/server_create-admin-user.md)command
|
||||||
|
on your server.
|
||||||
|
|
||||||
|
> Note: You must run this command on the same machine running the Coder server.
|
||||||
|
> If you are running Coder on Kubernetes, this means using
|
||||||
|
> [kubectl exec](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_exec/)
|
||||||
|
> to exec into the pod.
|
||||||
|
|
||||||
|
## Reset a user's password
|
||||||
|
|
||||||
|
An admin must reset passwords on behalf of users. This can be done in the web UI
|
||||||
|
in the Users page or CLI:
|
||||||
|
[`coder reset-password`](../../reference/cli/reset-password.md)
|
@ -9,7 +9,8 @@ For example: A template is configured with a cost of 5 credits per day, and the
|
|||||||
user is granted 15 credits, which can be consumed by both started and stopped
|
user is granted 15 credits, which can be consumed by both started and stopped
|
||||||
workspaces. This budget limits the user to 3 concurrent workspaces.
|
workspaces. This budget limits the user to 3 concurrent workspaces.
|
||||||
|
|
||||||
Quotas are licensed with [Groups](./groups.md).
|
Quotas are scoped to [Groups](./groups-roles.md) in Enterprise and
|
||||||
|
[organizations](./organizations.md) in Premium.
|
||||||
|
|
||||||
## Definitions
|
## Definitions
|
||||||
|
|
||||||
@ -70,7 +71,7 @@ unused workspaces and freeing up compute in the cluster.
|
|||||||
Each group has a configurable Quota Allowance. A user's budget is calculated as
|
Each group has a configurable Quota Allowance. A user's budget is calculated as
|
||||||
the sum of their allowances.
|
the sum of their allowances.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
For example:
|
For example:
|
||||||
|
|
||||||
@ -98,8 +99,9 @@ process dynamically calculates costs, so quota violation fails builds as opposed
|
|||||||
to failing the build-triggering operation. For example, the Workspace Create
|
to failing the build-triggering operation. For example, the Workspace Create
|
||||||
Form will never get held up by quota enforcement.
|
Form will never get held up by quota enforcement.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
## Up next
|
## Up next
|
||||||
|
|
||||||
- [Configuring](./configure.md)
|
- [Group Sync](./idp-sync.md)
|
||||||
|
- [Control plane configuration](../setup/index.md)
|
64
docs/admin/users/sessions-tokens.md
Normal file
64
docs/admin/users/sessions-tokens.md
Normal file
@ -0,0 +1,64 @@
|
|||||||
|
# API & Session Tokens
|
||||||
|
|
||||||
|
Users can generate tokens to make API requests on behalf of themselves.
|
||||||
|
|
||||||
|
## Short-Lived Tokens (Sessions)
|
||||||
|
|
||||||
|
The [Coder CLI](../../install/cli.md) and [Backstage Plugin](#TODO) use
|
||||||
|
short-lived token to authenticate. To generate a short-lived session token on
|
||||||
|
behalf of your account, visit the following URL:
|
||||||
|
`https://coder.example.com/cli-auth`
|
||||||
|
|
||||||
|
### Session Durations
|
||||||
|
|
||||||
|
By default, sessions last 24 hours and are automatically refreshed. You can
|
||||||
|
configure
|
||||||
|
[`CODER_SESSION_DURATION`](../../reference/cli/server.md#--session-duration) to
|
||||||
|
change the duration and
|
||||||
|
[`CODER_DISABLE_SESSION_EXPIRY_REFRESH`](../../reference/cli/server.md#--disable-session-expiry-refresh)
|
||||||
|
to configure this behavior.
|
||||||
|
|
||||||
|
## Long-Lived Tokens (API Tokens)
|
||||||
|
|
||||||
|
Users can create long lived tokens. We refer to these as "API tokens" in the
|
||||||
|
product.
|
||||||
|
|
||||||
|
### Generate a long-lived API token on behalf of yourself
|
||||||
|
|
||||||
|
<div class="tabs">
|
||||||
|
|
||||||
|
#### UI
|
||||||
|
|
||||||
|
Visit your account settings in the top right of the dashboard or by navigating
|
||||||
|
to `https://coder.example.com/settings/account`
|
||||||
|
|
||||||
|
Navigate to the tokens page in the sidebar and create a new token:
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
#### CLI
|
||||||
|
|
||||||
|
Use the following command:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
coder tokens create --name=my-token --lifetime=720h
|
||||||
|
```
|
||||||
|
|
||||||
|
See the help docs for
|
||||||
|
[`coder tokens create`](../../reference/cli/tokens_create.md) for more info.
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
### Generate a long-lived API token on behalf of another user
|
||||||
|
|
||||||
|
Today, you must use the REST API to generate a token on behalf of another user.
|
||||||
|
You must have the `Owner` role to do this. Use our API reference for more
|
||||||
|
information:
|
||||||
|
[Create token API key](https://coder.com/docs/reference/api/users#create-token-api-key)
|
||||||
|
|
||||||
|
### Set max token length
|
||||||
|
|
||||||
|
You can use the
|
||||||
|
[`CODER_MAX_TOKEN_LIFETIME`](https://coder.com/docs/reference/cli/server#--max-token-lifetime)
|
||||||
|
server flag to set the maximum duration for long-lived tokens in your
|
||||||
|
deployment.
|
@ -1,393 +0,0 @@
|
|||||||
# Architecture
|
|
||||||
|
|
||||||
The Coder deployment model is flexible and offers various components that
|
|
||||||
platform administrators can deploy and scale depending on their use case. This
|
|
||||||
page describes possible deployments, challenges, and risks associated with them.
|
|
||||||
|
|
||||||
## Primary components
|
|
||||||
|
|
||||||
### coderd
|
|
||||||
|
|
||||||
_coderd_ is the service created by running `coder server`. It is a thin API that
|
|
||||||
connects workspaces, provisioners and users. _coderd_ stores its state in
|
|
||||||
Postgres and is the only service that communicates with Postgres.
|
|
||||||
|
|
||||||
It offers:
|
|
||||||
|
|
||||||
- Dashboard (UI)
|
|
||||||
- HTTP API
|
|
||||||
- Dev URLs (HTTP reverse proxy to workspaces)
|
|
||||||
- Workspace Web Applications (e.g for easy access to `code-server`)
|
|
||||||
- Agent registration
|
|
||||||
|
|
||||||
### provisionerd
|
|
||||||
|
|
||||||
_provisionerd_ is the execution context for infrastructure modifying providers.
|
|
||||||
At the moment, the only provider is Terraform (running `terraform`).
|
|
||||||
|
|
||||||
By default, the Coder server runs multiple provisioner daemons.
|
|
||||||
[External provisioners](../admin/provisioners.md) can be added for security or
|
|
||||||
scalability purposes.
|
|
||||||
|
|
||||||
### Agents
|
|
||||||
|
|
||||||
An agent is the Coder service that runs within a user's remote workspace. It
|
|
||||||
provides a consistent interface for coderd and clients to communicate with
|
|
||||||
workspaces regardless of operating system, architecture, or cloud.
|
|
||||||
|
|
||||||
It offers the following services along with much more:
|
|
||||||
|
|
||||||
- SSH
|
|
||||||
- Port forwarding
|
|
||||||
- Liveness checks
|
|
||||||
- `startup_script` automation
|
|
||||||
|
|
||||||
Templates are responsible for
|
|
||||||
[creating and running agents](../templates/index.md#coder-agent) within
|
|
||||||
workspaces.
|
|
||||||
|
|
||||||
### Service Bundling
|
|
||||||
|
|
||||||
While _coderd_ and Postgres can be orchestrated independently, our default
|
|
||||||
installation paths bundle them all together into one system service. It's
|
|
||||||
perfectly fine to run a production deployment this way, but there are certain
|
|
||||||
situations that necessitate decomposition:
|
|
||||||
|
|
||||||
- Reducing global client latency (distribute coderd and centralize database)
|
|
||||||
- Achieving greater availability and efficiency (horizontally scale individual
|
|
||||||
services)
|
|
||||||
|
|
||||||
### Workspaces
|
|
||||||
|
|
||||||
At the highest level, a workspace is a set of cloud resources. These resources
|
|
||||||
can be VMs, Kubernetes clusters, storage buckets, or whatever else Terraform
|
|
||||||
lets you dream up.
|
|
||||||
|
|
||||||
The resources that run the agent are described as _computational resources_,
|
|
||||||
while those that don't are called _peripheral resources_.
|
|
||||||
|
|
||||||
Each resource may also be _persistent_ or _ephemeral_ depending on whether
|
|
||||||
they're destroyed on workspace stop.
|
|
||||||
|
|
||||||
## Deployment models
|
|
||||||
|
|
||||||
### Single region architecture
|
|
||||||
|
|
||||||

|
|
||||||
|
|
||||||
#### Components
|
|
||||||
|
|
||||||
This architecture consists of a single load balancer, several _coderd_ replicas,
|
|
||||||
and _Coder workspaces_ deployed in the same region.
|
|
||||||
|
|
||||||
##### Workload resources
|
|
||||||
|
|
||||||
- Deploy at least one _coderd_ replica per availability zone with _coderd_
|
|
||||||
instances and provisioners. High availability is recommended but not essential
|
|
||||||
for small deployments.
|
|
||||||
- Single replica deployment is a special case that can address a
|
|
||||||
tiny/small/proof-of-concept installation on a single virtual machine. If you
|
|
||||||
are serving more than 100 users/workspaces, you should add more replicas.
|
|
||||||
|
|
||||||
**Coder workspace**
|
|
||||||
|
|
||||||
- For small deployments consider a lightweight workspace runtime like the
|
|
||||||
[Sysbox](https://github.com/nestybox/sysbox) container runtime. Learn more how
|
|
||||||
to enable
|
|
||||||
[docker-in-docker using Sysbox](https://asciinema.org/a/kkTmOxl8DhEZiM2fLZNFlYzbo?speed=2).
|
|
||||||
|
|
||||||
**HA Database**
|
|
||||||
|
|
||||||
- Monitor node status and resource utilization metrics.
|
|
||||||
- Implement robust backup and disaster recovery strategies to protect against
|
|
||||||
data loss.
|
|
||||||
|
|
||||||
##### Workload supporting resources
|
|
||||||
|
|
||||||
**Load balancer**
|
|
||||||
|
|
||||||
- Distributes and load balances traffic from agents and clients to _Coder
|
|
||||||
Server_ replicas across availability zones.
|
|
||||||
- Layer 7 load balancing. The load balancer can decrypt SSL traffic, and
|
|
||||||
re-encrypt using an internal certificate.
|
|
||||||
- Session persistence (sticky sessions) can be disabled as _coderd_ instances
|
|
||||||
are stateless.
|
|
||||||
- WebSocket and long-lived connections must be supported.
|
|
||||||
|
|
||||||
**Single sign-on**
|
|
||||||
|
|
||||||
- Integrate with existing Single Sign-On (SSO) solutions used within the
|
|
||||||
organization via the supported OAuth 2.0 or OpenID Connect standards.
|
|
||||||
- Learn more about [Authentication in Coder](../admin/auth.md).
|
|
||||||
|
|
||||||
### Multi-region architecture
|
|
||||||
|
|
||||||

|
|
||||||
|
|
||||||
#### Components
|
|
||||||
|
|
||||||
This architecture is for globally distributed developer teams using Coder
|
|
||||||
workspaces on daily basis. It features a single load balancer with regionally
|
|
||||||
deployed _Workspace Proxies_, several _coderd_ replicas, and _Coder workspaces_
|
|
||||||
provisioned in different regions.
|
|
||||||
|
|
||||||
Note: The _multi-region architecture_ assumes the same deployment principles as
|
|
||||||
the _single region architecture_, but it extends them to multi region deployment
|
|
||||||
with workspace proxies. Proxies are deployed in regions closest to developers to
|
|
||||||
offer the fastest developer experience.
|
|
||||||
|
|
||||||
##### Workload resources
|
|
||||||
|
|
||||||
**Workspace proxy**
|
|
||||||
|
|
||||||
- Workspace proxy offers developers the option to establish a fast relay
|
|
||||||
connection when accessing their workspace via SSH, a workspace application, or
|
|
||||||
port forwarding.
|
|
||||||
- Dashboard connections, API calls (e.g. _list workspaces_) are not served over
|
|
||||||
proxies.
|
|
||||||
- Proxies do not establish connections to the database.
|
|
||||||
- Proxy instances do not share authentication tokens between one another.
|
|
||||||
|
|
||||||
##### Workload supporting resources
|
|
||||||
|
|
||||||
**Proxy load balancer**
|
|
||||||
|
|
||||||
- Distributes and load balances workspace relay traffic in a single region
|
|
||||||
across availability zones.
|
|
||||||
- Layer 7 load balancing. The load balancer can decrypt SSL traffic, and
|
|
||||||
re-encrypt using internal certificate.
|
|
||||||
- Session persistence (sticky sessions) can be disabled as _coderd_ instances
|
|
||||||
are stateless.
|
|
||||||
- WebSocket and long-lived connections must be supported.
|
|
||||||
|
|
||||||
### Multi-cloud architecture
|
|
||||||
|
|
||||||
By distributing Coder workspaces across different cloud providers, organizations
|
|
||||||
can mitigate the risk of downtime caused by provider-specific outages or
|
|
||||||
disruptions. Additionally, multi-cloud deployment enables organizations to
|
|
||||||
leverage the unique features and capabilities offered by each cloud provider,
|
|
||||||
such as region availability and pricing models.
|
|
||||||
|
|
||||||

|
|
||||||
|
|
||||||
#### Components
|
|
||||||
|
|
||||||
The deployment model comprises:
|
|
||||||
|
|
||||||
- `coderd` instances deployed within a single region of the same cloud provider,
|
|
||||||
with replicas strategically distributed across availability zones.
|
|
||||||
- Workspace provisioners deployed in each cloud, communicating with `coderd`
|
|
||||||
instances.
|
|
||||||
- Workspace proxies running in the same locations as provisioners to optimize
|
|
||||||
user connections to workspaces for maximum speed.
|
|
||||||
|
|
||||||
Due to the relatively large overhead of cross-regional communication, it is not
|
|
||||||
advised to set up multi-cloud control planes. It is recommended to keep coderd
|
|
||||||
replicas and the database within the same cloud-provider and region.
|
|
||||||
|
|
||||||
Note: The _multi-cloud architecture_ follows the deployment principles outlined
|
|
||||||
in the _multi-region architecture_. However, it adapts component selection based
|
|
||||||
on the specific cloud provider. Developers can initiate workspaces based on the
|
|
||||||
nearest region and technical specifications provided by the cloud providers.
|
|
||||||
|
|
||||||
##### Workload resources
|
|
||||||
|
|
||||||
**Workspace provisioner**
|
|
||||||
|
|
||||||
- _Security recommendation_: Create a long, random pre-shared key (PSK) and add
|
|
||||||
it to the regional secret store, so that local _provisionerd_ can access it.
|
|
||||||
Remember to distribute it using safe, encrypted communication channel. The PSK
|
|
||||||
must also be added to the _coderd_ configuration.
|
|
||||||
|
|
||||||
**Workspace proxy**
|
|
||||||
|
|
||||||
- _Security recommendation_: Use `coder` CLI to create
|
|
||||||
[authentication tokens for every workspace proxy](../admin/workspace-proxies.md#requirements),
|
|
||||||
and keep them in regional secret stores. Remember to distribute them using
|
|
||||||
safe, encrypted communication channel.
|
|
||||||
|
|
||||||
**Managed database**
|
|
||||||
|
|
||||||
- For AWS: _Amazon RDS for PostgreSQL_
|
|
||||||
- For Azure: _Azure Database for PostgreSQL - Flexible Server_
|
|
||||||
- For GCP: _Cloud SQL for PostgreSQL_
|
|
||||||
|
|
||||||
##### Workload supporting resources
|
|
||||||
|
|
||||||
**Kubernetes platform (optional)**
|
|
||||||
|
|
||||||
- For AWS: _Amazon Elastic Kubernetes Service_
|
|
||||||
- For Azure: _Azure Kubernetes Service_
|
|
||||||
- For GCP: _Google Kubernetes Engine_
|
|
||||||
|
|
||||||
See here for an example deployment of
|
|
||||||
[Coder on Azure Kubernetes Service](https://github.com/ericpaulsen/coder-aks).
|
|
||||||
|
|
||||||
Learn more about [security requirements](../install/kubernetes.md) for deploying
|
|
||||||
Coder on Kubernetes.
|
|
||||||
|
|
||||||
**Load balancer**
|
|
||||||
|
|
||||||
- For AWS:
|
|
||||||
- _AWS Network Load Balancer_
|
|
||||||
- Level 4 load balancing
|
|
||||||
- For Kubernetes deployment: annotate service with
|
|
||||||
`service.beta.kubernetes.io/aws-load-balancer-type: "nlb"`, preserve the
|
|
||||||
client source IP with `externalTrafficPolicy: Local`
|
|
||||||
- _AWS Classic Load Balancer_
|
|
||||||
- Level 7 load balancing
|
|
||||||
- For Kubernetes deployment: set `sessionAffinity` to `None`
|
|
||||||
- For Azure:
|
|
||||||
- _Azure Load Balancer_
|
|
||||||
- Level 7 load balancing
|
|
||||||
- Azure Application Gateway
|
|
||||||
- Deploy Azure Application Gateway when more advanced traffic routing
|
|
||||||
policies are needed for Kubernetes applications.
|
|
||||||
- Take advantage of features such as WebSocket support and TLS termination
|
|
||||||
provided by Azure Application Gateway, enhancing the capabilities of
|
|
||||||
Kubernetes deployments on Azure.
|
|
||||||
- For GCP:
|
|
||||||
- _Cloud Load Balancing_ with SSL load balancer:
|
|
||||||
- Layer 4 load balancing, SSL enabled
|
|
||||||
- _Cloud Load Balancing_ with HTTPS load balancer:
|
|
||||||
- Layer 7 load balancing
|
|
||||||
- For Kubernetes deployment: annotate service (with ingress enabled) with
|
|
||||||
`kubernetes.io/ingress.class: "gce"`, leverage the `NodePort` service
|
|
||||||
type.
|
|
||||||
- Note: HTTP load balancer rejects DERP upgrade, Coder will fallback to
|
|
||||||
WebSockets
|
|
||||||
|
|
||||||
**Single sign-on**
|
|
||||||
|
|
||||||
- For AWS:
|
|
||||||
[AWS IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html)
|
|
||||||
- For Azure:
|
|
||||||
[Microsoft Entra ID Sign-On](https://learn.microsoft.com/en-us/entra/identity/app-proxy/)
|
|
||||||
- For GCP:
|
|
||||||
[Google Cloud Identity Platform](https://cloud.google.com/architecture/identity/single-sign-on)
|
|
||||||
|
|
||||||
### Air-gapped architecture
|
|
||||||
|
|
||||||
The air-gapped deployment model refers to the setup of Coder's development
|
|
||||||
environment within a restricted network environment that lacks internet
|
|
||||||
connectivity. This deployment model is often required for organizations with
|
|
||||||
strict security policies or those operating in isolated environments, such as
|
|
||||||
government agencies or certain enterprise setups.
|
|
||||||
|
|
||||||
The key features of the air-gapped architecture include:
|
|
||||||
|
|
||||||
- _Offline installation_: Deploy workspaces without relying on an external
|
|
||||||
internet connection.
|
|
||||||
- _Isolated package/plugin repositories_: Depend on local repositories for
|
|
||||||
software installation, updates, and security patches.
|
|
||||||
- _Secure data transfer_: Enable encrypted communication channels and robust
|
|
||||||
access controls to safeguard sensitive information.
|
|
||||||
|
|
||||||
Learn more about [offline deployments](../install/offline.md) of Coder.
|
|
||||||
|
|
||||||

|
|
||||||
|
|
||||||
#### Components
|
|
||||||
|
|
||||||
The deployment model includes:
|
|
||||||
|
|
||||||
- _Workspace provisioners_ with direct access to self-hosted package and plugin
|
|
||||||
repositories and restricted internet access.
|
|
||||||
- _Mirror of Terraform Registry_ with multiple versions of Terraform plugins.
|
|
||||||
- _Certificate Authority_ with all TLS certificates to build secure
|
|
||||||
communication channels.
|
|
||||||
|
|
||||||
The model is compatible with various infrastructure models, enabling deployment
|
|
||||||
across multiple regions and diverse cloud platforms.
|
|
||||||
|
|
||||||
##### Workload resources
|
|
||||||
|
|
||||||
**Workspace provisioner**
|
|
||||||
|
|
||||||
- Includes Terraform binary in the container or system image.
|
|
||||||
- Checks out Terraform plugins from self-hosted _Registry_ mirror.
|
|
||||||
- Deploys workspace images stored in the self-hosted _Container Registry_.
|
|
||||||
|
|
||||||
**Coder server**
|
|
||||||
|
|
||||||
- Update checks are disabled (`CODER_UPDATE_CHECK=false`).
|
|
||||||
- Telemetry data is not collected (`CODER_TELEMETRY_ENABLE=false`).
|
|
||||||
- Direct connections are not possible, workspace traffic is relayed through
|
|
||||||
control plane's DERP proxy.
|
|
||||||
|
|
||||||
##### Workload supporting resources
|
|
||||||
|
|
||||||
**Self-hosted Database**
|
|
||||||
|
|
||||||
- In the air-gapped deployment model, _Coderd_ instance is unable to download
|
|
||||||
Postgres binaries from the internet, so external database must be provided.
|
|
||||||
|
|
||||||
**Container Registry**
|
|
||||||
|
|
||||||
- Since the _Registry_ is isolated from the internet, platform engineers are
|
|
||||||
responsible for maintaining Workspace container images and conducting periodic
|
|
||||||
updates of base Docker images.
|
|
||||||
- It is recommended to keep [Dev Containers](../templates/dev-containers.md) up
|
|
||||||
to date with the latest released
|
|
||||||
[Envbuilder](https://github.com/coder/envbuilder) runtime.
|
|
||||||
|
|
||||||
**Mirror of Terraform Registry**
|
|
||||||
|
|
||||||
- Stores all necessary Terraform plugin dependencies, ensuring successful
|
|
||||||
workspace provisioning and maintenance without internet access.
|
|
||||||
- Platform engineers are responsible for periodically updating the mirrored
|
|
||||||
Terraform plugins, including
|
|
||||||
[terraform-provider-coder](https://github.com/coder/terraform-provider-coder).
|
|
||||||
|
|
||||||
**Certificate Authority**
|
|
||||||
|
|
||||||
- Manages and issues TLS certificates to facilitate secure communication
|
|
||||||
channels within the infrastructure.
|
|
||||||
|
|
||||||
### Dev Containers
|
|
||||||
|
|
||||||
This architecture enhances a Coder workspace with a
|
|
||||||
[development container](https://containers.dev/) setup built using the
|
|
||||||
[envbuilder](https://github.com/coder/envbuilder) project. Workspace users have
|
|
||||||
the flexibility to extend generic, base developer environments with custom,
|
|
||||||
project-oriented [features](https://containers.dev/features) without requiring
|
|
||||||
platform administrators to push altered Docker images.
|
|
||||||
|
|
||||||
Learn more about
|
|
||||||
[Dev containers support](https://coder.com/docs/templates/dev-containers) in
|
|
||||||
Coder.
|
|
||||||
|
|
||||||

|
|
||||||
|
|
||||||
#### Components
|
|
||||||
|
|
||||||
The deployment model includes:
|
|
||||||
|
|
||||||
- _Workspace_ built using Coder template with _envbuilder_ enabled to set up the
|
|
||||||
developer environment accordingly to the dev container spec.
|
|
||||||
- _Container Registry_ for Docker images used by _envbuilder_, maintained by
|
|
||||||
Coder platform engineers or developer productivity engineers.
|
|
||||||
|
|
||||||
Since this model is strictly focused on workspace nodes, it does not affect the
|
|
||||||
setup of regional infrastructure. It can be deployed alongside other deployment
|
|
||||||
models, in multiple regions, or across various cloud platforms.
|
|
||||||
|
|
||||||
##### Workload resources
|
|
||||||
|
|
||||||
**Coder workspace**
|
|
||||||
|
|
||||||
- Docker and Kubernetes based templates are supported.
|
|
||||||
- The `docker_container` resource uses `ghcr.io/coder/envbuilder` as the base
|
|
||||||
image.
|
|
||||||
|
|
||||||
_Envbuilder_ checks out the base Docker image from the container registry and
|
|
||||||
installs selected features as specified in the `devcontainer.json` on top.
|
|
||||||
Eventually, it starts the container with the developer environment.
|
|
||||||
|
|
||||||
##### Workload supporting resources
|
|
||||||
|
|
||||||
**Container Registry (optional)**
|
|
||||||
|
|
||||||
- Workspace nodes need access to the Container Registry to check out images. To
|
|
||||||
shorten the provisioning time, it is recommended to deploy registry mirrors in
|
|
||||||
the same region as the workspace nodes.
|
|
@ -61,12 +61,16 @@ ben@coder.com!
|
|||||||
popular IDEs (#8722) (@BrunoQuaresma)
|
popular IDEs (#8722) (@BrunoQuaresma)
|
||||||

|

|
||||||
- [Kubernetes log streaming](https://coder.com/docs/platforms/kubernetes/deployment-logs):
|
- [Kubernetes log streaming](https://coder.com/docs/platforms/kubernetes/deployment-logs):
|
||||||
Stream Kubernetes event logs to the Coder agent logs to reveal Kuernetes-level
|
Stream Kubernetes event logs to the Coder agent logs to reveal Kuernetes-level
|
||||||
issues such as ResourceQuota limitations, invalid images, etc.
|
issues such as ResourceQuota limitations, invalid images, etc.
|
||||||

|

|
||||||
- [OIDC Role Sync](https://coder.com/docs/admin/auth#group-sync-enterprise-premium)
|
<!-- markdown-link-check-disable -->
|
||||||
|
- [OIDC Role Sync](https://coder.com/docs/admin/users/oidc-auth.md#group-sync-enterprise-premium)
|
||||||
|
|
||||||
(Enterprise): Sync roles from your OIDC provider to Coder roles (e.g.
|
(Enterprise): Sync roles from your OIDC provider to Coder roles (e.g.
|
||||||
`Template Admin`) (#8595) (@Emyrk)
|
`Template Admin`) (#8595) (@Emyrk)
|
||||||
|
<!-- markdown-link-check-enable -->
|
||||||
|
|
||||||
- Users can convert their accounts from username/password authentication to SSO
|
- Users can convert their accounts from username/password authentication to SSO
|
||||||
by linking their account (#8742) (@Emyrk)
|
by linking their account (#8742) (@Emyrk)
|
||||||

|

|
||||||
@ -82,7 +86,7 @@ ben@coder.com!
|
|||||||
- CLI: Added `--var` shorthand for `--variable` in
|
- CLI: Added `--var` shorthand for `--variable` in
|
||||||
`coder templates <create/push>` CLI (#8710) (@ammario)
|
`coder templates <create/push>` CLI (#8710) (@ammario)
|
||||||
- Sever logs: Added fine-grained
|
- Sever logs: Added fine-grained
|
||||||
[filtering](https://coder.com/docs/cli/server#-l---log-filter) with
|
[filtering](https://coder.com/docs/reference/cli/server#-l---log-filter) with
|
||||||
Regex (#8748) (@ammario)
|
Regex (#8748) (@ammario)
|
||||||
- d3991fac2 feat(coderd): add parameter insights to template insights (#8656)
|
- d3991fac2 feat(coderd): add parameter insights to template insights (#8656)
|
||||||
(@mafredri)
|
(@mafredri)
|
||||||
|
@ -17,7 +17,7 @@
|
|||||||
[display apps](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#nested-schema-for-display_apps)
|
[display apps](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#nested-schema-for-display_apps)
|
||||||
in your template, such as VS Code (Insiders), web terminal, SSH, etc. (#9100)
|
in your template, such as VS Code (Insiders), web terminal, SSH, etc. (#9100)
|
||||||
(@sreya) To add VS Code insiders into your template, you can set:
|
(@sreya) To add VS Code insiders into your template, you can set:
|
||||||
```hcl
|
```tf
|
||||||
display_apps {
|
display_apps {
|
||||||
vscode_insiders = true
|
vscode_insiders = true
|
||||||
}
|
}
|
||||||
@ -51,9 +51,12 @@
|
|||||||
|
|
||||||
### Documentation
|
### Documentation
|
||||||
|
|
||||||
|
<!-- markdown-link-check-disable -->
|
||||||
|
|
||||||
- Add
|
- Add
|
||||||
[JetBrains Gateway Offline Mode](https://coder.com/docs/ides/gateway#jetbrains-gateway-in-an-offline-environment)
|
[JetBrains Gateway Offline Mode](https://coder.com/docs/user-guides/workspace-access/jetbrains.md#jetbrains-gateway-in-an-offline-environment)
|
||||||
config steps (#9388) (@ericpaulsen)
|
config steps (#9388) (@ericpaulsen)
|
||||||
|
<!-- markdown-link-check-enable -->
|
||||||
- Describe
|
- Describe
|
||||||
[dynamic options and locals for parameters](https://github.com/coder/coder/tree/main/examples/parameters-dynamic-options)
|
[dynamic options and locals for parameters](https://github.com/coder/coder/tree/main/examples/parameters-dynamic-options)
|
||||||
(#9429) (@mtojek)
|
(#9429) (@mtojek)
|
||||||
|
@ -133,7 +133,7 @@ The following features are hidden or disabled by default as we don't guarantee s
|
|||||||
### Documentation
|
### Documentation
|
||||||
|
|
||||||
- Fix /audit & /insights params (#12043) (@ericpaulsen)
|
- Fix /audit & /insights params (#12043) (@ericpaulsen)
|
||||||
- Fix jetbrains reconnect faq (#12073) (@ericpaulsen)
|
- Fix JetBrains gateway reconnect faq (#12073) (@ericpaulsen)
|
||||||
- Update modules documentation (#11911) (@matifali)
|
- Update modules documentation (#11911) (@matifali)
|
||||||
- Add kubevirt coder template in list of community templates (#12113) (@sulo1337)
|
- Add kubevirt coder template in list of community templates (#12113) (@sulo1337)
|
||||||
- Describe resource ordering in UI (#12185) (@mtojek)
|
- Describe resource ordering in UI (#12185) (@mtojek)
|
||||||
|
99
docs/ides.md
99
docs/ides.md
@ -1,99 +0,0 @@
|
|||||||
# IDEs
|
|
||||||
|
|
||||||
The following desktop IDEs have been tested with Coder, though any IDE with SSH
|
|
||||||
support should work:
|
|
||||||
|
|
||||||
- [Visual Studio Code](#visual-studio-code)
|
|
||||||
- [JetBrains with Gateway](./ides/gateway.md)
|
|
||||||
- IntelliJ IDEA
|
|
||||||
- CLion
|
|
||||||
- GoLand
|
|
||||||
- PyCharm
|
|
||||||
- Rider
|
|
||||||
- RubyMine
|
|
||||||
- WebStorm
|
|
||||||
- [JetBrains Fleet](./ides/fleet.md)
|
|
||||||
- Web IDEs (code-server, JupyterLab, JetBrains Projector)
|
|
||||||
- Note: These are [configured in the template](./ides/web-ides.md)
|
|
||||||
- [Emacs](./ides/emacs-tramp.md)
|
|
||||||
|
|
||||||
## Visual Studio Code
|
|
||||||
|
|
||||||
Click `VS Code Desktop` in the dashboard to one-click enter a workspace. This
|
|
||||||
automatically installs the [Coder Remote](https://github.com/coder/vscode-coder)
|
|
||||||
extension, authenticates with Coder, and connects to the workspace.
|
|
||||||
|
|
||||||

|
|
||||||
|
|
||||||
You can set the default directory in which VS Code opens via the `dir` argument
|
|
||||||
on the `coder_agent` resource in your workspace template. See the
|
|
||||||
[Terraform documentation for more details](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#dir).
|
|
||||||
|
|
||||||
> The `VS Code Desktop` button can be hidden by enabling
|
|
||||||
> [Browser-only connections](./networking/index.md#Browser-only).
|
|
||||||
|
|
||||||
### Manual Installation
|
|
||||||
|
|
||||||
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press
|
|
||||||
enter.
|
|
||||||
|
|
||||||
```text
|
|
||||||
ext install coder.coder-remote
|
|
||||||
```
|
|
||||||
|
|
||||||
Alternatively, manually install the VSIX from the
|
|
||||||
[latest release](https://github.com/coder/vscode-coder/releases/latest).
|
|
||||||
|
|
||||||
## SSH configuration
|
|
||||||
|
|
||||||
> Before proceeding, run `coder login <accessURL>` if you haven't already to
|
|
||||||
> authenticate the CLI with the web UI and your workspaces.
|
|
||||||
|
|
||||||
To access Coder via SSH, run the following in the terminal:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
coder config-ssh
|
|
||||||
```
|
|
||||||
|
|
||||||
> Run `coder config-ssh --dry-run` if you'd like to see the changes that will be
|
|
||||||
> made before proceeding.
|
|
||||||
|
|
||||||
Confirm that you want to continue by typing **yes** and pressing enter. If
|
|
||||||
successful, you'll see the following message:
|
|
||||||
|
|
||||||
```console
|
|
||||||
You should now be able to ssh into your workspace.
|
|
||||||
For example, try running:
|
|
||||||
|
|
||||||
$ ssh coder.<workspaceName>
|
|
||||||
```
|
|
||||||
|
|
||||||
Your workspace is now accessible via `ssh coder.<workspace_name>` (e.g.,
|
|
||||||
`ssh coder.myEnv` if your workspace is named `myEnv`).
|
|
||||||
|
|
||||||
## JetBrains Gateway
|
|
||||||
|
|
||||||
Gateway operates in a client-server model, using an SSH connection to the remote
|
|
||||||
host to install and start the server.
|
|
||||||
|
|
||||||
Setting up Gateway also involves picking a project directory, so if you have not
|
|
||||||
already done so, you may wish to open a terminal on your Coder workspace and
|
|
||||||
check out a copy of the project you intend to work on.
|
|
||||||
|
|
||||||
After installing Gateway on your local system,
|
|
||||||
[follow these steps to create a Connection and connect to your Coder workspace.](./ides/gateway.md)
|
|
||||||
|
|
||||||
| Version | Status | Notes |
|
|
||||||
| --------- | ------- | -------------------------------------------------------- |
|
|
||||||
| 2021.3.2 | Working | |
|
|
||||||
| 2022.1.4 | Working | Windows clients are unable to connect to Linux workspace |
|
|
||||||
| 2022.2 RC | Working | Version >= 222.3345.108 |
|
|
||||||
|
|
||||||
## Web IDEs (Jupyter, code-server, JetBrains Projector)
|
|
||||||
|
|
||||||
Web IDEs (code-server, JetBrains Projector, VNC, etc.) are defined in the
|
|
||||||
template. See [IDEs](./ides/web-ides.md).
|
|
||||||
|
|
||||||
## Up next
|
|
||||||
|
|
||||||
- Learn about [Port Forwarding](./networking/port-forwarding.md)
|
|
@ -1,25 +0,0 @@
|
|||||||
# JetBrains Fleet
|
|
||||||
|
|
||||||
JetBrains Fleet is a code editor and lightweight IDE designed to support various
|
|
||||||
programming languages and development environments.
|
|
||||||
|
|
||||||
[See JetBrains' website to learn about Fleet](https://www.jetbrains.com/fleet/)
|
|
||||||
|
|
||||||
Fleet can connect to a Coder workspace by following these steps.
|
|
||||||
|
|
||||||
1. [Install Fleet](https://www.jetbrains.com/fleet/download)
|
|
||||||
2. Install Coder CLI
|
|
||||||
```shell
|
|
||||||
curl -L https://coder.com/install.sh | sh
|
|
||||||
```
|
|
||||||
3. Login and configure Coder SSH.
|
|
||||||
```shell
|
|
||||||
coder login coder.example.com
|
|
||||||
coder config-ssh
|
|
||||||
```
|
|
||||||
4. Connect via SSH with the Host set to `coder.workspace-name`
|
|
||||||

|
|
||||||
|
|
||||||
> If you experience problems, please
|
|
||||||
> [create a GitHub issue](https://github.com/coder/coder/issues) or share in
|
|
||||||
> [our Discord channel](https://discord.gg/coder).
|
|
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user