coder · matifali · Aug 13, 2024 · Aug 12, 2024 · Aug 12, 2024 · Aug 12, 2024
diff --git a/.gitattributes b/.gitattributes
@@ -1,7 +1,7 @@
 # Generated files
 coderd/apidoc/docs.go linguist-generated=true
-docs/api/*.md linguist-generated=true
-docs/cli/*.md linguist-generated=true
+docs/reference/api/*.md linguist-generated=true
+docs/reference/cli/*.md linguist-generated=true
 coderd/apidoc/swagger.json linguist-generated=true
 coderd/database/dump.sql linguist-generated=true
 peerbroker/proto/*.go linguist-generated=true

diff --git a/.prettierrc.yaml b/.prettierrc.yaml
@@ -9,8 +9,8 @@ tabWidth: 2
 overrides:
   - files:
       - README.md
-      - docs/api/**/*.md
-      - docs/cli/**/*.md
+      - docs/reference/api/**/*.md
+      - docs/reference/cli/**/*.md
       - docs/changelogs/*.md
       - .github/**/*.{yaml,yml,toml}
       - scripts/**/*.{yaml,yml,toml}

diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -196,7 +196,8 @@
     "**/*.gen.json": true,
     "**/testdata/*": true,
     "coderd/apidoc/**": true,
-    "docs/api/*.md": true,
+    "docs/reference/api/*.md": true,
+    "docs/reference/cli/*.md": true,
     "docs/templates/*.md": true,
     "LICENSE": true,
     "scripts/metricsdocgen/metrics": true,

diff --git a/Makefile b/Makefile
@@ -489,7 +489,7 @@ gen: \
 	codersdk/rbacresources_gen.go \
 	site/src/api/rbacresources_gen.ts \
 	docs/admin/prometheus.md \
-	docs/cli.md \
+	docs/reference/cli/README.md \
 	docs/admin/audit-logs.md \
 	coderd/apidoc/swagger.json \
 	.prettierignore.include \
@@ -521,7 +521,7 @@ gen/mark-fresh:
 		codersdk/rbacresources_gen.go \
 		site/src/api/rbacresources_gen.ts \
 		docs/admin/prometheus.md \
-		docs/cli.md \
+		docs/reference/cli/README.md \
 		docs/admin/audit-logs.md \
 		coderd/apidoc/swagger.json \
 		.prettierignore.include \
@@ -633,10 +633,10 @@ docs/admin/prometheus.md: scripts/metricsdocgen/main.go scripts/metricsdocgen/me
 	./scripts/pnpm_install.sh
 	pnpm exec prettier --write ./docs/admin/prometheus.md
 
-docs/cli.md: scripts/clidocgen/main.go examples/examples.gen.json $(GO_SRC_FILES)
+docs/reference/cli/README.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/cli.md ./docs/cli/*.md ./docs/manifest.json
+	pnpm exec prettier --write ./docs/reference/cli/README.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
 	go run scripts/auditdocgen/main.go
@@ -646,7 +646,7 @@ docs/admin/audit-logs.md: coderd/database/querier.go scripts/auditdocgen/main.go
 coderd/apidoc/swagger.json: $(shell find ./scripts/apidocgen $(FIND_EXCLUSIONS) -type f) $(wildcard coderd/*.go) $(wildcard enterprise/coderd/*.go) $(wildcard codersdk/*.go) $(wildcard enterprise/wsproxy/wsproxysdk/*.go) $(DB_GEN_FILES) .swaggo docs/manifest.json coderd/rbac/object_gen.go
 	./scripts/apidocgen/generate.sh
 	./scripts/pnpm_install.sh
-	pnpm exec prettier --write ./docs/api ./docs/manifest.json ./coderd/apidoc/swagger.json
+	pnpm exec prettier --write ./docs/reference/api ./docs/manifest.json ./coderd/apidoc/swagger.json
 
 update-golden-files: \
 	cli/testdata/.gen-golden \

diff --git a/docs/admin/audit-logs.md b/docs/admin/audit-logs.md
@@ -70,14 +70,15 @@ audit trails.
 
 Audit logs can be accessed through our REST API. You can find detailed
 information about this in our
-[endpoint documentation](../api/audit.md#get-audit-logs).
+[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](../cli/server.md#--log-json) audit log entry:
+Example of a [JSON formatted](../reference/cli/server.md#--log-json) audit log
+entry:
 
 ```json
 {
@@ -112,7 +113,8 @@ Example of a [JSON formatted](../cli/server.md#--log-json) audit log entry:
 }
 ```
 
-Example of a [human readable](../cli/server.md#--log-human) audit log entry:
+Example of a [human readable](../reference/cli/server.md#--log-human) audit log
+entry:
 
 ```console
 2023-06-13 03:43:29.233 [info]  coderd: audit_log  ID=95f7c392-da3e-480c-a579-8909f145fbe2  Time="2023-06-13T03:43:29.230422Z"  UserID=6c405053-27e3-484a-9ad7-bcb64e7bfde6  OrganizationID=00000000-0000-0000-0000-000000000000  Ip=<nil>  UserAgent=<nil>  ResourceType=workspace_build  ResourceID=988ae133-5b73-41e3-a55e-e1e9d3ef0b66  ResourceTarget=""  Action=start  Diff="{}"  StatusCode=200  AdditionalFields="{\"workspace_name\":\"linux-container\",\"build_number\":\"7\",\"build_reason\":\"initiator\",\"workspace_owner\":\"\"}"  RequestID=9682b1b5-7b9f-4bf2-9a39-9463f8e41cd6  ResourceIcon=""

diff --git a/docs/admin/auth.md b/docs/admin/auth.md
@@ -19,7 +19,7 @@ First,
 GitHub will ask you for the following Coder parameters:
 
 - **Homepage URL**: Set to your Coder deployments
-  [`CODER_ACCESS_URL`](../cli/server.md#--access-url) (e.g.
+  [`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`
 

diff --git a/docs/admin/automation.md b/docs/admin/automation.md
@@ -4,8 +4,8 @@ All actions possible through the Coder dashboard can also be automated as it
 utilizes the same public REST API. There are several ways to extend/automate
 Coder:
 
-- [CLI](../cli.md)
-- [REST API](../api/)
+- [CLI](../reference/cli/README.md)
+- [REST API](../reference/api/README.md)
 - [Coder SDK](https://pkg.go.dev/github.com/coder/coder/v2/codersdk)
 
 ## Quickstart
@@ -32,9 +32,10 @@ curl https://coder.example.com/api/v2/workspaces?q=owner:me \
 
 ## Documentation
 
-We publish an [API reference](../api/index.md) in our documentation. You can
-also enable a [Swagger endpoint](../cli/server.md#--swagger-enable) on your
-Coder deployment.
+We publish an [API reference](../reference/api/README.md) in our documentation.
+You can also enable a
+[Swagger endpoint](../reference/cli/server.md#--swagger-enable) on your Coder
+deployment.
 
 ## Use cases
 
@@ -52,8 +53,8 @@ payloads, we recommend checking the CLI and API documentation.
 Workspace agents have a special token that can send logs, metrics, and workspace
 activity.
 
-- [Custom workspace logs](../api/agents.md#patch-workspace-agent-logs): Expose
-  messages prior to the Coder init script running (e.g. pulling image, VM
+- [Custom workspace logs](../reference/api/agents.md#patch-workspace-agent-logs):
+  Expose messages prior to the Coder init script running (e.g. pulling image, VM
   starting, restoring snapshot).
   [coder-logstream-kube](https://github.com/coder/coder-logstream-kube) uses
   this to show Kubernetes events, such as image pulls or ResourceQuota
@@ -73,7 +74,7 @@ activity.
   }"
   ```
 
-- [Manually send workspace activity](../api/agents.md#submit-workspace-agent-stats):
+- [Manually send workspace activity](../reference/api/agents.md#submit-workspace-agent-stats):
   Keep a workspace "active," even if there is not an open connection (e.g. for a
   long-running machine learning job).
 

diff --git a/docs/admin/configure.md b/docs/admin/configure.md
@@ -1,6 +1,6 @@
 Coder server's primary configuration is done via environment variables. For a
 full list of the options, run `coder server --help` or see our
-[CLI documentation](../cli/server.md).
+[CLI documentation](../reference/cli/server.md).
 
 ## Access URL
 
@@ -48,10 +48,11 @@ If you are providing TLS certificates directly to the Coder server, either
 1. Use a single certificate and key for both the root and wildcard domains.
 2. Configure multiple certificates and keys via
    [`coder.tls.secretNames`](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
-   in the Helm Chart, or [`--tls-cert-file`](../cli/server.md#--tls-cert-file)
-   and [`--tls-key-file`](../cli/server.md#--tls-key-file) command line options
-   (these both take a comma separated list of files; list certificates and their
-   respective keys in the same order).
+   in the Helm Chart, or
+   [`--tls-cert-file`](../reference/cli/server.md#--tls-cert-file) and
+   [`--tls-key-file`](../reference/cli/server.md#--tls-key-file) command line
+   options (these both take a comma separated list of files; list certificates
+   and their respective keys in the same order).
 
 ## TLS & Reverse Proxy
 

diff --git a/docs/admin/encryption.md b/docs/admin/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](../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`](../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](../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`](../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.
+  [`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`](../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
@@ -132,8 +132,9 @@ To disable encryption, perform the following actions:
 - Stop all active coderd instances. This will prevent new encrypted data from
   being written, which may cause the next step to fail.
 
-- Run [`coder server dbcrypt decrypt`](../cli/server_dbcrypt_decrypt.md). This
-  command will decrypt all encrypted user tokens and revoke all active
+- Run
+  [`coder server dbcrypt decrypt`](../reference/cli/server_dbcrypt_decrypt.md).
+  This command will decrypt all encrypted user tokens and revoke all active
   encryption keys.
 
   > Note: for `decrypt` command, the equivalent environment variable for
@@ -142,7 +143,7 @@ To disable encryption, perform the following actions:
   > to help prevent accidentally decrypting data.
 
 - Remove all
-  [external token encryption keys](../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
@@ -159,12 +160,13 @@ To delete all encrypted data from your database, perform the following actions:
 - Stop all active coderd instances. This will prevent new encrypted data from
   being written.
 
-- Run [`coder server dbcrypt delete`](../cli/server_dbcrypt_delete.md). This
-  command will delete all encrypted user tokens and revoke all active encryption
-  keys.
+- Run
+  [`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](../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

diff --git a/docs/admin/healthcheck.md b/docs/admin/healthcheck.md
@@ -4,7 +4,8 @@ Coder includes an operator-friendly deployment health page that provides a
 number of details about the health of your Coder deployment.
 
 You can view it at `https://${CODER_URL}/health`, or you can alternatively view
-the [JSON response directly](../api/debug.md#debug-info-deployment-health).
+the
+[JSON response directly](../reference/api/debug.md#debug-info-deployment-health).
 
 The deployment health page is broken up into the following sections:
 
@@ -106,8 +107,8 @@ query fails.
 _Database Latency High_
 
 **Problem:** This code is returned if the median latency is higher than the
-[configured threshold](../cli/server.md#--health-check-threshold-database). This
-may not be an error as such, but is an indication of a potential issue.
+[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
 Coder's current activity and usage. It may be necessary to increase the
@@ -117,18 +118,19 @@ configured threshold to a higher value (this will not address the root cause).
 > [!TIP]
 >
 > - You can enable
->   [detailed database metrics](../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](../cli/server.md#--trace), these traces may
->   also contain useful information regarding Coder's database activity.
+> - If you have [tracing enabled](../reference/cli/server.md#--trace), these
+>   traces may also contain useful information regarding Coder's database
+>   activity.
 
 ## DERP
 
 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](../cli/server.md#--derp-config-path) which are used to relay
-traffic between Coder and workspace agents. Coder periodically queries the
+[DERP servers](../reference/cli/server.md#--derp-config-path) which are used to
+relay traffic between Coder and workspace agents. Coder periodically queries the
 health of its configured DERP servers and may return one or more of the
 following:
 
@@ -146,7 +148,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](../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.
@@ -179,9 +181,9 @@ 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](../cli/server.md#derp-server-stun-addresses) are
-reachable from Coder and that UDP traffic can be sent/received on the configured
-port.
+[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.
 
 ### ESTUN02
 
@@ -292,8 +294,8 @@ be built until there is at least one provisioner daemon running.
 If you are using
 [External Provisioner Daemons](./provisioners.md#external-provisioners), ensure
 that they are able to successfully connect to Coder. Otherwise, ensure
-[`--provisioner-daemons`](../cli/server.md#provisioner-daemons) is set to a
-value greater than 0.
+[`--provisioner-daemons`](../reference/cli/server.md#provisioner-daemons) is set
+to a value greater than 0.
 
 > Note: This may be a transient issue if you are currently in the process of
 > updating your deployment.