Files
coder/docs/admin/security/database-encryption.md
T
Nick Vigilante 5e41baf73c docs: normalize control plane, coderd, and coder server terminology (#28960)
Normalizes the three overlapping names for the thing that serves the
Coder API and dashboard. This is step 1 of the Install/Deploy and
Administration refactor
([DOCS-685](https://linear.app/codercom/issue/DOCS-685),
[DOCS-738](https://linear.app/codercom/issue/DOCS-738)) and lands first
because every later page depends on settled terminology.

Resolves [DOCS-871](https://linear.app/codercom/issue/DOCS-871).

## The rule

| Term | Means | Use when |
|---|---|---|
| control plane | The component that serves the Coder API and dashboard,
brokers connections, and coordinates provisioners | Default in prose,
diagrams, planning, sizing, security |
| `coderd` | The process that implements it | Architecture internals,
metrics, logs, flags, troubleshooting |
| `coder server` | The literal CLI command | Only when the reader will
type it |

Retired: "the Coder server" as a name for the component, and "a service"
as a standalone description of it.

## What changed

- **`docs/.style/style-guide/word-choice.md`**: new "Naming Coder's
components" rule, with do/don't examples. Also fixes a "Do" example on
that page that itself used "the Coder server".
- **`docs/reference/glossary.md`**: rewrote `coderd` and Control plane,
added a `coder server` entry. The existing Control plane entry defined
it as "the collective term for `coderd`, its provisioners, and its
database", which made it indistinguishable from the Deployment entry two
sections later. Control plane is now the component; Deployment remains
the whole installation.
- **65 pages** across `docs/admin`, `docs/install`, `docs/get-started`,
`docs/tutorials`, `docs/user-guides`, `docs/ai-coder`, and `docs/about`:
roughly 154 component-sense "Coder server" usages, 21 bare "the server"
usages meaning the control plane, 3 "a service" descriptions, and 43
unbackticked `coderd` mentions in prose.
- One real bug caught in passing:
`docs/tutorials/best-practices/security-best-practices.md` documented
`coderd server --disable-path-apps`, which is not a command. Now `coder
server`.

Generated files were not touched: `configuration-reference.md`,
`prometheus.md`, `audit-logs.md`, `reference/cli/*`, `reference/api/*`,
and the generated blocks inside `feature-stages.md`. Those still contain
the retired term and need generator-side changes; see the deferred list
below.

## Reviewer attention, please

**Anchor changes.** 11 headings were renamed, so their fragments change.
No in-repo link targets any of them (the one internal link that did was
updated), but external deep links from tickets or blog posts would
break, and fragments cannot be fixed with a redirect. Happy to revert
any of these if you would rather they ride along with the page moves in
[DOCS-869](https://linear.app/codercom/issue/DOCS-869), which changes
those URLs anyway.

<details>
<summary>Renamed headings and their old fragments</summary>

| File | Old fragment | New heading |
|---|---|---|
| `admin/networking/index.md` | `#coder-server` | `## Control plane` |
| `install/index.md` | `#starting-the-coder-server` | `## Starting the
control plane` |
| `install/uninstall.md` | `#the-coder-server-binary-and-cli` | `## The
Coder binary and CLI` |
| `install/registry-mirror-artifactory.md` |
`#step-5-configure-coder-server-or-provisioners` | `## Step 5: Configure
the control plane or provisioners` |
| `install/cloud/compute-engine.md` | `#configuring-coder-server` | `##
Configuring the control plane` |
| `get-started/index.md` |
`#cant-start-coder-server-address-already-in-use` | ``### Can't start
`coder server`: Address already in use`` |
| `tutorials/external-database.md` |
`#coder-server-fails-startup-with-...` | ``### `coder server` fails
startup with ...`` |
| `tutorials/faqs.md` |
`#how-do-i-change-the-access-url-for-my-coder-server` | `## How do I
change the access URL for my control plane?` |
| `tutorials/best-practices/security-best-practices.md` |
`#coder-server` | `## Control plane` |
| `tutorials/best-practices/security-best-practices.md` |
`#server-logs-and-audit-logs` | `### Control plane logs and audit logs`
|
| `tutorials/best-practices/scale-coder.md` | `#coder-server`,
`#how-to-capture-coder-server-metrics-with-prometheus` | `## Control
plane`, `### How to capture control plane metrics with Prometheus` |

</details>

**One deliberate deviation from the issue.** DOCS-871 proposed reserving
"sub-agent" for the Coder Agents sense and using "devcontainer agent"
for the workspace sense. I did not make that change. The glossary
already disambiguates with "Sub-agent (Coder Agents)" and "Sub-agent
(dev containers)", and "devcontainer agent" would violate the existing
dev container spelling rule in the same style guide, which requires "dev
container" as two lowercase words. The current split reads correctly and
costs no churn. Happy to revisit if you disagree.

<details>
<summary>Deferred, with reasons</summary>

- **Generated content still says "Coder server".** `reference/cli/*`
comes from Go command help text, `configuration-reference.md` from
`configdocgen`, and `reference/api/*` from Swagger annotations. Fixing
those means changing Go source, which belongs in its own PR so a docs
review does not turn into a backend review.
- **`validated-architectures/index.md` "also known as `coderd`"** is
fixed here, but the page's larger problem is that it holds four
documents in one file. That split is
[DOCS-868](https://linear.app/codercom/issue/DOCS-868).
- **"server flag" phrasing** in `admin/users/idp-sync.md` and
`admin/users/oidc-auth/index.md` means `coder server` flags. Left alone;
rewording those sentences is a copy edit, not a substitution.
- **Metric and UI labels** such as "Dashboard-to-server latency" in
`admin/networking/index.md`. Renaming risks diverging from what the
dashboard shows.
- **Pre-existing `Coder.GerundHeading` warnings** on headings this PR
touches, and a "from from" typo in `scale-coder.md`. Out of scope for a
terminology pass.
- **Peer-sense "server"** in NAT traversal prose, where "client or
server" describes the connection roles rather than the control plane.
Needs restructuring, not substitution.

</details>

## Verification

| Check | Result |
|---|---|
| `make lint/emdash` | pass |
| `make lint/markdown` | pass, 504 files, 0 errors |
| `make lint/docs-html` | pass |
| `make lint/prose` | pass, findings identical to the `main` baseline (1
intentional demo error, 145 warnings, 1 suggestion; only Vale's file
ordering and one line-number shift in `glossary.md` differ) |
| `make gen` | clean, no drift |
| `make fmt/markdown` | applied |

No redirects needed: no page moved or was renamed in this PR.

<details>
<summary>Merged main, 2026-09-14</summary>

One conflict, in `docs/ai-coder/ai-gateway/providers.md`. Both hunks
were text this PR had edited and `main` had since deleted in #29053,
which removed env-based AI provider configuration:

- The deprecated provider seeding note, which held a `coderd` backtick
fix, is gone. Took `main`.
- The failure-mode table lost its env-drift row. Took `main`'s two rows
and reapplied the `coderd` logs wording.

`main` also landed new prose carrying the retired terms, so the pass was
extended to cover it:

- `docs/admin/integrations/oauth2-provider.md`: two "the server log(s)"
in the scope-enforcement sections added by #29144 are now "the `coderd`
log(s)"; "a `scope` the server will not grant" is now "the control
plane".
- `docs/reference/cli/index.md` gained "the server" from #29104, and
stays deferred as generated content.

The new `docs/ai-coder/agent-relay/claude-code.md` needed no change, and
no page `main` added links to a heading this PR renamed.

</details>

<details>
<summary>Decision log for the wider refactor</summary>

Agreed with @nickvigilante before implementation, recorded on DOCS-685
and in the Notion outline:

1. Feature stages and release channels move to Reference; ESR upgrade
guides move under Operate. No new top-level Releases section.
2. `data-retention.md` moves to Administration > Security;
`chat-lifecycle-hooks.md` moves into the Coder Agents docs.
`admin/setup/` therefore survives as "Deployment configuration" and
`configdocgen` is not touched.
3. Prepare is advisory, not a gate, framed as "don't know where to
start? Start here", with lead times and owners per item.
4. One actor table, on the Install overview, spanning all five phases,
noting that one person can be several actors and several people can be
one actor.
5. The quickstart stays independent and is mentioned once, on the
Install overview. The proposed `server/single-machine` page is dropped.
6. Coder Validated Architecture keeps its name in nav, defined in-page,
with a glossary entry.
7. PR 3 is split: moves only, then prose, so the riskiest change reads
as a pure rename diff.
8. For every PR that moves a page, the coder.com `redirects.json` change
merges first.
9. There is no Download section and no CLI page in docs. Per-OS CLI
steps live on coder.com/download and the Install overview links to it.

</details>

Generated with Coder Agents on behalf of @nickvigilante.
2026-09-22 15:18:40 -04:00

7.2 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

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.

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

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

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

Deleting 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