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>

.github/workflows/typos.toml

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

.vscode/settings.json

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

Makefile

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

docs/CONTRIBUTING.md

@@ -315,6 +315,9 @@ Breaking changes can be triggered in two ways:
 
 ### Security
 
+> If you find a vulnerability, **DO NOT FILE AN ISSUE**. Instead, send an email
+> to security@coder.com.
+
 The
 [`security`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Asecurity)
 label can be added to PRs that have, or will be, merged into `main`. Doing so

docs/README.md

@@ -1,5 +1,7 @@
 # About Coder
 
+<!-- Warning for docs contributors: The first route in manifest.json must be titled "About" for the static landing page to work correctly.  -->
+
 Coder is an open-source platform for creating and managing developer workspaces
 on your preferred clouds and servers.
 
@@ -7,7 +9,10 @@ on your preferred clouds and servers.
   <img src="./images/hero-image.png">
 </p>
 
-By building on top of common development interfaces (SSH) and infrastructure tools (Terraform), Coder aims to make the process of **provisioning** and **accessing** remote workspaces approachable for organizations of various sizes and stages of cloud-native maturity.
+By building on top of common development interfaces (SSH) and infrastructure
+tools (Terraform), Coder aims to make the process of **provisioning** and
+**accessing** remote workspaces approachable for organizations of various sizes
+and stages of cloud-native maturity.
 
 <blockquote class="warning">
   <p>
@@ -18,21 +23,28 @@ By building on top of common development interfaces (SSH) and infrastructure too
 ## How it works
 
 Coder workspaces are represented with Terraform, but no Terraform knowledge is
-required to get started. We have a database of pre-made templates built into the
+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">
   <img src="./images/providers-compute.png">
 </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
 
-You can use any Web IDE ([code-server](https://github.com/coder/code-server), [projector](https://github.com/JetBrains/projector-server), [Jupyter](https://jupyter.org/), etc.), [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/), [VS Code Remote](https://code.visualstudio.com/docs/remote/ssh-tutorial) or even a file sync such as [mutagen](https://mutagen.io/).
+You can use any [Web IDE](./admin/templates/extending-templates/web-ides.md)
+([code-server](https://github.com/coder/code-server),
+[projector](https://github.com/JetBrains/projector-server),
+[Jupyter](https://jupyter.org), etc.),
+[JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/),
+[VS Code Remote](https://code.visualstudio.com/docs/remote/ssh-tutorial) or even
+a file sync such as [mutagen](https://mutagen.io/).
 
 <p align="center">
   <img src="./images/ide-icons.svg" height=72>
@@ -41,11 +53,11 @@ You can use any Web IDE ([code-server](https://github.com/coder/code-server), [p
 ## Why remote development
 
 Migrating from local developer machines to workspaces hosted by cloud services
-is an [increasingly common solution for
+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
   development, such as IDE loading, code compilation and building, and the
@@ -80,8 +92,9 @@ layer of infrastructure control. This additional layer allows admins to:
 - Enable persistent workspaces, which are like local machines, but faster and
   hosted by a cloud service
 
-Coder includes [production-ready templates](https://github.com/coder/coder/tree/c6b1daabc5a7aa67bfbb6c89966d728919ba7f80/examples/templates) for use with AWS EC2,
+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_
 
@@ -99,10 +112,5 @@ Azure, Google Cloud, Kubernetes, and more.
 - Coder is not a collaboration platform. You can use git and dedicated IDE
   extensions for pull requests, code reviews, and pair programming.
 
-- Coder is not a SaaS/fully-managed offering. You must host
+- Coder 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)

docs/admin/README.md

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

docs/admin/app-logs.md

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

docs/admin/external-auth.md

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

docs/admin/groups.md

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

docs/admin/index.md

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

docs/admin/infrastructure/architecture.md

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

docs/admin/infrastructure/index.md

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

docs/admin/infrastructure/scale-testing.md

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

docs/admin/infrastructure/scale-utility.md

@@ -6,15 +6,15 @@ infrastructure. For scale-testing Kubernetes clusters we recommend to install
 and use the dedicated Coder template,
 [scaletest-runner](https://github.com/coder/coder/tree/main/scaletest/templates/scaletest-runner).
 
-Learn more about [Coder’s architecture](../../architecture/architecture.md) and
+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
 
 > Note: the below information is for reference purposes only, and are not
 > intended to be used as guidelines for infrastructure sizing. Review the
-> [Reference Architectures](../../architecture/validated-arch.md#node-sizing)
+> [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  |
 | ---------------- | --------- | --------- | -------------- | ----------------- | ----- | ----------------- | ------------------------------------- | ------------- | ------------ |
@@ -249,6 +249,7 @@ an annotation on the coderd deployment.
 ## Troubleshooting
 
 If a load test fails or if you are experiencing performance issues during
-day-to-day use, you can leverage Coder's [Prometheus metrics](../prometheus.md)
+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.

docs/admin/infrastructure/validated-architectures/index.md

@@ -61,18 +61,19 @@ by default.
 
 ### 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
 web interface, the CLI tool, or directly calling API methods.
 
 ### 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
 `code-server`, facilitating collaboration and remote access. Additionally,
@@ -82,22 +83,24 @@ Coder templates and deployed on resources created by provisioners.
 
 ### Template
 
-A [template](../templates/index.md) in Coder is a predefined configuration for
+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
 
-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
 
@@ -161,7 +164,7 @@ compute as users start/stop workspaces at the beginning and end of their day.
 Set nodeSelectors, affinities, and tolerations in Coder templates to assign
 workspaces to the given node group:
 
-```hcl
+```tf
 resource "kubernetes_deployment" "coder" {
   spec {
     template {
@@ -212,11 +215,11 @@ resource "kubernetes_deployment" "coder" {
 
 For sizing recommendations, see the below reference architectures:
 
-- [Up to 1,000 users](./1k-users.md)
+- [Up to 1,000 users](1k-users.md)
 
-- [Up to 2,000 users](./2k-users.md)
+- [Up to 2,000 users](2k-users.md)
 
-- [Up to 3,000 users](./3k-users.md)
+- [Up to 3,000 users](3k-users.md)
 
 ### Networking
 
@@ -297,8 +300,9 @@ considerations:
   active users.
 - Enable High Availability mode for database engine for large scale deployments.
 
-If you enable [database encryption](../admin/encryption.md) in Coder, consider
+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
 
@@ -320,27 +324,25 @@ could affect workspace users experience once the platform is live.
 
 ### Helm Chart Configuration
 
-1. Reference our [Helm chart values file](../../helm/coder/values.yaml) and
+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. Determine the necessary environment variables. Here is the
-   [full list of supported server environment variables](../reference/cli/server.md).
+   [full list of supported server environment variables](../../../reference/cli/server.md).
 1. Follow our documented
-   [steps for installing Coder via Helm](../install/kubernetes.md).
+   [steps for installing Coder via Helm](../../../install/kubernetes.md).
 
 ### Template configuration
 
 1. Establish dedicated accounts for users with the _Template Administrator_
    role.
 1. Maintain Coder templates using
-   [version control](../templates/change-management.md) and the
+   [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
    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
-   [automatic template updates](../templates/general-settings.md#require-automatic-updates-enterprise)
+   [automatic template updates](../../templates/managing-templates/index.md#template-update-policies-enterprise-premium)
    upon workspace startup.
 
 ### Observability
@@ -352,12 +354,12 @@ could affect workspace users experience once the platform is live.
    leverage pre-configured dashboards, alerts, and runbooks for monitoring
    Coder. This includes integrations between Prometheus, Grafana, Loki, and
    Alertmanager.
-1. Review the [Prometheus response](../admin/prometheus.md) and set up alarms on
+1. Review the [Prometheus response](../../integrations/prometheus.md) and set up
-   selected metrics.
+   alarms on selected metrics.
 
 ### User support
 
-1. Incorporate [support links](../admin/appearance.md#support-links) into
+1. Incorporate [support links](../../setup/appearance.md#support-links) into
    internal documentation accessible from the user context menu. Ensure that
    hyperlinks are valid and lead to up-to-date materials.
 1. Encourage the use of `coder support bundle` to allow workspace users to

docs/admin/integrations/index.md

@@ -1,13 +1,18 @@
-# Other platforms
+# Integrations
 
 Coder is highly extensible and is not limited to the platforms outlined in these
 docs. The control plane can be provisioned on any VM or container compute, and
 workspaces can include any Terraform resource. See our
-[architecture documentation](../architecture/architecture.md) for more details.
+[architecture diagram](../infrastructure/architecture.md) for more details.
+
+You can host your deployment on almost any infrastructure. To learn how, read
+our [installation guides](../../install/index.md).
+
+<children></children>
 
 The following resources may help as you're deploying Coder.
 
 - [Coder packages: one-click install on cloud providers](https://github.com/coder/packages)
-- [Deploy Coder offline](../install/offline.md)
+- [Deploy Coder offline](../../install/offline.md)
 - [Supported resources (Terraform registry)](https://registry.terraform.io)
 - [Writing custom templates](../templates/index.md)

docs/admin/integrations/jfrog-artifactory.md

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

docs/admin/integrations/jfrog-xray.md

@@ -26,30 +26,29 @@ using Coder's [JFrog Xray Integration](https://github.com/coder/coder-xray).
    with a user that has the read
    [permission](https://jfrog.com/help/r/jfrog-platform-administration-documentation/permissions)
    for the repositories you want to scan.
-2. Create a Coder
+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
 
@@ -66,6 +65,6 @@ image = "<ARTIFACTORY_URL>/<REPO>/<IMAGE>:<TAG>"
 > create a
 > [Docker config](https://jfrog.com/help/r/jfrog-artifactory-documentation/docker-advanced-topics)
 > and use it in the `imagePullSecrets` field of the kubernetes pod. See this
-> [guide](./image-pull-secret.md) for more information.
+> [guide](../../tutorials/image-pull-secret.md) for more information.
 
-![JFrog Xray Integration](../images/guides/xray-integration/example.png)
+![JFrog Xray Integration](../../images/guides/xray-integration/example.png)

docs/admin/integrations/kubernetes-logs.md

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

docs/admin/integrations/multiple-kube-clusters.md

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

docs/admin/integrations/opentofu.md

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

docs/admin/integrations/prometheus.md

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

docs/admin/integrations/vault.md

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

docs/admin/licensing/index.md

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

docs/admin/monitoring/health-check.md

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

docs/admin/monitoring/index.md

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

docs/admin/monitoring/logs.md

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

docs/admin/monitoring/metrics.md

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

docs/admin/monitoring/notifications/index.md

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

docs/admin/monitoring/notifications/slack.md

@@ -17,8 +17,8 @@ consistent between Slack and their Coder login.
 Before setting up Slack notifications, ensure that you have the following:
 
 - Administrator access to the Slack platform to create apps
-- Coder platform with
+- 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
 
@@ -90,11 +90,9 @@ receiver.router.post("/v1/webhook", async (req, res) => {
 			return res.status(400).send("Error: request body is missing");
 		}
 
-		const { title_markdown, body_markdown } = req.body;
+		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;
@@ -120,11 +118,11 @@ receiver.router.post("/v1/webhook", async (req, res) => {
 			blocks: [
 				{
 					type: "header",
-					text: { type: "mrkdwn", text: title_markdown },
+					text: { type: "plain_text", text: title },
 				},
 				{
 					type: "section",
-					text: { type: "mrkdwn", text: body_markdown },
+					text: { type: "mrkdwn", text: body },
 				},
 			],
 		};
@@ -194,12 +192,9 @@ must respond appropriately.
 
 ## Enable Webhook Integration in Coder
 
-To enable webhook integration in Coder, ensure the "notifications" experiment is
+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:
 

docs/admin/monitoring/notifications/teams.md

@@ -15,7 +15,7 @@ Before setting up Microsoft Teams notifications, ensure that you have the
 following:
 
 - Administrator access to the Teams platform
-- Coder platform with notifications enabled
+- Coder platform with [notifications enabled](./index.md#enable-experiment)
 
 ## Build Teams Workflow
 
@@ -67,10 +67,10 @@ The process of setting up a Teams workflow consists of three key steps:
     				}
     			}
     		},
-    		"title_markdown": {
+    		"title": {
     			"type": "string"
     		},
-    		"body_markdown": {
+    		"body": {
     			"type": "string"
     		}
     	}
@@ -108,11 +108,11 @@ The process of setting up a Teams workflow consists of three key steps:
     		},
     		{
     			"type": "TextBlock",
-    			"text": "**@{replace(body('Parse_JSON')?['title_markdown'], '"', '\"')}**"
+    			"text": "**@{replace(body('Parse_JSON')?['title'], '"', '\"')}**"
     		},
     		{
     			"type": "TextBlock",
-    			"text": "@{replace(body('Parse_JSON')?['body_markdown'], '"', '\"')}",
+    			"text": "@{replace(body('Parse_JSON')?['body'], '"', '\"')}",
     			"wrap": true
     		},
     		{
@@ -133,12 +133,9 @@ The process of setting up a Teams workflow consists of three key steps:
 
 ## Enable Webhook Integration
 
-To enable webhook integration in Coder, ensure the "notifications" experiment is
+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:
 

docs/admin/networking/high-availability.md

@@ -32,10 +32,9 @@ connect to the same Postgres endpoint.
 HA brings one configuration variable to set in each Coderd node:
 `CODER_DERP_SERVER_RELAY_URL`. The HA nodes use these URLs to communicate with
 each other. Inter-node communication is only required while using the embedded
-relay (default). If you're using
+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_ACCESS_URL` is a load balancer to all Coder nodes.
@@ -51,7 +50,7 @@ Here's an example 3-node network configuration setup:
 ## Kubernetes
 
 If you installed Coder via
-[our Helm Chart](../install/kubernetes.md#install-coder-with-helm), just
+[our Helm Chart](../../install/kubernetes.md#4-install-coder-with-helm), just
 increase `coder.replicaCount` in `values.yaml`.
 
 If you installed Coder into Kubernetes by some other means, insert the relay URL
@@ -71,5 +70,5 @@ Then, increase the number of pods.
 
 ## Up next
 
-- [Networking](../networking/index.md)
+- [Read more on Coder's networking stack](./index.md)
-- [Kubernetes](../install/kubernetes.md)
+- [Install on Kubernetes](../../install/kubernetes.md)

docs/admin/networking/index.md

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

docs/admin/networking/port-forwarding.md

@@ -49,10 +49,10 @@ For more examples, see `coder port-forward --help`.
 ## Dashboard
 
 > To enable port forwarding via the dashboard, Coder must be configured with a
-> [wildcard access URL](../admin/configure.md#wildcard-access-url). If an access
+> [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
 > [DNS limitation](https://datatracker.ietf.org/doc/html/rfc1035#section-2.3.1)
@@ -67,7 +67,7 @@ workspace's template. This approach shows a visual application icon in the
 dashboard. See the following `coder_app` example for a Node React app and note
 the `subdomain` and `share` settings:
 
-```hcl
+```tf
 # node app
 resource "coder_app" "node-react-app" {
   agent_id  = coder_agent.dev.id
@@ -90,7 +90,7 @@ Valid `share` values include `owner` - private to the user, `authenticated` -
 accessible by any user authenticated to the Coder deployment, and `public` -
 accessible by users outside of the Coder deployment.
 
-![Port forwarding from an app in the UI](../images/networking/portforwarddashboard.png)
+![Port forwarding from an app in the UI](../../images/networking/portforwarddashboard.png)
 
 ## Accessing workspace ports
 
@@ -99,7 +99,7 @@ to specify an arbitrary port. Coder will also detect if apps inside the
 workspace are listening on ports, and list them below the port input (this is
 only supported on Windows and Linux workspace agents).
 
-![Port forwarding in the UI](../images/networking/listeningports.png)
+![Port forwarding in the UI](../../images/networking/listeningports.png)
 
 ### Sharing ports
 
@@ -118,7 +118,7 @@ Once a port is shared at either `authenticated` or `public` levels, it will stay
 pinned in the open ports UI for better accessibility regardless of whether or
 not it is still accessible.
 
-![Annotated port controls in the UI](../images/networking/annotatedports.png)
+![Annotated port controls in the UI](../../images/networking/annotatedports.png)
 
 The sharing level is limited by the maximum level enforced in the template
 settings in enterprise deployments, and not restricted in OSS deployments.
@@ -137,7 +137,7 @@ maximum sharing level is set to `Owner`, meaning port sharing is disabled for
 end-users. OSS deployments allow all workspaces to share ports at both the
 `authenticated` and `public` levels.
 
-![Max port sharing level in the UI](../images/networking/portsharingmax.png)
+![Max port sharing level in the UI](../../images/networking/portsharingmax.png)
 
 ### Configuring port protocol
 
@@ -274,8 +274,9 @@ configurable by either admins or users.
 
 ## SSH
 
-First, [configure SSH](../ides.md#ssh-configuration) on your local machine.
+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
 ssh -L 8080:localhost:8000 coder.myworkspace

docs/admin/networking/stun.md

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

docs/admin/networking/workspace-proxies.md

@@ -4,15 +4,16 @@ Workspace proxies provide low-latency experiences for geo-distributed teams.
 
 Coder's networking does a best effort to make direct connections to a workspace.
 In situations where this is not possible, such as connections via the web
-terminal and [web IDEs](../ides/web-ides.md), workspace proxies are able to
+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
 connecting with their workspace over SSH, a workspace app, port forwarding, etc.
 Dashboard connections and API calls (e.g. the workspaces list) are not served
 over workspace proxies.
 
-![ProxyDiagram](../images/workspaceproxy/proxydiagram.png)
+![ProxyDiagram](../../images/admin/networking/workspace-proxies/proxydiagram.png)
 
 # Deploy a workspace proxy
 
@@ -26,12 +27,8 @@ Workspace proxies can be used in the browser by navigating to the user
 
 ## Requirements
 
-- The [Coder CLI](../reference/cli) must be installed and authenticated as a
+- 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
 
@@ -61,7 +58,7 @@ the workspace proxy usable. If the proxy deployment is successful,
 
 ```
 $ coder wsproxy ls
-NAME              URL                           STATUS STATUS
+NAME              URL                         STATUS STATUS
 brazil-saopaulo   https://brazil.example.com  ok
 europe-frankfurt  https://europe.example.com  ok
 sydney            https://sydney.example.com  ok
@@ -153,8 +150,8 @@ coder wsproxy server
 
 ### Running as a system service
 
-If you've installed Coder via a [system package](../install/index.md), you can
+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`
 
 To run workspace proxy as a system service on the host:
@@ -202,49 +199,6 @@ FROM ghcr.io/coder/coder:latest
 ENTRYPOINT ["/opt/coder", "wsproxy", "server"]
 ```
 
-### Managing via Terraform
-
-The
-[coderd Terraform Provider](https://registry.terraform.io/providers/coder/coderd/latest)
-can also be used to create and manage workspace proxies in the same Terraform
-configuration as your deployment.
-
-```hcl
-
-provider "coderd" {
-	url   = "https://coder.example.com"
-	token = "****"
-}
-
-resource "coderd_workspace_proxy" "sydney-wsp" {
-  name         = "sydney-wsp"
-  display_name = "Australia (Sydney)"
-  icon         = "/emojis/1f1e6-1f1fa.png"
-}
-resource "kubernetes_deployment" "syd_wsproxy" {
-  metadata { /* ... */ }
-  spec {
-    template {
-      metadata { /* ... */ }
-      spec {
-        container {
-          name  = "syd-wsp"
-          image = "ghcr.io/coder/coder:latest"
-          args  = ["wsproxy", "server"]
-          env {
-            name  = "CODER_PROXY_SESSION_TOKEN"
-            value = coderd_workspace_proxy.sydney-wsp.session_token
-          }
-          /* ... */
-        }
-        /* ... */
-      }
-    }
-    /* ... */
-  }
-}
-```
-
 ### Selecting a proxy
 
 Users can select a workspace proxy at the top-right of the browser-based Coder
@@ -252,9 +206,9 @@ dashboard. Workspace proxy preferences are cached by the web browser. If a proxy
 goes offline, the session will fall back to the primary proxy. This could take
 up to 60 seconds.
 
-![Workspace proxy picker](../images/admin/workspace-proxy-picker.png)
+![Workspace proxy picker](../../images/admin/networking/workspace-proxies/ws-proxy-picker.png)
 
-## Step 3: Observability
+## Observability
 
 Coder workspace proxy exports metrics via the HTTP endpoint, which can be
 enabled using either the environment variable `CODER_PROMETHEUS_ENABLE` or the

docs/admin/provisioners.md

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

docs/admin/rbac.md

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

docs/admin/security/audit-logs.md

@@ -6,7 +6,7 @@ Audit Logs allows **Auditors** to monitor user operations in their deployment.
 
 We track the following resources:
 
-<!-- Code generated by 'make docs/admin/audit-logs.md'. DO NOT EDIT -->
+<!-- Code generated by 'make docs/admin/security/audit-logs.md'. DO NOT EDIT -->
 
 | <b>Resource<b>                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -30,7 +30,7 @@ We track the following resources:
 | WorkspaceBuild<br><i>start, stop</i>                     | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>build_number</td><td>false</td></tr><tr><td>created_at</td><td>false</td></tr><tr><td>daily_cost</td><td>false</td></tr><tr><td>deadline</td><td>false</td></tr><tr><td>id</td><td>false</td></tr><tr><td>initiator_by_avatar_url</td><td>false</td></tr><tr><td>initiator_by_username</td><td>false</td></tr><tr><td>initiator_id</td><td>false</td></tr><tr><td>job_id</td><td>false</td></tr><tr><td>max_deadline</td><td>false</td></tr><tr><td>provisioner_state</td><td>false</td></tr><tr><td>reason</td><td>false</td></tr><tr><td>template_version_id</td><td>true</td></tr><tr><td>transition</td><td>false</td></tr><tr><td>updated_at</td><td>false</td></tr><tr><td>workspace_id</td><td>false</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | WorkspaceProxy<br><i></i>                                | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>created_at</td><td>true</td></tr><tr><td>deleted</td><td>false</td></tr><tr><td>derp_enabled</td><td>true</td></tr><tr><td>derp_only</td><td>true</td></tr><tr><td>display_name</td><td>true</td></tr><tr><td>icon</td><td>true</td></tr><tr><td>id</td><td>true</td></tr><tr><td>name</td><td>true</td></tr><tr><td>region_id</td><td>true</td></tr><tr><td>token_hashed_secret</td><td>true</td></tr><tr><td>updated_at</td><td>false</td></tr><tr><td>url</td><td>true</td></tr><tr><td>version</td><td>true</td></tr><tr><td>wildcard_hostname</td><td>true</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
-<!-- End generated by 'make docs/admin/audit-logs.md'. -->
+<!-- End generated by 'make docs/admin/security/audit-logs.md'. -->
 
 ## Filtering logs
 
@@ -70,15 +70,15 @@ audit trails.
 
 Audit logs can be accessed through our REST API. You can find detailed
 information about this in our
-[endpoint documentation](../reference/api/audit.md#get-audit-logs).
+[endpoint documentation](../../reference/api/audit.md#get-audit-logs).
 
 ## Service Logs
 
 Audit trails are also dispatched as service logs and can be captured and
 categorized using any log management tool such as [Splunk](https://splunk.com).
 
-Example of a [JSON formatted](../reference/cli/server.md#--log-json) audit log
+Example of a [JSON formatted](../../reference/cli/server.md#--log-json) audit
-entry:
+log entry:
 
 ```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
 2023-06-13 03:43:29.233 [info]  coderd: audit_log  ID=95f7c392-da3e-480c-a579-8909f145fbe2  Time="2023-06-13T03:43:29.230422Z"  UserID=6c405053-27e3-484a-9ad7-bcb64e7bfde6  OrganizationID=00000000-0000-0000-0000-000000000000  Ip=<nil>  UserAgent=<nil>  ResourceType=workspace_build  ResourceID=988ae133-5b73-41e3-a55e-e1e9d3ef0b66  ResourceTarget=""  Action=start  Diff="{}"  StatusCode=200  AdditionalFields="{\"workspace_name\":\"linux-container\",\"build_number\":\"7\",\"build_reason\":\"initiator\",\"workspace_owner\":\"\"}"  RequestID=9682b1b5-7b9f-4bf2-9a39-9463f8e41cd6  ResourceIcon=""
@@ -122,5 +122,5 @@ entry:
 
 ## Enabling this feature
 
-This feature is only available with a
+This feature is only available with an enterprise license.
-[Premium or Enterprise license](https://coder.com/pricing).
+[Learn more](../licensing/index.md)

docs/admin/security/database-encryption.md

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

docs/admin/security/index.md

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

docs/admin/security/secrets.md

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

docs/admin/setup/appearance.md

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

docs/admin/setup/index.md

@@ -1,6 +1,8 @@
+# Configure Control Plane Access
+
 Coder server's primary configuration is done via environment variables. For a
 full list of the options, run `coder server --help` or see our
-[CLI documentation](../reference/cli/server.md).
+[CLI documentation](../../reference/cli/server.md).
 
 ## Access URL
 
@@ -39,9 +41,8 @@ coder server
 
 `CODER_WILDCARD_ACCESS_URL` is necessary for
 [port forwarding](../networking/port-forwarding.md#dashboard) via the dashboard
-or running [coder_apps](../templates/index.md#coder-apps) on an absolute path.
+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
 
@@ -49,8 +50,8 @@ If you are providing TLS certificates directly to the Coder server, either
 2. Configure multiple certificates and keys via
    [`coder.tls.secretNames`](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
    in the Helm Chart, or
-   [`--tls-cert-file`](../reference/cli/server.md#--tls-cert-file) and
+   [`--tls-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
    and their respective keys in the same order).
 
@@ -60,9 +61,9 @@ The Coder server can directly use TLS certificates with `CODER_TLS_ENABLE` and
 accompanying configuration flags. However, Coder can also run behind a
 reverse-proxy to terminate TLS certificates from LetsEncrypt, for example.
 
-- [Apache](https://github.com/coder/coder/tree/main/examples/web-server/apache)
+- [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
 
@@ -129,63 +130,24 @@ steps:
 6. Start your Coder deployment with
    `CODER_PG_CONNECTION_URL=<external-connection-string>`.
 
-## System packages
-
-If you've installed Coder via a [system package](../install/index.md), you can
-configure the server by setting the following variables in
-`/etc/coder.d/coder.env`:
-
-```env
-# String. Specifies the external URL (HTTP/S) to access Coder.
-CODER_ACCESS_URL=https://coder.example.com
-
-# String. Address to serve the API and dashboard.
-CODER_HTTP_ADDRESS=0.0.0.0:3000
-
-# String. The URL of a PostgreSQL database to connect to. If empty, PostgreSQL binaries
-# will be downloaded from Maven (https://repo1.maven.org/maven2) and store all
-# data in the config root. Access the built-in database with "coder server postgres-builtin-url".
-CODER_PG_CONNECTION_URL=
-
-# Boolean. Specifies if TLS will be enabled.
-CODER_TLS_ENABLE=
-
-# If CODER_TLS_ENABLE=true, also set:
-CODER_TLS_ADDRESS=0.0.0.0:3443
-
-# String. Specifies the path to the certificate for TLS. It requires a PEM-encoded file.
-# To configure the listener to use a CA certificate, concatenate the primary
-# certificate and the CA certificate together. The primary certificate should
-# appear first in the combined file.
-CODER_TLS_CERT_FILE=
-
-# String. Specifies the path to the private key for the certificate. It requires a
-# PEM-encoded file.
-CODER_TLS_KEY_FILE=
-```
-
-To run Coder as a system service on the host:
-
-```shell
-# Use systemd to start Coder now and on reboot
-sudo systemctl enable --now coder
-
-# View the logs to ensure a successful start
-journalctl -u coder.service -b
-```
-
-To restart Coder after applying system changes:
-
-```shell
-sudo systemctl restart coder
-```
-
 ## Configuring Coder behind a proxy
 
 To configure Coder behind a corporate proxy, set the environment variables
 `HTTP_PROXY` and `HTTPS_PROXY`. Be sure to restart the server. Lowercase values
 (e.g. `http_proxy`) are also respected in this case.
 
+## External Authentication
+
+Coder supports external authentication via OAuth2.0. This allows enabling
+integrations with git providers, such as GitHub, GitLab, and Bitbucket etc.
+
+External authentication can also be used to integrate with external services
+like JFrog Artifactory and others.
+
+Please refer to the [external authentication](../external-auth.md) section for
+more information.
+
 ## Up Next
 
-- [Learn how to upgrade Coder](./upgrade.md).
+- [Learn how to setup and manage templates](../templates/index.md)
+- [Setup external provisioners](../provisioners.md)

docs/admin/setup/web-server/apache/index.md

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

docs/admin/setup/web-server/caddy/index.md

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

docs/admin/setup/web-server/nginx/index.md

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

docs/admin/templates/creating-templates.md

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

docs/admin/templates/extending-templates/agent-metadata.md

@@ -1,6 +1,6 @@
 # Agent metadata
 
-![agent-metadata](../images/agent-metadata.png)
+![agent-metadata](../../../images/admin/templates/agent-metadata-ui.png)
 
 You can show live operational metrics to workspace users with agent metadata. It
 is the dynamic complement of [resource metadata](./resource-metadata.md).
@@ -15,14 +15,14 @@ All of these examples use
 for the script declaration. With heredoc strings, you can script without messy
 escape codes, just as if you were working in your terminal.
 
-Some of the examples use the [`coder stat`](../reference/cli/stat.md) command.
+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:
 
-```hcl
+```tf
 resource "coder_agent" "main" {
   os             = "linux"
   ...

docs/admin/templates/extending-templates/docker-in-workspaces.md

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

docs/admin/templates/extending-templates/external-auth.md

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

docs/admin/templates/extending-templates/icons.md

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

docs/admin/templates/extending-templates/index.md

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

docs/admin/templates/extending-templates/modules.md

@@ -8,7 +8,7 @@ You can store these modules externally from your Coder deployment, like in a git
 repository or a Terraform registry. This example shows how to reference a module
 from your template:
 
-```hcl
+```tf
 data "coder_workspace" "me" {}
 
 module "coder-base" {
@@ -82,7 +82,7 @@ to resolve modules via [Artifactory](https://jfrog.com/artifactory/).
 5. Create a file `.terraformrc` with following content and mount at
    `/home/coder/.terraformrc` within the Coder provisioner.
 
-   ```hcl
+   ```tf
    provider_installation {
      direct {
          exclude = ["registry.terraform.io/*/*"]
@@ -95,7 +95,7 @@ to resolve modules via [Artifactory](https://jfrog.com/artifactory/).
 
 6. Update module source as,
 
-   ```hcl
+   ```tf
    module "module-name" {
      source = "https://example.jfrog.io/tf__coder/module-name/coder"
      version = "1.0.0"
@@ -111,14 +111,16 @@ Based on the instructions
 
 #### Example template
 
-We have an example template [here](../../examples/jfrog/remote/main.tf) that
+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
 
 If you are importing a module from a private git repository, the Coder server or
-[provisioner](../admin/provisioners.md) needs git credentials. Since this token
+[provisioner](../../provisioners.md) needs git credentials. Since this token
 will only be used for cloning your repositories with modules, it is best to
 create a token with access limited to the repository and no extra permissions.
 In GitHub, you can generate a
@@ -188,12 +190,9 @@ coder:
       readOnly: true
 ```
 
-### Next up
+### Next steps
 
-Learn more about
+- JFrog's
-
+  [Terraform Registry support](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)

docs/admin/templates/extending-templates/parameters.md

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

docs/admin/templates/extending-templates/process-logging.md

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

docs/admin/templates/extending-templates/resource-metadata.md

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

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

docs/admin/templates/extending-templates/resource-persistence.md

@@ -24,7 +24,7 @@ meta-argument.
 In this example, Coder will provision or tear down the `docker_container`
 resource:
 
-```hcl
+```tf
 data "coder_workspace" "me" {
 }
 
@@ -39,7 +39,7 @@ resource "docker_container" "workspace" {
 
 Take this example resource:
 
-```hcl
+```tf
 data "coder_workspace" "me" {
 }
 
@@ -57,7 +57,7 @@ To prevent this, use immutable IDs:
 - `coder_workspace.me.owner_id`
 - `coder_workspace.me.id`
 
-```hcl
+```tf
 data "coder_workspace" "me" {
 }
 
@@ -78,7 +78,7 @@ You can prevent Terraform from recreating a resource under any circumstance by
 setting the
 [`ignore_changes = all` directive in the `lifecycle` block](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#ignore_changes).
 
-```hcl
+```tf
 data "coder_workspace" "me" {
 }
 

docs/admin/templates/extending-templates/variables.md

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

docs/admin/templates/extending-templates/web-ides.md

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

docs/admin/templates/extending-templates/workspace-tags.md

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

docs/admin/templates/index.md

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

docs/admin/templates/managing-templates/change-management.md

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

docs/admin/templates/managing-templates/dependencies.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
 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
 > `.terraform.lock.hcl` into Git or other VCS.

docs/admin/templates/managing-templates/devcontainers.md

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

docs/admin/templates/managing-templates/image-management.md

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

docs/admin/templates/managing-templates/index.md

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

docs/admin/templates/managing-templates/schedule.md

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

docs/admin/templates/open-in-coder.md

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

docs/admin/templates/template-permissions.md

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

docs/admin/templates/troubleshooting.md

@@ -21,7 +21,7 @@ practices:
 
 - Ensure the resource has `curl` installed (alternatively, `wget` or `busybox`)
 - Ensure the resource can `curl` your Coder
-  [access URL](../admin/configure.md#access-url)
+  [access URL](../../admin/setup/index.md#access-url)
 - Manually connect to the resource and check the agent logs (e.g.,
   `kubectl exec`, `docker exec` or AWS console)
   - The Coder agent logs are typically stored in `/tmp/coder-agent.log`
@@ -31,7 +31,7 @@ practices:
     `/tmp/coder-shutdown-script.log`
 - This can also happen if the websockets are not being forwarded correctly when
   running Coder behind a reverse proxy.
-  [Read our reverse-proxy docs](../admin/configure.md#tls--reverse-proxy)
+  [Read our reverse-proxy docs](../../admin/setup/index.md#tls--reverse-proxy)
 
 ## Startup script issues
 

docs/admin/users/github-auth.md

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

docs/admin/users/groups-roles.md

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

docs/admin/users/headless-auth.md

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

docs/admin/users/idp-sync.md

@@ -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
 to synchronize groups in your auth provider to groups within Coder. To enable
 group sync, ensure that the `groups` claim is being sent by your OpenID
 provider. You might need to request an additional
-[scope](../reference/cli/server.md#--oidc-scopes) or additional configuration on
+[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
 provider. This means manual group additions/removals will be overwritten on the
@@ -283,7 +34,8 @@ the OIDC provider. See
 > ones include `groups`, `memberOf`, and `roles`.
 
 Next configure the Coder server to read groups from the claim name with the
-[OIDC group field](../reference/cli/server.md#--oidc-group-field) server flag:
+[OIDC group field](../../reference/cli/server.md#--oidc-group-field) server
+flag:
 
 ```sh
 # as an environment variable
@@ -301,7 +53,7 @@ names in Coder and removed from groups that the user no longer belongs to.
 For cases when an OIDC provider only returns group IDs ([Azure AD][azure-gids])
 or you want to have different group names in Coder than in your OIDC provider,
 you can configure mapping between the two with the
-[OIDC group mapping](../reference/cli/server.md#--oidc-group-mapping) server
+[OIDC group mapping](../../reference/cli/server.md#--oidc-group-mapping) server
 flag.
 
 ```sh
@@ -339,7 +91,7 @@ For deployments with multiple [organizations](./organizations.md), you must
 configure group sync at the organization level. In future Coder versions, you
 will be able to configure this in the UI. For now, you must use CLI commands.
 
-First confirm you have the [Coder CLI](../install/index.md) installed and are
+First confirm you have the [Coder CLI](../../install/index.md) installed and are
 logged in with a user who is an Owner or Organization Admin role. Next, confirm
 that your OIDC provider is sending a groups claim by logging in with OIDC and
 visiting the following URL:
@@ -420,7 +172,7 @@ coder organizations settings set group-sync \
 
 Visit the Coder UI to confirm these changes:
 
-![IDP Sync](../images/admin/organizations/group-sync.png)
+![IDP Sync](../../images/admin/users/organizations/group-sync.png)
 
 </div>
 
@@ -430,7 +182,7 @@ You can limit which groups from your identity provider can log in to Coder with
 [CODER_OIDC_ALLOWED_GROUPS](https://coder.com/docs/cli/server#--oidc-allowed-groups).
 Users who are not in a matching group will see the following error:
 
-![Unauthorized group error](../images/admin/group-allowlist.png)
+![Unauthorized group error](../../images/admin/group-allowlist.png)
 
 ## Role sync (enterprise) (premium)
 
@@ -460,10 +212,10 @@ the OIDC provider. See
 > Depending on the OIDC provider, this claim may be named differently.
 
 Next configure the Coder server to read groups from the claim name with the
-[OIDC role field](../reference/cli/server.md#--oidc-user-role-field) server
+[OIDC role field](../../reference/cli/server.md#--oidc-user-role-field) server
 flag:
 
-Set the following in your Coder server [configuration](./configure.md).
+Set the following in your Coder server [configuration](../setup/index.md).
 
 ```env
  # Depending on your identity provider configuration, you may need to explicitly request a "roles" scope
@@ -546,7 +298,7 @@ coder organizations settings set role-sync \
 
 Visit the Coder UI to confirm these changes:
 
-![IDP Sync](../images/admin/organizations/role-sync.png)
+![IDP Sync](../../images/admin/users/organizations/role-sync.png)
 
 </div>
 
@@ -575,7 +327,7 @@ the OIDC provider. See
 > ones include `groups`, `memberOf`, and `roles`.
 
 Next configure the Coder server to read groups from the claim name with the
-[OIDC organization field](../reference/cli/server.md#--oidc-organization-field)
+[OIDC organization field](../../reference/cli/server.md#--oidc-organization-field)
 server flag:
 
 ```sh
@@ -589,7 +341,7 @@ Next, fetch the corresponding organization IDs using the following endpoint:
 https://[coder.example.com]/api/v2/organizations
 ```
 
-Set the following in your Coder server [configuration](./configure.md).
+Set the following in your Coder server [configuration](../setup/index.md).
 
 ```env
 CODER_OIDC_ORGANIZATION_MAPPING='{"data-scientists":["d8d9daef-e273-49ff-a832-11fe2b2d4ab1", "70be0908-61b5-4fb5-aba4-4dfb3a6c5787"]}'
@@ -614,8 +366,8 @@ Some common issues when enabling group/role sync.
 
 If you are running into issues with group/role sync, is best to view your Coder
 server logs and enable
-[verbose mode](https://coder.com/docs/v2/v2.5.1/cli#-v---verbose). To reduce
+[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
 CODER_VERBOSE=true

docs/admin/users/index.md

@@ -1,48 +1,33 @@
 # 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
 
-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.
-
-![Custom roles](../images/admin/organizations/custom-roles.png)
-
-> Note: This requires a Premium license.
-> [Contact your account team](https://coder.com/contact) for more details.
-
-## Security notes
-
-A malicious Template Admin could write a template that executes commands on the
-host (or `coder server` container), which potentially escalates their privileges
-or shuts down the Coder server. To avoid this, run
-[external provisioners](./provisioners.md).
-
-In low-trust environments, we do not recommend giving users direct access to
-edit templates. Instead, use
-[CI/CD pipelines to update templates](../templates/change-management.md) with
-proper security scans and code reviews in place.
 
 ## User status
 

docs/admin/users/oidc-auth.md

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

docs/admin/users/organizations.md

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

docs/admin/users/password-auth.md

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

docs/admin/users/quotas.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
 workspaces. This budget limits the user to 3 concurrent workspaces.
 
-Quotas are licensed with [Groups](./groups.md).
+Quotas are scoped to [Groups](./groups-roles.md) in Enterprise and
+[organizations](./organizations.md) in Premium.
 
 ## Definitions
 
@@ -70,7 +71,7 @@ unused workspaces and freeing up compute in the cluster.
 Each group has a configurable Quota Allowance. A user's budget is calculated as
 the sum of their allowances.
 
-![group-settings](../images/admin/quota-groups.png)
+![group-settings](../../images/admin/users/quotas/quota-groups.png)
 
 For example:
 
@@ -98,8 +99,9 @@ process dynamically calculates costs, so quota violation fails builds as opposed
 to failing the build-triggering operation. For example, the Workspace Create
 Form will never get held up by quota enforcement.
 
-![build-log](../images/admin/quota-buildlog.png)
+![build-log](../../images/admin/quota-buildlog.png)
 
 ## Up next
 
-- [Configuring](./configure.md)
+- [Group Sync](./idp-sync.md)
+- [Control plane configuration](../setup/index.md)

docs/admin/users/sessions-tokens.md

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

docs/architecture/architecture.md

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

docs/changelogs/v2.0.0.md

@@ -61,12 +61,16 @@ ben@coder.com!
   popular IDEs (#8722) (@BrunoQuaresma)
   ![Template insights](https://user-images.githubusercontent.com/22407953/258239988-69641bd6-28da-4c60-9ae7-c0b1bba53859.png)
 - [Kubernetes log streaming](https://coder.com/docs/platforms/kubernetes/deployment-logs):
-  Stream Kubernetes event logs to the Coder agent logs to reveal Kuernetes-level
+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.
-  ![Kubernetes quota](https://raw.githubusercontent.com/coder/coder/main/docs/platforms/kubernetes/coder-logstream-kube-logs-quota-exceeded.png)
+![Kubernetes quota](https://raw.githubusercontent.com/coder/coder/main/docs/platforms/kubernetes/coder-logstream-kube-logs-quota-exceeded.png)
-- [OIDC Role Sync](https://coder.com/docs/admin/auth#group-sync-enterprise-premium)
+<!-- markdown-link-check-disable -->
+- [OIDC Role Sync](https://coder.com/docs/admin/users/oidc-auth.md#group-sync-enterprise-premium)
+
   (Enterprise): Sync roles from your OIDC provider to Coder roles (e.g.
   `Template Admin`) (#8595) (@Emyrk)
+  <!-- markdown-link-check-enable -->
+
 - Users can convert their accounts from username/password authentication to SSO
   by linking their account (#8742) (@Emyrk)
   ![Converting OIDC accounts](https://user-images.githubusercontent.com/22407953/257408767-5b136476-99d1-4052-aeec-fe2a42618e04.png)
@@ -82,7 +86,7 @@ ben@coder.com!
 - CLI: Added `--var` shorthand for `--variable` in
   `coder templates <create/push>` CLI (#8710) (@ammario)
 - Sever logs: Added fine-grained
-  [filtering](https://coder.com/docs/cli/server#-l---log-filter) with
+  [filtering](https://coder.com/docs/reference/cli/server#-l---log-filter) with
   Regex (#8748) (@ammario)
 - d3991fac2 feat(coderd): add parameter insights to template insights (#8656)
   (@mafredri)

docs/changelogs/v2.1.5.md

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

docs/changelogs/v2.9.0.md

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

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

docs/ides/fleet.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`
-   ![Fleet Connect to Coder](../images/fleet/ssh-connect-to-coder.png)
-
-> If you experience problems, please
-> [create a GitHub issue](https://github.com/coder/coder/issues) or share in
-> [our Discord channel](https://discord.gg/coder).