## Summary Nests the CLI reference by subcommand so the Command Line sidebar collapses from 156 flat entries to 49 top-level verbs. Each page's URL follows the invocation, its page title is the full command as inline code, and its sidebar label is only its own verb as inline code. | | Before | After | | --- | --- | --- | | File | `docs/reference/cli/oauth2-provider_dcr_disable.md` | `docs/reference/cli/oauth2-provider/dcr/disable.md` | | URL | `/reference/cli/oauth2-provider_dcr_disable` | `/reference/cli/oauth2-provider/dcr/disable` | | Page title (front matter) | `oauth2-provider dcr disable` | `` `coder oauth2-provider dcr disable` `` | | Sidebar label (manifest) | `oauth2-provider dcr disable` | `` `disable` `` | Resolves DOCS-140 (coder/coder half). Also fixes the Makefile part of DOCS-1073 / DOCS-912, which this change depends on. ## Changes - `scripts/clidocgen`: pages nest by command path. A command with visible subcommands becomes its directory's `index.md`, so `oauth2-provider/index.md` and `oauth2-provider/dcr/index.md` sit above `oauth2-provider/dcr/disable.md`. Subcommand table links are relative to the parent page. - `scripts/clidocgen`: the manifest "Command Line" section is built from the command tree (nested, sorted by name, hidden commands skipped) instead of a flat list. The redundant `coder` child that pointed back at `reference/cli/index.md` is gone. - `Makefile`: the CLI rule now replaces `docs/reference/cli/` wholesale, so stale pages get removed. The manifest rule now runs `clidocgen -manifest-only` on top of the API staging manifest, so the CLI nav is generated instead of edited by hand. As a result, the nine pages that had no nav entry (`ai-gateway*`, `secret enable/disable`, `server fix-oidc-links`) now have one. - `scripts/configdocgen` and 48 prose pages: links point at the new paths (for example `reference/cli/server.md` is now `reference/cli/server/index.md`). ## How to review/QA this PR - `docs/reference/cli/**/*` (approximately 190 pages): Each of these pages are generated automatically. Some pages appear deleted, and some pages appear new. Every deleted page corresponds to a new page somewhere else, so no information is being deleted. The docs in this section should adhere to the following, so a test in the build preview for each of these items should be satisfactory: - [ ] Each subcommand of a command gets nested as a child instead of being displayed as a flat list. - [ ] Each parent command is stored in an `index.md` file. - [ ] The title of each page inside the page should now feature the full `coder XYZ` command. - [ ] The title of each page inside the page should now be formatted as inline code. - [ ] The title of each page in the sidebar should be the most granular subcommand of the whole command string (if the page's title is `coder ai-gateway keys create`, the sidebar label is `create`). - [ ] The title of each page in the sidebar should now be formatted as inline code. - [ ] The page slug for each page is now the most granular subcommand. - [ ] All links now point to the correct page. - `docs/manifest.json`: The changes here reflect the updated structure of the `docs/reference/cli` section. - `docs/**/*.md` outside of `docs/reference/cli/**/*` (approximately 50 pages): The extent of the changes in these pages are just updating the paths to point to the new page locations. - [ ] The links on the page all point to the correct new path in `docs/reference/cli`. - `scripts/clidocgen` (4 files): This is the Go code responsible for generating everything inside of `docs/reference/cli/**/*`. A typical code review here should be satisfactory. - `scripts/configdocgen` (2 files): these two files just have updates to the raw `.md` path used by `docs/admin/setup/configuration-reference.md` and updates the tests to reflect that. - `Makefile`: This updates the `make` targets for generating the CLI docs to fit the new structure. ## Merge ordering Without the renderer PRs deployed, both docs sites show literal backticks in titles and sidebar labels. Without the redirects, the old flat URLs return 404. 1. Deploy before merging this PR: coder/docs-engine#176 (beta-docs renders these titles as inline code) and coder/coder.com#1111 (classic docs renders them as inline code). Both are safe to ship first, because titles without backticks render as before. 2. Merge this PR. 3. Merge coder/coder.com#1112 (redirects from the old flat URLs) only once this content reaches the mainline release branch that serves unversioned `/docs`. ## Testing - `go test ./scripts/clidocgen/ ./scripts/configdocgen/ ./scripts/docshtmlcheck/`: pass. New tests cover page paths, subcommand links, the nested manifest, and front matter quoting. - `make docs/reference/cli/index.md docs/manifest.json docs/admin/setup/configuration-reference.md`, then a forced rerun: the second run produced no diff. - Checked the manifest: all 164 CLI entries resolve to a file, no page is missing a nav entry, and everything outside "Command Line" is byte-identical. - Relative `.md` links across `docs/`: 0 broken, same as `main`. - `make pre-commit` and `make pre-push`: pass. On earlier pre-push attempts, different unrelated vitest files timed out under host load. Those files pass when run alone, and the final push passed with `PARALLEL_JOBS=1`. <details> <summary>Implementation plan and decision log</summary> **Goal (from DOCS-140 and the requester):** URLs follow the command hierarchy. Pages are titled with the full command, and sidebar entries with the last verb only. Both are formatted as inline code. **Contract with the renderers:** a title wrapped entirely in one pair of backticks (``^`[^`]+`$``) renders as inline code. Plain-text consumers (`<title>`, meta, search, llms corpus) strip the backticks. Page title comes from front matter `title`, and the sidebar label from the manifest node `title`. **Decisions** - A parent command is `dir/index.md` rather than a sibling `dir.md`. The root CLI page is already `index.md`, and both docs-engine and the legacy coder.com renderer map `x/index.md` to `/x`. - The manifest is built from the command tree, not from the written files, so ordering is deterministic and the nesting matches the pages exactly. - The manifest discard bug (DOCS-1073 item 1) is fixed here, because without that fix the generated nested manifest would never reach the tree. DOCS-1073 items 2 through 4 (a prose fix and a hidden-command policy) are out of scope. - `-manifest-only` keeps the existing parallel `make gen` layout: the API rule still owns `_gen/manifest-staging.json`, and CLI regeneration doesn't retrigger swag. - The renderer and redirect work lives in the companion PRs in coder/docs-engine and coder/coder.com. It is linked above and not duplicated here. </details> --- > [!NOTE] > Generated by Coder Agents on behalf of @nickvigilante.
7.4 KiB
title
| title |
|---|
| Database Encryption |
By default, Coder stores external user tokens and other sensitive values in plaintext in the database. Database Encryption allows Coder administrators to encrypt these values at-rest, preventing attackers with database access from reading or misusing them.
How it works
Coder allows administrators to specify 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.
Coder will use the first key provided for both encryption and decryption. If additional keys are provided, Coder will use it for decryption only. This allows administrators to rotate encryption keys without invalidating existing tokens.
The following database fields are currently encrypted:
user_links.oauth_access_tokenuser_links.oauth_refresh_tokenexternal_auth_links.oauth_access_tokenexternal_auth_links.oauth_refresh_tokencrypto_keys.secretuser_secrets.valuegitsshkeys.private_keychat_mcp_servers.headers
Additional database fields may be encrypted in the future.
Implementation notes
Each encrypted database column $C has a corresponding
$C_key_id column. This column is used to determine which encryption key was
used to encrypt the data. This allows Coder to rotate encryption keys without
invalidating existing tokens, and provides referential integrity for encrypted
data.
The $C_key_id column stores the first 7 bytes of the SHA-256 hash of the
encryption key used to encrypt the data.
Encryption keys in use are stored in dbcrypt_keys. This table stores a
record of all encryption keys that have been used to encrypt data. Active keys
have a null revoked_key_id column, and revoked keys have a non-null
revoked_key_id column. You cannot revoke a key until you have rotated all
values using that key to a new key.
Turn on encryption
Note
Enabling encryption does not encrypt all existing data. To encrypt existing data, see rotating keys below.
-
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-urlto get the connection URL. -
Generate a 32-byte random key and base64-encode it. For example:
dd if=/dev/urandom bs=32 count=1 | base64
- Store this key in a secure location (for example, a Kubernetes secret):
kubectl create secret generic coder-external-token-encryption-keys --from-literal=keys=<key>
- In your Coder configuration set
CODER_EXTERNAL_TOKEN_ENCRYPTION_KEYSto a comma-separated list of base64-encoded keys. For example, in your Helmvalues.yaml:
coder:
env:
[...]
- name: CODER_EXTERNAL_TOKEN_ENCRYPTION_KEYS
valueFrom:
secretKeyRef:
name: coder-external-token-encryption-keys
key: keys
- Restart the control plane. It will now encrypt all new data with the provided key.
Rotate keys
We recommend only having one active encryption key at a time normally. However, if you need to rotate keys, you can perform the following procedure:
-
Ensure you have a valid backup of your database. Do not skip this step.
-
Generate a new encryption key following the same procedure as above.
-
Add the above key to the list of external token encryption keys. The new key must appear first in the list. For example, in the Kubernetes secret created above:
apiVersion: v1
kind: Secret
type: Opaque
metadata:
name: coder-external-token-encryption-keys
namespace: coder-namespace
data:
keys: <new-key>,<old-key1>,<old-key2>,...
-
After updating the configuration, restart the control plane. It will now encrypt all new data with the new key, but will be able to decrypt tokens encrypted with the old key(s).
-
To re-encrypt all encrypted database fields with the new key, run
coder server dbcrypt rotate. This command will re-encrypt all tokens with the specified new encryption key. We recommend performing this action during a maintenance window.This command requires direct access to the database. If you are using the built-in PostgreSQL database, you can run
coder server postgres-builtin-urlto get the connection URL. -
Once the above command completes successfully, remove the old encryption key from Coder's configuration and restart Coder once more. You can now safely delete the old key from your secret store.
Turn off encryption
To disable encryption, perform the following actions:
-
Ensure you have a valid backup of your database. Do not skip this step.
-
Stop all active
coderdinstances. This will prevent new encrypted data from being written, which may cause the next step to fail. -
Run
coder server dbcrypt decrypt. This command will decrypt all encrypted user tokens and revoke all active encryption keys.Note
for
decryptcommand, the equivalent environment variable for--keysisCODER_EXTERNAL_TOKEN_ENCRYPTION_DECRYPT_KEYSand notCODER_EXTERNAL_TOKEN_ENCRYPTION_KEYS. This is explicitly named differently to help prevent accidentally decrypting data. -
Remove all external token encryption keys from Coder's configuration.
-
Start
coderd. You can now safely delete the encryption keys from your secret store.
Delete encrypted data
Caution
This is a destructive operation.
To delete all encrypted data from your database, perform the following actions:
-
Ensure you have a valid backup of your database. Do not skip this step.
-
Stop all active
coderdinstances. This will prevent new encrypted data from being written. -
Run
coder server dbcrypt delete. This command will delete all encrypted user tokens and revoke all active encryption keys. -
Remove all external token encryption keys from Coder's configuration.
-
Start
coderd. You can now safely delete the encryption keys from your secret store.
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 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 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, and retry.