Files
coder/docs/admin/security/database-encryption.md
T
Nick Vigilante d40e24cf7d docs: nest the CLI reference by subcommand (#29956)
## 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.
2026-09-28 15:44:10 -04:00

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_token
  • user_links.oauth_refresh_token
  • external_auth_links.oauth_access_token
  • external_auth_links.oauth_refresh_token
  • crypto_keys.secret
  • user_secrets.value
  • gitsshkeys.private_key
  • chat_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-url to 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_KEYS to a comma-separated list of base64-encoded keys. For example, in your Helm values.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-url to 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 coderd instances. 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 decrypt command, the equivalent environment variable for --keys is CODER_EXTERNAL_TOKEN_ENCRYPTION_DECRYPT_KEYS and not CODER_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 coderd instances. 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.

Next steps