From 6677b3a3fa6559daa243e20a15027221f7d0507b Mon Sep 17 00:00:00 2001 From: "Kayla (via Coder Agents)" Date: Mon, 8 Jun 2026 23:02:57 +0000 Subject: [PATCH 01/13] docs: lead with env vars in admin docs and add configuration reference Coder server runs as a system service or container in production. Both read configuration from environment variables, but the admin docs lead with `coder server --flag` examples and only mention the env var form as an afterthought. Operators have to translate every flag to its CODER_* name. Three changes, all small and independent: - New generated page docs/admin/setup/configuration-reference.md with a searchable table of every visible deployment option (Setting, Env var, Flag, YAML key, Default, Description). Grouped by serpent group, with the General section first. Generated from codersdk.DeploymentValues so it stays in sync. - docs/admin/users/github-auth.md inverted to lead with the env-var form in /etc/coder.d/coder.env. The CLI flag form becomes a closing note that links to the new configuration reference. H2 slugs preserved. - DOCS_STYLE_GUIDE entry stating the env-var-first convention for admin/setup docs, with the CLI flag form reserved for ad-hoc invocations. Plumbing: new scripts/configdocgen binary, Makefile target, and GEN_FILES entry. docs/manifest.json wires the new page under Administration / Setup. docs/admin/setup/index.md gains a TIP callout pointing at the reference. Co-authored-by: Coder Agents --- .claude/docs/DOCS_STYLE_GUIDE.md | 30 ++ Makefile | 14 + docs/admin/setup/configuration-reference.md | 390 ++++++++++++++++++++ docs/admin/setup/index.md | 5 + docs/admin/users/github-auth.md | 35 +- docs/manifest.json | 5 + scripts/configdocgen/main.go | 206 +++++++++++ 7 files changed, 668 insertions(+), 17 deletions(-) create mode 100644 docs/admin/setup/configuration-reference.md create mode 100644 scripts/configdocgen/main.go diff --git a/.claude/docs/DOCS_STYLE_GUIDE.md b/.claude/docs/DOCS_STYLE_GUIDE.md index ac3e6496072c8..5045d36738aba 100644 --- a/.claude/docs/DOCS_STYLE_GUIDE.md +++ b/.claude/docs/DOCS_STYLE_GUIDE.md @@ -168,6 +168,36 @@ superseded by the canonical content guidelines. ## Code Examples +### Configuration examples: prefer environment variables + +When showing how to configure `coder server` in admin or setup +documentation, lead with the environment variable form. Production Coder +deployments are typically run as a system service, container, or Helm +chart, all of which set configuration through environment variables (for +systemd, via `/etc/coder.d/coder.env`). Showing the CLI flag form first +forces operators to mentally translate every example. + +Show the equivalent CLI flag only when the example is invoking +`coder server` directly (for local development or one-off runs), or as a +supporting note. Point readers at the +[configuration reference](../../docs/admin/setup/configuration-reference.md) +for the full mapping between environment variables, flags, and YAML keys. + +````markdown +```shell +# Preferred for admin/setup docs: +CODER_DISABLE_TEMPLATE_INSIGHTS=true +``` +```` + +CLI flag form, reserved for ad-hoc invocations: + +````markdown +```shell +coder server --disable-template-insights +``` +```` + ### Command Examples ````markdown diff --git a/Makefile b/Makefile index fd1af317c6ba4..b6f14f3af5b02 100644 --- a/Makefile +++ b/Makefile @@ -73,6 +73,7 @@ endif docs/manifest.json \ docs/admin/integrations/prometheus.md \ docs/admin/security/audit-logs.md \ + docs/admin/setup/configuration-reference.md \ docs/reference/cli/index.md \ coderd/apidoc/swagger.json \ coderd/rbac/object_gen.go \ @@ -153,6 +154,12 @@ _gen/bin/clidocgen: $(CLIDOCGEN_INPUTS) | _gen @mkdir -p _gen/bin go build -o $@ ./scripts/clidocgen +# configdocgen reflects over codersdk.DeploymentValues to produce the +# configuration reference page. +_gen/bin/configdocgen: $(wildcard scripts/configdocgen/*.go) $(wildcard codersdk/*.go) | _gen + @mkdir -p _gen/bin + go build -o $@ ./scripts/configdocgen + _gen/bin/dbdump: $(wildcard coderd/database/gen/dump/*.go) $(DBDUMP_INPUTS) | _gen @mkdir -p _gen/bin go build -o $@ ./coderd/database/gen/dump @@ -1342,6 +1349,13 @@ docs/install/releases/feature-stages.md: \ pnpm exec markdown-table-formatter "$$tmpfile" && \ mv "$$tmpfile" "$@" && rm -rf "$$tmpdir" +docs/admin/setup/configuration-reference.md: node_modules/.installed $(wildcard scripts/configdocgen/*.go) $(wildcard codersdk/*.go) | _gen _gen/bin/configdocgen + tmpdir=$$(mktemp -d -p _gen) && tmpfile=$$(realpath "$$tmpdir")/$(notdir $@) && \ + _gen/bin/configdocgen --out="$$tmpfile" && \ + pnpm exec markdownlint-cli2 --fix "$$tmpfile" && \ + pnpm exec markdown-table-formatter "$$tmpfile" && \ + mv "$$tmpfile" "$@" && rm -rf "$$tmpdir" + coderd/apidoc/.gen: \ node_modules/.installed \ scripts/apidocgen/node_modules/.installed \ diff --git a/docs/admin/setup/configuration-reference.md b/docs/admin/setup/configuration-reference.md new file mode 100644 index 0000000000000..00a491b3a873f --- /dev/null +++ b/docs/admin/setup/configuration-reference.md @@ -0,0 +1,390 @@ + +# Configuration reference + +Coder server is configured primarily through environment variables. This page +lists every option so you can search by environment variable name, CLI flag, or +YAML key. For first-time setup guidance and worked examples, see +[Configure Control Plane Access](./index.md). + +Every option below can be set via: + +- An environment variable (recommended for production deployments running as a + system service, container, or Helm chart). +- A CLI flag passed to `coder server` (useful for one-off invocations + and local development). +- A key in a YAML configuration file passed with `--config`. + +For a full description of each option's accepted values and behavior, follow +the flag link into [`coder server` CLI reference](../../reference/cli/server.md). + +## General + +| Setting | Env var | Flag | YAML | Default | Description | +|----------------------------------------------|------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Allow Workspace Renames | `CODER_ALLOW_WORKSPACE_RENAMES` | [`--allow-workspace-renames`](../../reference/cli/server.md#--allow-workspace-renames) | `allowWorkspaceRenames` | `false` | Allow users to rename their workspaces. WARNING: Renaming a workspace can cause Terraform resources that depend on the workspace name to be destroyed and recreated, potentially causing data loss. Only enable this if your templates do not use workspace names in resource identifiers, or if you understand the risks. | +| Cache Directory | `CODER_CACHE_DIRECTORY` | [`--cache-dir`](../../reference/cli/server.md#--cache-dir) | `cacheDir` | `/home/coder/.cache/coder` | The directory to cache temporary files. If unspecified and $CACHE_DIRECTORY is set, it will be used for compatibility with systemd. This directory is NOT safe to be configured as a shared directory across coderd/provisionerd replicas. | +| Default OAuth Refresh Lifetime | `CODER_DEFAULT_OAUTH_REFRESH_LIFETIME` | [`--default-oauth-refresh-lifetime`](../../reference/cli/server.md#--default-oauth-refresh-lifetime) | `defaultOAuthRefreshLifetime` | `720h0m0s` | The default lifetime duration for OAuth2 refresh tokens. This controls how long refresh tokens remain valid after issuance or rotation. | +| Default Token Lifetime | `CODER_DEFAULT_TOKEN_LIFETIME` | [`--default-token-lifetime`](../../reference/cli/server.md#--default-token-lifetime) | `defaultTokenLifetime` | `168h0m0s` | The default lifetime duration for API tokens. This value is used when creating a token without specifying a duration, such as when authenticating the CLI or an IDE plugin. | +| Disable Chat Sharing | `CODER_DISABLE_CHAT_SHARING` | [`--disable-chat-sharing`](../../reference/cli/server.md#--disable-chat-sharing) | `disableChatSharing` | - | Disable chat sharing. Chat ACL checking is disabled and only owners can access their chats. | +| Disable Owner Workspace Access | `CODER_DISABLE_OWNER_WORKSPACE_ACCESS` | [`--disable-owner-workspace-access`](../../reference/cli/server.md#--disable-owner-workspace-access) | `disableOwnerWorkspaceAccess` | - | Remove the permission for the 'owner' role to have workspace execution on all workspaces. This prevents the 'owner' from ssh, apps, and terminal access based on the 'owner' role. They still have their user permissions to access their own workspaces. | +| Disable Path Apps | `CODER_DISABLE_PATH_APPS` | [`--disable-path-apps`](../../reference/cli/server.md#--disable-path-apps) | `disablePathApps` | - | Disable workspace apps that are not served from subdomains. Path-based apps can make requests to the Coder API and pose a security risk when the workspace serves malicious JavaScript. This is recommended for security purposes if a --wildcard-access-url is configured. | +| Disable Workspace Sharing | `CODER_DISABLE_WORKSPACE_SHARING` | [`--disable-workspace-sharing`](../../reference/cli/server.md#--disable-workspace-sharing) | `disableWorkspaceSharing` | - | Disable workspace sharing. Workspace ACL checking is disabled and only owners can have ssh, apps and terminal access to workspaces. Access based on the 'owner' role is also allowed unless disabled via --disable-owner-workspace-access. | +| Enable swagger endpoint | `CODER_SWAGGER_ENABLE` | [`--swagger-enable`](../../reference/cli/server.md#--swagger-enable) | `enableSwagger` | - | Expose the swagger endpoint via /swagger. | +| Experiments | `CODER_EXPERIMENTS` | [`--experiments`](../../reference/cli/server.md#--experiments) | `experiments` | - | Enable one or more experiments. These are not ready for production. Separate multiple experiments with commas, or enter '*' to opt-in to all available experiments. | +| External Auth GitHub Default Provider Enable | `CODER_EXTERNAL_AUTH_GITHUB_DEFAULT_PROVIDER_ENABLE` | [`--external-auth-github-default-provider-enable`](../../reference/cli/server.md#--external-auth-github-default-provider-enable) | `externalAuthGithubDefaultProviderEnable` | `true` | Enable the default GitHub external auth provider managed by Coder. | +| External Token Encryption Keys | `CODER_EXTERNAL_TOKEN_ENCRYPTION_KEYS` | [`--external-token-encryption-keys`](../../reference/cli/server.md#--external-token-encryption-keys) | - | - | Encrypt OIDC and Git authentication tokens with AES-256-GCM in the database. The value must be a comma-separated list of base64-encoded keys. Each key, when base64-decoded, must be exactly 32 bytes in length. The first key will be used to encrypt new values. Subsequent keys will be used as a fallback when decrypting. During normal operation it is recommended to only set one key unless you are in the process of rotating keys with the `coder server dbcrypt rotate` command. | +| Postgres Auth | `CODER_PG_AUTH` | [`--postgres-auth`](../../reference/cli/server.md#--postgres-auth) | `pgAuth` | `password` | Type of auth to use when connecting to postgres. For AWS RDS, using IAM authentication (awsiamrds) is recommended. | +| Postgres Connection Max Idle | `CODER_PG_CONN_MAX_IDLE` | [`--postgres-conn-max-idle`](../../reference/cli/server.md#--postgres-conn-max-idle) | `pgConnMaxIdle` | `auto` | Maximum number of idle connections to the database. Set to "auto" (the default) to use max open / 3. Value must be greater or equal to 0; 0 means explicitly no idle connections. | +| Postgres Connection Max Open | `CODER_PG_CONN_MAX_OPEN` | [`--postgres-conn-max-open`](../../reference/cli/server.md#--postgres-conn-max-open) | `pgConnMaxOpen` | `10` | Maximum number of open connections to the database. Defaults to 10. | +| Postgres Connection URL | `CODER_PG_CONNECTION_URL` | [`--postgres-url`](../../reference/cli/server.md#--postgres-url) | - | - | URL of a PostgreSQL database. 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". Note that any special characters in the URL must be URL-encoded. | +| SCIM API Key | `CODER_SCIM_AUTH_HEADER` | [`--scim-auth-header`](../../reference/cli/server.md#--scim-auth-header) | - | - | Enables SCIM and sets the authentication header for the built-in SCIM server. New users are automatically created with OIDC authentication. | +| SSH Keygen Algorithm | `CODER_SSH_KEYGEN_ALGORITHM` | [`--ssh-keygen-algorithm`](../../reference/cli/server.md#--ssh-keygen-algorithm) | `sshKeygenAlgorithm` | `ed25519` | The algorithm to use for generating ssh keys. Accepted values are "ed25519", "ecdsa", or "rsa4096". | +| Support Links | `CODER_SUPPORT_LINKS` | [`--support-links`](../../reference/cli/server.md#--support-links) | `supportLinks` | - | Support links to display in the top right drop down menu. | +| Terms of Service URL | `CODER_TERMS_OF_SERVICE_URL` | [`--terms-of-service-url`](../../reference/cli/server.md#--terms-of-service-url) | `termsOfServiceURL` | - | A URL to an external Terms of Service that must be accepted by users when logging in. | +| Update Check | `CODER_UPDATE_CHECK` | [`--update-check`](../../reference/cli/server.md#--update-check) | `updateCheck` | `false` | Periodically check for new releases of Coder and inform the owner. The check is performed once per day. | + +## AI Gateway + +| Setting | Env var | Flag | YAML | Default | Description | +|--------------------------------------|----------------------------------------------|------------------------------------------------------------------------------------------------------------------|---------------------------------------|----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| AI Budget Period | `CODER_AI_BUDGET_PERIOD` | [`--ai-budget-period`](../../reference/cli/server.md#--ai-budget-period) | `ai_gateway.budget_period` | `month` | Determines when accumulated AI spend resets to zero, aligned to UTC calendar boundaries. Only "month" is currently supported. | +| AI Budget Policy | `CODER_AI_BUDGET_POLICY` | [`--ai-budget-policy`](../../reference/cli/server.md#--ai-budget-policy) | `ai_gateway.budget_policy` | `highest` | Determines the effective group when a user belongs to multiple groups with AI budgets. "highest" selects the group with the largest spend limit, and is currently the only supported value. | +| AI Gateway API Dump Directory | `CODER_AI_GATEWAY_DUMP_DIR` | [`--ai-gateway-dump-dir`](../../reference/cli/server.md#--ai-gateway-dump-dir) | `ai_gateway.api_dump_dir` | - | Base directory for dumping AI Bridge request/response pairs to disk for debugging. When set, each provider writes under a subdirectory named after the provider. Sensitive headers are redacted. Leave empty to disable. | +| AI Gateway Allow BYOK | `CODER_AI_GATEWAY_ALLOW_BYOK` | [`--ai-gateway-allow-byok`](../../reference/cli/server.md#--ai-gateway-allow-byok) | `ai_gateway.allow_byok` | `true` | Allow users to provide their own LLM API keys or subscriptions. When disabled, only centralized key authentication is permitted. | +| AI Gateway Anthropic Base URL | `CODER_AI_GATEWAY_ANTHROPIC_BASE_URL` | [`--ai-gateway-anthropic-base-url`](../../reference/cli/server.md#--ai-gateway-anthropic-base-url) | `ai_gateway.anthropic_base_url` | `https://api.anthropic.com/` | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The base URL of the Anthropic API. | +| AI Gateway Anthropic Key | `CODER_AI_GATEWAY_ANTHROPIC_KEY` | [`--ai-gateway-anthropic-key`](../../reference/cli/server.md#--ai-gateway-anthropic-key) | - | - | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The key to authenticate against the Anthropic API. | +| AI Gateway Bedrock Access Key | `CODER_AI_GATEWAY_BEDROCK_ACCESS_KEY` | [`--ai-gateway-bedrock-access-key`](../../reference/cli/server.md#--ai-gateway-bedrock-access-key) | - | - | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The access key to authenticate against the AWS Bedrock API. | +| AI Gateway Bedrock Access Key Secret | `CODER_AI_GATEWAY_BEDROCK_ACCESS_KEY_SECRET` | [`--ai-gateway-bedrock-access-key-secret`](../../reference/cli/server.md#--ai-gateway-bedrock-access-key-secret) | - | - | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The access key secret to use with the access key to authenticate against the AWS Bedrock API. | +| AI Gateway Bedrock Base URL | `CODER_AI_GATEWAY_BEDROCK_BASE_URL` | [`--ai-gateway-bedrock-base-url`](../../reference/cli/server.md#--ai-gateway-bedrock-base-url) | `ai_gateway.bedrock_base_url` | - | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The base URL to use for the AWS Bedrock API. Use this setting to specify an exact URL to use. Takes precedence over CODER_AI_GATEWAY_BEDROCK_REGION. | +| AI Gateway Bedrock Model | `CODER_AI_GATEWAY_BEDROCK_MODEL` | [`--ai-gateway-bedrock-model`](../../reference/cli/server.md#--ai-gateway-bedrock-model) | `ai_gateway.bedrock_model` | `global.anthropic.claude-sonnet-4-5-20250929-v1:0` | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The model to use when making requests to the AWS Bedrock API. | +| AI Gateway Bedrock Region | `CODER_AI_GATEWAY_BEDROCK_REGION` | [`--ai-gateway-bedrock-region`](../../reference/cli/server.md#--ai-gateway-bedrock-region) | `ai_gateway.bedrock_region` | - | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The AWS Bedrock API region to use. Constructs a base URL to use for the AWS Bedrock API in the form of 'https://bedrock-runtime..amazonaws.com'. | +| AI Gateway Bedrock Small Fast Model | `CODER_AI_GATEWAY_BEDROCK_SMALL_FAST_MODEL` | [`--ai-gateway-bedrock-small-fastmodel`](../../reference/cli/server.md#--ai-gateway-bedrock-small-fastmodel) | `ai_gateway.bedrock_small_fast_model` | `global.anthropic.claude-haiku-4-5-20251001-v1:0` | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The small fast model to use when making requests to the AWS Bedrock API. Claude Code uses Haiku-class models to perform background tasks. See https://docs.claude.com/en/docs/claude-code/settings#environment-variables. | +| AI Gateway Circuit Breaker Enabled | `CODER_AI_GATEWAY_CIRCUIT_BREAKER_ENABLED` | [`--ai-gateway-circuit-breaker-enabled`](../../reference/cli/server.md#--ai-gateway-circuit-breaker-enabled) | `ai_gateway.circuit_breaker_enabled` | `false` | Enable the circuit breaker to protect against cascading failures from upstream AI provider overload (503, 529). | +| AI Gateway Data Retention Duration | `CODER_AI_GATEWAY_RETENTION` | [`--ai-gateway-retention`](../../reference/cli/server.md#--ai-gateway-retention) | `ai_gateway.retention` | `60d` | Length of time to retain data such as interceptions and all related records (token, prompt, tool use). | +| AI Gateway Enabled | `CODER_AI_GATEWAY_ENABLED` | [`--ai-gateway-enabled`](../../reference/cli/server.md#--ai-gateway-enabled) | `ai_gateway.enabled` | `true` | Whether to start an in-memory AI Gateway instance. | +| AI Gateway Max Concurrency | `CODER_AI_GATEWAY_MAX_CONCURRENCY` | [`--ai-gateway-max-concurrency`](../../reference/cli/server.md#--ai-gateway-max-concurrency) | `ai_gateway.max_concurrency` | `0` | Maximum number of concurrent AI Gateway requests per replica. Set to 0 to disable (unlimited). | +| AI Gateway OpenAI Base URL | `CODER_AI_GATEWAY_OPENAI_BASE_URL` | [`--ai-gateway-openai-base-url`](../../reference/cli/server.md#--ai-gateway-openai-base-url) | `ai_gateway.openai_base_url` | `https://api.openai.com/v1/` | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The base URL of the OpenAI API. | +| AI Gateway OpenAI Key | `CODER_AI_GATEWAY_OPENAI_KEY` | [`--ai-gateway-openai-key`](../../reference/cli/server.md#--ai-gateway-openai-key) | - | - | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The key to authenticate against the OpenAI API. | +| AI Gateway Rate Limit | `CODER_AI_GATEWAY_RATE_LIMIT` | [`--ai-gateway-rate-limit`](../../reference/cli/server.md#--ai-gateway-rate-limit) | `ai_gateway.rate_limit` | `0` | Maximum number of AI Gateway requests per second per replica. Set to 0 to disable (unlimited). | +| AI Gateway Send Actor Headers | `CODER_AI_GATEWAY_SEND_ACTOR_HEADERS` | [`--ai-gateway-send-actor-headers`](../../reference/cli/server.md#--ai-gateway-send-actor-headers) | `ai_gateway.send_actor_headers` | `false` | Once enabled, extra headers will be added to upstream requests to identify the user (actor) making requests to AI Gateway. This is only needed if you are using a proxy between AI Gateway and an upstream AI provider. This will send X-Ai-Bridge-Actor-Id (the ID of the user making the request) and X-Ai-Bridge-Actor-Metadata-Username (their username). | +| AI Gateway Structured Logging | `CODER_AI_GATEWAY_STRUCTURED_LOGGING` | [`--ai-gateway-structured-logging`](../../reference/cli/server.md#--ai-gateway-structured-logging) | `ai_gateway.structured_logging` | `false` | Emit structured logs for AI Gateway interception records. Use this for exporting these records to external SIEM or observability systems. | + +## AI Gateway Proxy + +| Setting | Env var | Flag | YAML | Default | Description | +|-------------------------------------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|------------------------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| AI Gateway Proxy API Dump Directory | `CODER_AI_GATEWAY_PROXY_DUMP_DIR` | [`--ai-gateway-proxy-dump-dir`](../../reference/cli/server.md#--ai-gateway-proxy-dump-dir) | `ai_gateway_proxy.api_dump_dir` | - | Directory for dumping MITM request/response pairs to disk for debugging. When set, each proxied request produces .req.txt and .resp.txt files organized by provider. Sensitive headers are redacted. Leave empty to disable. | +| AI Gateway Proxy Allowed Private CIDRs | `CODER_AI_GATEWAY_PROXY_ALLOWED_PRIVATE_CIDRS` | [`--ai-gateway-proxy-allowed-private-cidrs`](../../reference/cli/server.md#--ai-gateway-proxy-allowed-private-cidrs) | `ai_gateway_proxy.allowed_private_cidrs` | - | Comma-separated list of CIDR ranges that are permitted even though they fall within blocked private/reserved IP ranges. By default all private ranges are blocked to prevent SSRF attacks. Use this to allow access to specific internal networks. | +| AI Gateway Proxy Enabled | `CODER_AI_GATEWAY_PROXY_ENABLED` | [`--ai-gateway-proxy-enabled`](../../reference/cli/server.md#--ai-gateway-proxy-enabled) | `ai_gateway_proxy.enabled` | `false` | Enable the AI Gateway MITM Proxy for intercepting and decrypting AI provider requests. | +| AI Gateway Proxy Listen Address | `CODER_AI_GATEWAY_PROXY_LISTEN_ADDR` | [`--ai-gateway-proxy-listen-addr`](../../reference/cli/server.md#--ai-gateway-proxy-listen-addr) | `ai_gateway_proxy.listen_addr` | `:8888` | The address the AI Gateway Proxy will listen on. | +| AI Gateway Proxy MITM CA Certificate File | `CODER_AI_GATEWAY_PROXY_CERT_FILE` | [`--ai-gateway-proxy-cert-file`](../../reference/cli/server.md#--ai-gateway-proxy-cert-file) | `ai_gateway_proxy.cert_file` | - | Path to the CA certificate file used to intercept (MITM) HTTPS traffic from AI clients. This CA must be trusted by AI clients for the proxy to decrypt their requests. | +| AI Gateway Proxy MITM CA Key File | `CODER_AI_GATEWAY_PROXY_KEY_FILE` | [`--ai-gateway-proxy-key-file`](../../reference/cli/server.md#--ai-gateway-proxy-key-file) | `ai_gateway_proxy.key_file` | - | Path to the CA private key file used to intercept (MITM) HTTPS traffic from AI clients. | +| AI Gateway Proxy TLS Certificate File | `CODER_AI_GATEWAY_PROXY_TLS_CERT_FILE` | [`--ai-gateway-proxy-tls-cert-file`](../../reference/cli/server.md#--ai-gateway-proxy-tls-cert-file) | `ai_gateway_proxy.tls_cert_file` | - | Path to the TLS certificate file for the AI Gateway Proxy listener. Must be set together with AI Gateway Proxy TLS Key File. | +| AI Gateway Proxy TLS Key File | `CODER_AI_GATEWAY_PROXY_TLS_KEY_FILE` | [`--ai-gateway-proxy-tls-key-file`](../../reference/cli/server.md#--ai-gateway-proxy-tls-key-file) | `ai_gateway_proxy.tls_key_file` | - | Path to the TLS private key file for the AI Gateway Proxy listener. Must be set together with AI Gateway Proxy TLS Certificate File. | +| AI Gateway Proxy Upstream Proxy | `CODER_AI_GATEWAY_PROXY_UPSTREAM` | [`--ai-gateway-proxy-upstream`](../../reference/cli/server.md#--ai-gateway-proxy-upstream) | `ai_gateway_proxy.upstream_proxy` | - | URL of an upstream HTTP proxy to chain tunneled (non-allowlisted) requests through. Format: http://[user:pass@]host:port or https://[user:pass@]host:port. | +| AI Gateway Proxy Upstream Proxy CA | `CODER_AI_GATEWAY_PROXY_UPSTREAM_CA` | [`--ai-gateway-proxy-upstream-ca`](../../reference/cli/server.md#--ai-gateway-proxy-upstream-ca) | `ai_gateway_proxy.upstream_proxy_ca` | - | Path to a PEM-encoded CA certificate to trust for the upstream proxy's TLS connection. Only needed for HTTPS upstream proxies with certificates not trusted by the system. If not provided, the system certificate pool is used. | + +## Chat + +| Setting | Env var | Flag | YAML | Default | Description | +|-----------------------------|------------------------------------|----------------------------------------------------------------------------------------------|----------------------------|---------|---------------------------------------------------------------------------------------------------| +| Chat: Debug Logging Enabled | `CODER_CHAT_DEBUG_LOGGING_ENABLED` | [`--chat-debug-logging-enabled`](../../reference/cli/server.md#--chat-debug-logging-enabled) | `chat.debugLoggingEnabled` | `false` | Force chat debug logging on for every chat, bypassing the runtime admin and user opt-in settings. | + +## Client + +| Setting | Env var | Flag | YAML | Default | Description | +|---------------------------|-----------------------------------|--------------------------------------------------------------------------------------------|----------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| CLI Upgrade Message | `CODER_CLI_UPGRADE_MESSAGE` | [`--cli-upgrade-message`](../../reference/cli/server.md#--cli-upgrade-message) | `client.cliUpgradeMessage` | - | The upgrade message to display to users when a client/server mismatch is detected. By default it instructs users to update using 'curl -L https://coder.com/install.sh \| sh'. | +| Hide AI Tasks | `CODER_HIDE_AI_TASKS` | [`--hide-ai-tasks`](../../reference/cli/server.md#--hide-ai-tasks) | `client.hideAITasks` | `false` | Hide AI tasks from the dashboard. | +| SSH Config Options | `CODER_SSH_CONFIG_OPTIONS` | [`--ssh-config-options`](../../reference/cli/server.md#--ssh-config-options) | `client.sshConfigOptions` | - | These SSH config options will override the default SSH config options. Provide options in "key=value" or "key value" format separated by commas.Using this incorrectly can break SSH to your deployment, use cautiously. | +| Web Terminal Renderer | `CODER_WEB_TERMINAL_RENDERER` | [`--web-terminal-renderer`](../../reference/cli/server.md#--web-terminal-renderer) | `client.webTerminalRenderer` | `canvas` | The renderer to use when opening a web terminal. Valid values are 'canvas', 'webgl', or 'dom'. | +| Workspace Hostname Suffix | `CODER_WORKSPACE_HOSTNAME_SUFFIX` | [`--workspace-hostname-suffix`](../../reference/cli/server.md#--workspace-hostname-suffix) | `client.workspaceHostnameSuffix` | `coder` | Workspace hostnames use this suffix in SSH config and Coder Connect on Coder Desktop. By default it is coder, resulting in names like myworkspace.coder. | + +## Config + +| Setting | Env var | Flag | YAML | Default | Description | +|--------------|---------------------|------------------------------------------------------------------|------|---------|--------------------------------------------------------| +| Config Path | `CODER_CONFIG_PATH` | [`--config`](../../reference/cli/server.md#--config) | - | - | Specify a YAML file to load configuration from. | +| Write Config | - | [`--write-config`](../../reference/cli/server.md#--write-config) | - | - | Write out the current server config as YAML to stdout. | + +## Email + +| Setting | Env var | Flag | YAML | Default | Description | +|---------------------|-------------------------|------------------------------------------------------------------------|-------------------|-------------|-----------------------------------------------------------| +| Email: Force TLS | `CODER_EMAIL_FORCE_TLS` | [`--email-force-tls`](../../reference/cli/server.md#--email-force-tls) | `email.forceTLS` | `false` | Force a TLS connection to the configured SMTP smarthost. | +| Email: From Address | `CODER_EMAIL_FROM` | [`--email-from`](../../reference/cli/server.md#--email-from) | `email.from` | - | The sender's address to use. | +| Email: Hello | `CODER_EMAIL_HELLO` | [`--email-hello`](../../reference/cli/server.md#--email-hello) | `email.hello` | `localhost` | The hostname identifying the SMTP server. | +| Email: Smarthost | `CODER_EMAIL_SMARTHOST` | [`--email-smarthost`](../../reference/cli/server.md#--email-smarthost) | `email.smarthost` | - | The intermediary SMTP host through which emails are sent. | + +## Email / Email Authentication + +| Setting | Env var | Flag | YAML | Default | Description | +|---------------------------|----------------------------------|------------------------------------------------------------------------------------------|--------------------------------|---------|---------------------------------------------------------------------------| +| Email Auth: Identity | `CODER_EMAIL_AUTH_IDENTITY` | [`--email-auth-identity`](../../reference/cli/server.md#--email-auth-identity) | `email.emailAuth.identity` | - | Identity to use with PLAIN authentication. | +| Email Auth: Password | `CODER_EMAIL_AUTH_PASSWORD` | [`--email-auth-password`](../../reference/cli/server.md#--email-auth-password) | - | - | Password to use with PLAIN/LOGIN authentication. | +| Email Auth: Password File | `CODER_EMAIL_AUTH_PASSWORD_FILE` | [`--email-auth-password-file`](../../reference/cli/server.md#--email-auth-password-file) | `email.emailAuth.passwordFile` | - | File from which to load password for use with PLAIN/LOGIN authentication. | +| Email Auth: Username | `CODER_EMAIL_AUTH_USERNAME` | [`--email-auth-username`](../../reference/cli/server.md#--email-auth-username) | `email.emailAuth.username` | - | Username to use with PLAIN/LOGIN authentication. | + +## Email / Email TLS + +| Setting | Env var | Flag | YAML | Default | Description | +|-----------------------------------------------------|-------------------------------|----------------------------------------------------------------------------------------|-------------------------------------|---------|------------------------------------------------------------------| +| Email TLS: Certificate Authority File | `CODER_EMAIL_TLS_CACERTFILE` | [`--email-tls-ca-cert-file`](../../reference/cli/server.md#--email-tls-ca-cert-file) | `email.emailTLS.caCertFile` | - | CA certificate file to use. | +| Email TLS: Certificate File | `CODER_EMAIL_TLS_CERTFILE` | [`--email-tls-cert-file`](../../reference/cli/server.md#--email-tls-cert-file) | `email.emailTLS.certFile` | - | Certificate file to use. | +| Email TLS: Certificate Key File | `CODER_EMAIL_TLS_CERTKEYFILE` | [`--email-tls-cert-key-file`](../../reference/cli/server.md#--email-tls-cert-key-file) | `email.emailTLS.certKeyFile` | - | Certificate key file to use. | +| Email TLS: Server Name | `CODER_EMAIL_TLS_SERVERNAME` | [`--email-tls-server-name`](../../reference/cli/server.md#--email-tls-server-name) | `email.emailTLS.serverName` | - | Server name to verify against the target certificate. | +| Email TLS: Skip Certificate Verification (Insecure) | `CODER_EMAIL_TLS_SKIPVERIFY` | [`--email-tls-skip-verify`](../../reference/cli/server.md#--email-tls-skip-verify) | `email.emailTLS.insecureSkipVerify` | - | Skip verification of the target server's certificate (insecure). | +| Email TLS: StartTLS | `CODER_EMAIL_TLS_STARTTLS` | [`--email-tls-starttls`](../../reference/cli/server.md#--email-tls-starttls) | `email.emailTLS.startTLS` | - | Enable STARTTLS to upgrade insecure SMTP connections using TLS. | + +## Introspection / Health Check + +| Setting | Env var | Flag | YAML | Default | Description | +|----------------------------------|-----------------------------------------|--------------------------------------------------------------------------------------------------------|-----------------------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Health Check Refresh | `CODER_HEALTH_CHECK_REFRESH` | [`--health-check-refresh`](../../reference/cli/server.md#--health-check-refresh) | `introspection.healthcheck.refresh` | `10m0s` | Refresh interval for healthchecks. | +| Health Check Threshold: Database | `CODER_HEALTH_CHECK_THRESHOLD_DATABASE` | [`--health-check-threshold-database`](../../reference/cli/server.md#--health-check-threshold-database) | `introspection.healthcheck.thresholdDatabase` | `15ms` | The threshold for the database health check. If the median latency of the database exceeds this threshold over 5 attempts, the database is considered unhealthy. The default value is 15ms. | + +## Introspection / Logging + +| Setting | Env var | Flag | YAML | Default | Description | +|-----------------------------|-------------------------------------|------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------|--------------------------------------------------------------------------------------| +| Enable Terraform debug mode | `CODER_ENABLE_TERRAFORM_DEBUG_MODE` | [`--enable-terraform-debug-mode`](../../reference/cli/server.md#--enable-terraform-debug-mode) | `introspection.logging.enableTerraformDebugMode` | `false` | Allow administrators to enable Terraform debug output. | +| Human Log Location | `CODER_LOGGING_HUMAN` | [`--log-human`](../../reference/cli/server.md#--log-human) | `introspection.logging.humanPath` | `/dev/stderr` | Output human-readable logs to a given file. | +| JSON Log Location | `CODER_LOGGING_JSON` | [`--log-json`](../../reference/cli/server.md#--log-json) | `introspection.logging.jsonPath` | - | Output JSON logs to a given file. | +| Log Filter | `CODER_LOG_FILTER` | [`--log-filter`](../../reference/cli/server.md#--log-filter) | `introspection.logging.filter` | - | Filter debug logs by matching against a given regex. Use .* to match all debug logs. | +| Stackdriver Log Location | `CODER_LOGGING_STACKDRIVER` | [`--log-stackdriver`](../../reference/cli/server.md#--log-stackdriver) | `introspection.logging.stackdriverPath` | - | Output Stackdriver compatible logs to a given file. | + +## Introspection / Prometheus + +| Setting | Env var | Flag | YAML | Default | Description | +|-------------------------------------|---------------------------------------------|----------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Prometheus Address | `CODER_PROMETHEUS_ADDRESS` | [`--prometheus-address`](../../reference/cli/server.md#--prometheus-address) | `introspection.prometheus.address` | `127.0.0.1:2112` | The bind address to serve prometheus metrics. | +| Prometheus Aggregate Agent Stats By | `CODER_PROMETHEUS_AGGREGATE_AGENT_STATS_BY` | [`--prometheus-aggregate-agent-stats-by`](../../reference/cli/server.md#--prometheus-aggregate-agent-stats-by) | `introspection.prometheus.aggregate_agent_stats_by` | `agent_name,template_name,username,workspace_name` | When collecting agent stats, aggregate metrics by a given set of comma-separated labels to reduce cardinality. Accepted values are agent_name, template_name, username, workspace_name. | +| Prometheus Collect Agent Stats | `CODER_PROMETHEUS_COLLECT_AGENT_STATS` | [`--prometheus-collect-agent-stats`](../../reference/cli/server.md#--prometheus-collect-agent-stats) | `introspection.prometheus.collect_agent_stats` | - | Collect agent stats (may increase charges for metrics storage). | +| Prometheus Collect Database Metrics | `CODER_PROMETHEUS_COLLECT_DB_METRICS` | [`--prometheus-collect-db-metrics`](../../reference/cli/server.md#--prometheus-collect-db-metrics) | `introspection.prometheus.collect_db_metrics` | `false` | Collect database query metrics (may increase charges for metrics storage). If set to false, a reduced set of database metrics are still collected. | +| Prometheus Enable | `CODER_PROMETHEUS_ENABLE` | [`--prometheus-enable`](../../reference/cli/server.md#--prometheus-enable) | `introspection.prometheus.enable` | - | Serve prometheus metrics on the address defined by prometheus address. | + +## Introspection / Stats Collection / Usage Stats + +| Setting | Env var | Flag | YAML | Default | Description | +|-------------------------------------|---------------------------------------------|----------------------------------------------------------------------------------------------------------------|---------------------------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Stats Collection Usage Stats Enable | `CODER_STATS_COLLECTION_USAGE_STATS_ENABLE` | [`--stats-collection-usage-stats-enable`](../../reference/cli/server.md#--stats-collection-usage-stats-enable) | `introspection.statsCollection.usageStats.enable` | `true` | Enable the collection of application and workspace usage along with the associated API endpoints and the template insights page. Disabling this will also disable traffic and connection insights in the deployment stats shown to admins in the bottom bar of the Coder UI, and will prevent Prometheus collection of these values. | + +## Introspection / Tracing + +| Setting | Env var | Flag | YAML | Default | Description | +|-------------------------|---------------------------------|----------------------------------------------------------------------------------------|-------------------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Capture Logs in Traces | `CODER_TRACE_LOGS` | [`--trace-logs`](../../reference/cli/server.md#--trace-logs) | `introspection.tracing.captureLogs` | - | Enables capturing of logs as events in traces. This is useful for debugging, but may result in a very large amount of events being sent to the tracing backend which may incur significant costs. | +| Trace Enable | `CODER_TRACE_ENABLE` | [`--trace`](../../reference/cli/server.md#--trace) | `introspection.tracing.enable` | - | Whether application tracing data is collected. It exports to a backend configured by environment variables. See: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md. | +| Trace Honeycomb API Key | `CODER_TRACE_HONEYCOMB_API_KEY` | [`--trace-honeycomb-api-key`](../../reference/cli/server.md#--trace-honeycomb-api-key) | - | - | Enables trace exporting to Honeycomb.io using the provided API Key. | + +## Introspection / pprof + +| Setting | Env var | Flag | YAML | Default | Description | +|---------------|-----------------------|--------------------------------------------------------------------|-------------------------------|------------------|--------------------------------------------------------------| +| pprof Address | `CODER_PPROF_ADDRESS` | [`--pprof-address`](../../reference/cli/server.md#--pprof-address) | `introspection.pprof.address` | `127.0.0.1:6060` | The bind address to serve pprof. | +| pprof Enable | `CODER_PPROF_ENABLE` | [`--pprof-enable`](../../reference/cli/server.md#--pprof-enable) | `introspection.pprof.enable` | - | Serve pprof metrics on the address defined by pprof address. | + +## Networking + +| Setting | Env var | Flag | YAML | Default | Description | +|------------------------|--------------------------------|--------------------------------------------------------------------------------------|----------------------------------|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Access URL | `CODER_ACCESS_URL` | [`--access-url`](../../reference/cli/server.md#--access-url) | `networking.accessURL` | - | The URL that users will use to access the Coder deployment. | +| Browser Only | `CODER_BROWSER_ONLY` | [`--browser-only`](../../reference/cli/server.md#--browser-only) | `networking.browserOnly` | - | Whether Coder only allows connections to workspaces via the browser. | +| Docs URL | `CODER_DOCS_URL` | [`--docs-url`](../../reference/cli/server.md#--docs-url) | `networking.docsURL` | `https://coder.com/docs` | Specifies the custom docs URL. | +| Proxy Trusted Headers | `CODER_PROXY_TRUSTED_HEADERS` | [`--proxy-trusted-headers`](../../reference/cli/server.md#--proxy-trusted-headers) | `networking.proxyTrustedHeaders` | - | Headers to trust for forwarding IP addresses. e.g. Cf-Connecting-Ip, True-Client-Ip, X-Forwarded-For. | +| Proxy Trusted Origins | `CODER_PROXY_TRUSTED_ORIGINS` | [`--proxy-trusted-origins`](../../reference/cli/server.md#--proxy-trusted-origins) | `networking.proxyTrustedOrigins` | - | Origin addresses to respect "proxy-trusted-headers". e.g. 192.168.1.0/24. | +| Redirect to Access URL | `CODER_REDIRECT_TO_ACCESS_URL` | [`--redirect-to-access-url`](../../reference/cli/server.md#--redirect-to-access-url) | `networking.redirectToAccessURL` | - | Specifies whether to redirect requests that do not match the access URL host. | +| SameSite Auth Cookie | `CODER_SAMESITE_AUTH_COOKIE` | [`--samesite-auth-cookie`](../../reference/cli/server.md#--samesite-auth-cookie) | `networking.sameSiteAuthCookie` | `lax` | Controls the 'SameSite' property is set on browser session cookies. | +| Secure Auth Cookie | `CODER_SECURE_AUTH_COOKIE` | [`--secure-auth-cookie`](../../reference/cli/server.md#--secure-auth-cookie) | `networking.secureAuthCookie` | `(dynamic)` | Controls if the 'Secure' property is set on browser session cookies. | +| Wildcard Access URL | `CODER_WILDCARD_ACCESS_URL` | [`--wildcard-access-url`](../../reference/cli/server.md#--wildcard-access-url) | `networking.wildcardAccessURL` | - | Specifies the wildcard hostname to use for workspace applications in the form "*.example.com". | +| __Host Prefix Cookies | `CODER_HOST_PREFIX_COOKIE` | [`--host-prefix-cookie`](../../reference/cli/server.md#--host-prefix-cookie) | `networking.hostPrefixCookie` | `false` | Recommended to be enabled. Enables `__Host-` prefix for cookies to guarantee they are only set by the right domain. This change is disruptive to any workspaces built before release 2.31, requiring a workspace restart. | + +## Networking / DERP + +| Setting | Env var | Flag | YAML | Default | Description | +|----------------------------|------------------------------------|----------------------------------------------------------------------------------------------|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Block Direct Connections | `CODER_BLOCK_DIRECT` | [`--block-direct-connections`](../../reference/cli/server.md#--block-direct-connections) | `networking.derp.blockDirect` | - | Block peer-to-peer (aka. direct) workspace connections. All workspace connections from the CLI will be proxied through Coder (or custom configured DERP servers) and will never be peer-to-peer when enabled. Workspaces may still reach out to STUN servers to get their address until they are restarted after this change has been made, but new connections will still be proxied regardless. | +| DERP Config Path | `CODER_DERP_CONFIG_PATH` | [`--derp-config-path`](../../reference/cli/server.md#--derp-config-path) | `networking.derp.configPath` | - | Path to read a DERP mapping from. See: https://tailscale.com/kb/1118/custom-derp-servers/. | +| DERP Config URL | `CODER_DERP_CONFIG_URL` | [`--derp-config-url`](../../reference/cli/server.md#--derp-config-url) | `networking.derp.url` | - | URL to fetch a DERP mapping on startup. See: https://tailscale.com/kb/1118/custom-derp-servers/. | +| DERP Force WebSockets | `CODER_DERP_FORCE_WEBSOCKETS` | [`--derp-force-websockets`](../../reference/cli/server.md#--derp-force-websockets) | `networking.derp.forceWebSockets` | - | Force clients and agents to always use WebSocket to connect to DERP relay servers. By default, DERP uses `Upgrade: derp`, which may cause issues with some reverse proxies. Clients may automatically fallback to WebSocket if they detect an issue with `Upgrade: derp`, but this does not work in all situations. | +| DERP Server Enable | `CODER_DERP_SERVER_ENABLE` | [`--derp-server-enable`](../../reference/cli/server.md#--derp-server-enable) | `networking.derp.enable` | `true` | Whether to enable or disable the embedded DERP relay server. | +| DERP Server Region Name | `CODER_DERP_SERVER_REGION_NAME` | [`--derp-server-region-name`](../../reference/cli/server.md#--derp-server-region-name) | `networking.derp.regionName` | `Coder Embedded Relay` | Region name that for the embedded DERP server. | +| DERP Server Relay URL | `CODER_DERP_SERVER_RELAY_URL` | [`--derp-server-relay-url`](../../reference/cli/server.md#--derp-server-relay-url) | `networking.derp.relayURL` | - | An HTTP URL that is accessible by other replicas to relay DERP traffic. Required for high availability. | +| DERP Server STUN Addresses | `CODER_DERP_SERVER_STUN_ADDRESSES` | [`--derp-server-stun-addresses`](../../reference/cli/server.md#--derp-server-stun-addresses) | `networking.derp.stunAddresses` | `stun.l.google.com:19302,stun1.l.google.com:19302,stun2.l.google.com:19302,stun3.l.google.com:19302,stun4.l.google.com:19302` | Addresses for STUN servers to establish P2P connections. It's recommended to have at least two STUN servers to give users the best chance of connecting P2P to workspaces. Each STUN server will get it's own DERP region, with region IDs starting at `--derp-server-region-id + 1`. Use special value 'disable' to turn off STUN completely. | + +## Networking / HTTP + +| Setting | Env var | Flag | YAML | Default | Description | +|---------------------------------|----------------------------------------|------------------------------------------------------------------------------------------------------|-----------------------------------------------|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Additional CSP Policy | `CODER_ADDITIONAL_CSP_POLICY` | [`--additional-csp-policy`](../../reference/cli/server.md#--additional-csp-policy) | `networking.http.additionalCSPPolicy` | - | Coder configures a Content Security Policy (CSP) to protect against XSS attacks. This setting allows you to add additional CSP directives, which can open the attack surface of the deployment. Format matches the CSP directive format, e.g. --additional-csp-policy="script-src https://example.com". | +| Disable Password Authentication | `CODER_DISABLE_PASSWORD_AUTH` | [`--disable-password-auth`](../../reference/cli/server.md#--disable-password-auth) | `networking.http.disablePasswordAuth` | - | Disable password authentication. This is recommended for security purposes in production deployments that rely on an identity provider. Any user with the owner role will be able to sign in with their password regardless of this setting to avoid potential lock out. If you are locked out of your account, you can use the `coder server create-admin` command to create a new admin user directly in the database. | +| Disable Session Expiry Refresh | `CODER_DISABLE_SESSION_EXPIRY_REFRESH` | [`--disable-session-expiry-refresh`](../../reference/cli/server.md#--disable-session-expiry-refresh) | `networking.http.disableSessionExpiryRefresh` | - | Disable automatic session expiry bumping due to activity. This forces all sessions to become invalid after the session expiry duration has been reached. | +| HTTP Address | `CODER_HTTP_ADDRESS` | [`--http-address`](../../reference/cli/server.md#--http-address) | `networking.http.httpAddress` | `127.0.0.1:3000` | HTTP bind address of the server. Unset to disable the HTTP endpoint. | +| Max Token Lifetime | `CODER_MAX_TOKEN_LIFETIME` | [`--max-token-lifetime`](../../reference/cli/server.md#--max-token-lifetime) | `networking.http.maxTokenLifetime` | `876600h0m0s` | The maximum lifetime duration users can specify when creating an API token. | +| Maximum Admin Token Lifetime | `CODER_MAX_ADMIN_TOKEN_LIFETIME` | [`--max-admin-token-lifetime`](../../reference/cli/server.md#--max-admin-token-lifetime) | `networking.http.maxAdminTokenLifetime` | `168h0m0s` | The maximum lifetime duration administrators can specify when creating an API token. | +| Proxy Health Check Interval | `CODER_PROXY_HEALTH_INTERVAL` | [`--proxy-health-interval`](../../reference/cli/server.md#--proxy-health-interval) | `networking.http.proxyHealthInterval` | `1m0s` | The interval in which coderd should be checking the status of workspace proxies. | +| Session Duration | `CODER_SESSION_DURATION` | [`--session-duration`](../../reference/cli/server.md#--session-duration) | `networking.http.sessionDuration` | `24h0m0s` | The token expiry duration for browser sessions. Sessions may last longer if they are actively making requests, but this functionality can be disabled via --disable-session-expiry-refresh. | + +## Networking / TLS + +| Setting | Env var | Flag | YAML | Default | Description | +|-----------------------------------|-------------------------------------------|------------------------------------------------------------------------------------------------------------|-------------------------------------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Strict-Transport-Security | `CODER_STRICT_TRANSPORT_SECURITY` | [`--strict-transport-security`](../../reference/cli/server.md#--strict-transport-security) | `networking.tls.strictTransportSecurity` | `0` | Controls if the 'Strict-Transport-Security' header is set on all static file responses. This header should only be set if the server is accessed via HTTPS. This value is the MaxAge in seconds of the header. | +| Strict-Transport-Security Options | `CODER_STRICT_TRANSPORT_SECURITY_OPTIONS` | [`--strict-transport-security-options`](../../reference/cli/server.md#--strict-transport-security-options) | `networking.tls.strictTransportSecurityOptions` | - | Two optional fields can be set in the Strict-Transport-Security header; 'includeSubDomains' and 'preload'. The 'strict-transport-security' flag must be set to a non-zero value for these options to be used. | +| TLS Address | `CODER_TLS_ADDRESS` | [`--tls-address`](../../reference/cli/server.md#--tls-address) | `networking.tls.address` | `127.0.0.1:3443` | HTTPS bind address of the server. | +| TLS Allow Insecure Ciphers | `CODER_TLS_ALLOW_INSECURE_CIPHERS` | [`--tls-allow-insecure-ciphers`](../../reference/cli/server.md#--tls-allow-insecure-ciphers) | `networking.tls.tlsAllowInsecureCiphers` | `false` | By default, only ciphers marked as 'secure' are allowed to be used. See https://github.com/golang/go/blob/master/src/crypto/tls/cipher_suites.go#L82-L95. | +| TLS Certificate Files | `CODER_TLS_CERT_FILE` | [`--tls-cert-file`](../../reference/cli/server.md#--tls-cert-file) | `networking.tls.certFiles` | - | Path to each 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. | +| TLS Ciphers | `CODER_TLS_CIPHERS` | [`--tls-ciphers`](../../reference/cli/server.md#--tls-ciphers) | `networking.tls.tlsCiphers` | - | Specify specific TLS ciphers that allowed to be used. See https://github.com/golang/go/blob/master/src/crypto/tls/cipher_suites.go#L53-L75. | +| TLS Client Auth | `CODER_TLS_CLIENT_AUTH` | [`--tls-client-auth`](../../reference/cli/server.md#--tls-client-auth) | `networking.tls.clientAuth` | `none` | Policy the server will follow for TLS Client Authentication. Accepted values are "none", "request", "require-any", "verify-if-given", or "require-and-verify". | +| TLS Client CA Files | `CODER_TLS_CLIENT_CA_FILE` | [`--tls-client-ca-file`](../../reference/cli/server.md#--tls-client-ca-file) | `networking.tls.clientCAFile` | - | PEM-encoded Certificate Authority file used for checking the authenticity of client. | +| TLS Client Cert File | `CODER_TLS_CLIENT_CERT_FILE` | [`--tls-client-cert-file`](../../reference/cli/server.md#--tls-client-cert-file) | `networking.tls.clientCertFile` | - | Path to certificate for client TLS authentication. It requires a PEM-encoded file. | +| TLS Client Key File | `CODER_TLS_CLIENT_KEY_FILE` | [`--tls-client-key-file`](../../reference/cli/server.md#--tls-client-key-file) | `networking.tls.clientKeyFile` | - | Path to key for client TLS authentication. It requires a PEM-encoded file. | +| TLS Enable | `CODER_TLS_ENABLE` | [`--tls-enable`](../../reference/cli/server.md#--tls-enable) | `networking.tls.enable` | - | Whether TLS will be enabled. | +| TLS Key Files | `CODER_TLS_KEY_FILE` | [`--tls-key-file`](../../reference/cli/server.md#--tls-key-file) | `networking.tls.keyFiles` | - | Paths to the private keys for each of the certificates. It requires a PEM-encoded file. | +| TLS Minimum Version | `CODER_TLS_MIN_VERSION` | [`--tls-min-version`](../../reference/cli/server.md#--tls-min-version) | `networking.tls.minVersion` | `tls12` | Minimum supported version of TLS. Accepted values are "tls10", "tls11", "tls12" or "tls13". | + +## Notifications + +| Setting | Env var | Flag | YAML | Default | Description | +|----------------------------------|-----------------------------------------|--------------------------------------------------------------------------------------------------------|---------------------------------|---------|-----------------------------------------------------------------------| +| Notifications: Dispatch Timeout | `CODER_NOTIFICATIONS_DISPATCH_TIMEOUT` | [`--notifications-dispatch-timeout`](../../reference/cli/server.md#--notifications-dispatch-timeout) | `notifications.dispatchTimeout` | `1m0s` | How long to wait while a notification is being sent before giving up. | +| Notifications: Max Send Attempts | `CODER_NOTIFICATIONS_MAX_SEND_ATTEMPTS` | [`--notifications-max-send-attempts`](../../reference/cli/server.md#--notifications-max-send-attempts) | `notifications.maxSendAttempts` | `5` | The upper limit of attempts to send a notification. | +| Notifications: Method | `CODER_NOTIFICATIONS_METHOD` | [`--notifications-method`](../../reference/cli/server.md#--notifications-method) | `notifications.method` | `smtp` | Which delivery method to use (available options: 'smtp', 'webhook'). | + +## Notifications / Email + +| Setting | Env var | Flag | YAML | Default | Description | +|------------------------------------|---------------------------------------|----------------------------------------------------------------------------------------------------|---------------------------------|---------|-----------------------------------------------------------| +| Notifications: Email: Force TLS | `CODER_NOTIFICATIONS_EMAIL_FORCE_TLS` | [`--notifications-email-force-tls`](../../reference/cli/server.md#--notifications-email-force-tls) | `notifications.email.forceTLS` | - | Force a TLS connection to the configured SMTP smarthost. | +| Notifications: Email: From Address | `CODER_NOTIFICATIONS_EMAIL_FROM` | [`--notifications-email-from`](../../reference/cli/server.md#--notifications-email-from) | `notifications.email.from` | - | The sender's address to use. | +| Notifications: Email: Hello | `CODER_NOTIFICATIONS_EMAIL_HELLO` | [`--notifications-email-hello`](../../reference/cli/server.md#--notifications-email-hello) | `notifications.email.hello` | - | The hostname identifying the SMTP server. | +| Notifications: Email: Smarthost | `CODER_NOTIFICATIONS_EMAIL_SMARTHOST` | [`--notifications-email-smarthost`](../../reference/cli/server.md#--notifications-email-smarthost) | `notifications.email.smarthost` | - | The intermediary SMTP host through which emails are sent. | + +## Notifications / Email / Email Authentication + +| Setting | Env var | Flag | YAML | Default | Description | +|------------------------------------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|----------------------------------------------|---------|---------------------------------------------------------------------------| +| Notifications: Email Auth: Identity | `CODER_NOTIFICATIONS_EMAIL_AUTH_IDENTITY` | [`--notifications-email-auth-identity`](../../reference/cli/server.md#--notifications-email-auth-identity) | `notifications.email.emailAuth.identity` | - | Identity to use with PLAIN authentication. | +| Notifications: Email Auth: Password | `CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD` | [`--notifications-email-auth-password`](../../reference/cli/server.md#--notifications-email-auth-password) | - | - | Password to use with PLAIN/LOGIN authentication. | +| Notifications: Email Auth: Password File | `CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD_FILE` | [`--notifications-email-auth-password-file`](../../reference/cli/server.md#--notifications-email-auth-password-file) | `notifications.email.emailAuth.passwordFile` | - | File from which to load password for use with PLAIN/LOGIN authentication. | +| Notifications: Email Auth: Username | `CODER_NOTIFICATIONS_EMAIL_AUTH_USERNAME` | [`--notifications-email-auth-username`](../../reference/cli/server.md#--notifications-email-auth-username) | `notifications.email.emailAuth.username` | - | Username to use with PLAIN/LOGIN authentication. | + +## Notifications / Email / Email TLS + +| Setting | Env var | Flag | YAML | Default | Description | +|--------------------------------------------------------------------|---------------------------------------------|--------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|---------|------------------------------------------------------------------| +| Notifications: Email TLS: Certificate Authority File | `CODER_NOTIFICATIONS_EMAIL_TLS_CACERTFILE` | [`--notifications-email-tls-ca-cert-file`](../../reference/cli/server.md#--notifications-email-tls-ca-cert-file) | `notifications.email.emailTLS.caCertFile` | - | CA certificate file to use. | +| Notifications: Email TLS: Certificate File | `CODER_NOTIFICATIONS_EMAIL_TLS_CERTFILE` | [`--notifications-email-tls-cert-file`](../../reference/cli/server.md#--notifications-email-tls-cert-file) | `notifications.email.emailTLS.certFile` | - | Certificate file to use. | +| Notifications: Email TLS: Certificate Key File | `CODER_NOTIFICATIONS_EMAIL_TLS_CERTKEYFILE` | [`--notifications-email-tls-cert-key-file`](../../reference/cli/server.md#--notifications-email-tls-cert-key-file) | `notifications.email.emailTLS.certKeyFile` | - | Certificate key file to use. | +| Notifications: Email TLS: Server Name | `CODER_NOTIFICATIONS_EMAIL_TLS_SERVERNAME` | [`--notifications-email-tls-server-name`](../../reference/cli/server.md#--notifications-email-tls-server-name) | `notifications.email.emailTLS.serverName` | - | Server name to verify against the target certificate. | +| Notifications: Email TLS: Skip Certificate Verification (Insecure) | `CODER_NOTIFICATIONS_EMAIL_TLS_SKIPVERIFY` | [`--notifications-email-tls-skip-verify`](../../reference/cli/server.md#--notifications-email-tls-skip-verify) | `notifications.email.emailTLS.insecureSkipVerify` | - | Skip verification of the target server's certificate (insecure). | +| Notifications: Email TLS: StartTLS | `CODER_NOTIFICATIONS_EMAIL_TLS_STARTTLS` | [`--notifications-email-tls-starttls`](../../reference/cli/server.md#--notifications-email-tls-starttls) | `notifications.email.emailTLS.startTLS` | - | Enable STARTTLS to upgrade insecure SMTP connections using TLS. | + +## Notifications / Inbox + +| Setting | Env var | Flag | YAML | Default | Description | +|-------------------------------|-------------------------------------|------------------------------------------------------------------------------------------------|-------------------------------|---------|---------------------| +| Notifications: Inbox: Enabled | `CODER_NOTIFICATIONS_INBOX_ENABLED` | [`--notifications-inbox-enabled`](../../reference/cli/server.md#--notifications-inbox-enabled) | `notifications.inbox.enabled` | `true` | Enable Coder Inbox. | + +## Notifications / Webhook + +| Setting | Env var | Flag | YAML | Default | Description | +|----------------------------------|----------------------------------------|------------------------------------------------------------------------------------------------------|----------------------------------|---------|-----------------------------------------| +| Notifications: Webhook: Endpoint | `CODER_NOTIFICATIONS_WEBHOOK_ENDPOINT` | [`--notifications-webhook-endpoint`](../../reference/cli/server.md#--notifications-webhook-endpoint) | `notifications.webhook.endpoint` | - | The endpoint to which to send webhooks. | + +## OAuth2 / GitHub + +| Setting | Env var | Flag | YAML | Default | Description | +|---------------------------------------|-----------------------------------------------|--------------------------------------------------------------------------------------------------------------------|---------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------| +| OAuth2 GitHub Allow Everyone | `CODER_OAUTH2_GITHUB_ALLOW_EVERYONE` | [`--oauth2-github-allow-everyone`](../../reference/cli/server.md#--oauth2-github-allow-everyone) | `oauth2.github.allowEveryone` | - | Allow all logins, setting this option means allowed orgs and teams must be empty. | +| OAuth2 GitHub Allow Signups | `CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS` | [`--oauth2-github-allow-signups`](../../reference/cli/server.md#--oauth2-github-allow-signups) | `oauth2.github.allowSignups` | - | Whether new users can sign up with GitHub. | +| OAuth2 GitHub Allowed Orgs | `CODER_OAUTH2_GITHUB_ALLOWED_ORGS` | [`--oauth2-github-allowed-orgs`](../../reference/cli/server.md#--oauth2-github-allowed-orgs) | `oauth2.github.allowedOrgs` | - | Organizations the user must be a member of to Login with GitHub. | +| OAuth2 GitHub Allowed Teams | `CODER_OAUTH2_GITHUB_ALLOWED_TEAMS` | [`--oauth2-github-allowed-teams`](../../reference/cli/server.md#--oauth2-github-allowed-teams) | `oauth2.github.allowedTeams` | - | Teams inside organizations the user must be a member of to Login with GitHub. Structured as: /. | +| OAuth2 GitHub Client ID | `CODER_OAUTH2_GITHUB_CLIENT_ID` | [`--oauth2-github-client-id`](../../reference/cli/server.md#--oauth2-github-client-id) | `oauth2.github.clientID` | - | Client ID for Login with GitHub. | +| OAuth2 GitHub Client Secret | `CODER_OAUTH2_GITHUB_CLIENT_SECRET` | [`--oauth2-github-client-secret`](../../reference/cli/server.md#--oauth2-github-client-secret) | - | - | Client secret for Login with GitHub. | +| OAuth2 GitHub Default Provider Enable | `CODER_OAUTH2_GITHUB_DEFAULT_PROVIDER_ENABLE` | [`--oauth2-github-default-provider-enable`](../../reference/cli/server.md#--oauth2-github-default-provider-enable) | `oauth2.github.defaultProviderEnable` | `true` | Enable the default GitHub OAuth2 provider managed by Coder. | +| OAuth2 GitHub Device Flow | `CODER_OAUTH2_GITHUB_DEVICE_FLOW` | [`--oauth2-github-device-flow`](../../reference/cli/server.md#--oauth2-github-device-flow) | `oauth2.github.deviceFlow` | `false` | Enable device flow for Login with GitHub. | +| OAuth2 GitHub Enterprise Base URL | `CODER_OAUTH2_GITHUB_ENTERPRISE_BASE_URL` | [`--oauth2-github-enterprise-base-url`](../../reference/cli/server.md#--oauth2-github-enterprise-base-url) | `oauth2.github.enterpriseBaseURL` | - | Base URL of a GitHub Enterprise deployment to use for Login with GitHub. | + +## OIDC + +| Setting | Env var | Flag | YAML | Default | Description | +|-------------------------------------------|-------------------------------------------|------------------------------------------------------------------------------------------------------------|----------------------------------|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Enable OIDC Group Auto Create | `CODER_OIDC_GROUP_AUTO_CREATE` | [`--oidc-group-auto-create`](../../reference/cli/server.md#--oidc-group-auto-create) | `oidc.enableGroupAutoCreate` | `false` | Automatically creates missing groups from a user's groups claim. | +| OIDC Allow Signups | `CODER_OIDC_ALLOW_SIGNUPS` | [`--oidc-allow-signups`](../../reference/cli/server.md#--oidc-allow-signups) | `oidc.allowSignups` | `true` | Whether new users can sign up with OIDC. | +| OIDC Allowed Groups | `CODER_OIDC_ALLOWED_GROUPS` | [`--oidc-allowed-groups`](../../reference/cli/server.md#--oidc-allowed-groups) | `oidc.groupAllowed` | - | If provided any group name not in the list will not be allowed to authenticate. This allows for restricting access to a specific set of groups. This filter is applied after the group mapping and before the regex filter. | +| OIDC Auth URL Parameters | `CODER_OIDC_AUTH_URL_PARAMS` | [`--oidc-auth-url-params`](../../reference/cli/server.md#--oidc-auth-url-params) | `oidc.authURLParams` | `{"access_type": "offline"}` | OIDC auth URL parameters to pass to the upstream provider. | +| OIDC Client Cert File | `CODER_OIDC_CLIENT_CERT_FILE` | [`--oidc-client-cert-file`](../../reference/cli/server.md#--oidc-client-cert-file) | `oidc.oidcClientCertFile` | - | Pem encoded certificate file to use for oauth2 PKI/JWT authorization. The public certificate that accompanies oidc-client-key-file. A standard x509 certificate is expected. | +| OIDC Client ID | `CODER_OIDC_CLIENT_ID` | [`--oidc-client-id`](../../reference/cli/server.md#--oidc-client-id) | `oidc.clientID` | - | Client ID to use for Login with OIDC. | +| OIDC Client Key File | `CODER_OIDC_CLIENT_KEY_FILE` | [`--oidc-client-key-file`](../../reference/cli/server.md#--oidc-client-key-file) | `oidc.oidcClientKeyFile` | - | Pem encoded RSA private key to use for oauth2 PKI/JWT authorization. This can be used instead of oidc-client-secret if your IDP supports it. | +| OIDC Client Secret | `CODER_OIDC_CLIENT_SECRET` | [`--oidc-client-secret`](../../reference/cli/server.md#--oidc-client-secret) | - | - | Client secret to use for Login with OIDC. | +| OIDC Email Domain | `CODER_OIDC_EMAIL_DOMAIN` | [`--oidc-email-domain`](../../reference/cli/server.md#--oidc-email-domain) | `oidc.emailDomain` | - | Email domains that clients logging in with OIDC must match. | +| OIDC Email Field | `CODER_OIDC_EMAIL_FIELD` | [`--oidc-email-field`](../../reference/cli/server.md#--oidc-email-field) | `oidc.emailField` | `email` | OIDC claim field to use as the email. | +| OIDC Group Field | `CODER_OIDC_GROUP_FIELD` | [`--oidc-group-field`](../../reference/cli/server.md#--oidc-group-field) | `oidc.groupField` | - | This field must be set if using the group sync feature and the scope name is not 'groups'. Set to the claim to be used for groups. | +| OIDC Group Mapping | `CODER_OIDC_GROUP_MAPPING` | [`--oidc-group-mapping`](../../reference/cli/server.md#--oidc-group-mapping) | `oidc.groupMapping` | `{}` | A map of OIDC group IDs and the group in Coder it should map to. This is useful for when OIDC providers only return group IDs. | +| OIDC Ignore Email Verified | `CODER_OIDC_IGNORE_EMAIL_VERIFIED` | [`--oidc-ignore-email-verified`](../../reference/cli/server.md#--oidc-ignore-email-verified) | `oidc.ignoreEmailVerified` | - | Ignore the email_verified claim from the upstream provider. | +| OIDC Ignore UserInfo | `CODER_OIDC_IGNORE_USERINFO` | [`--oidc-ignore-userinfo`](../../reference/cli/server.md#--oidc-ignore-userinfo) | `oidc.ignoreUserInfo` | `false` | Ignore the userinfo endpoint and only use the ID token for user information. | +| OIDC Issuer URL | `CODER_OIDC_ISSUER_URL` | [`--oidc-issuer-url`](../../reference/cli/server.md#--oidc-issuer-url) | `oidc.issuerURL` | - | Issuer URL to use for Login with OIDC. | +| OIDC Name Field | `CODER_OIDC_NAME_FIELD` | [`--oidc-name-field`](../../reference/cli/server.md#--oidc-name-field) | `oidc.nameField` | `name` | OIDC claim field to use as the name. | +| OIDC Regex Group Filter | `CODER_OIDC_GROUP_REGEX_FILTER` | [`--oidc-group-regex-filter`](../../reference/cli/server.md#--oidc-group-regex-filter) | `oidc.groupRegexFilter` | `.*` | If provided any group name not matching the regex is ignored. This allows for filtering out groups that are not needed. This filter is applied after the group mapping. | +| OIDC Scopes | `CODER_OIDC_SCOPES` | [`--oidc-scopes`](../../reference/cli/server.md#--oidc-scopes) | `oidc.scopes` | `openid,profile,email` | Scopes to grant when authenticating with OIDC. | +| OIDC User Role Default | `CODER_OIDC_USER_ROLE_DEFAULT` | [`--oidc-user-role-default`](../../reference/cli/server.md#--oidc-user-role-default) | `oidc.userRoleDefault` | - | If user role sync is enabled, these roles are always included for all authenticated users. The 'member' role is always assigned. | +| OIDC User Role Field | `CODER_OIDC_USER_ROLE_FIELD` | [`--oidc-user-role-field`](../../reference/cli/server.md#--oidc-user-role-field) | `oidc.userRoleField` | - | This field must be set if using the user roles sync feature. Set this to the name of the claim used to store the user's role. The roles should be sent as an array of strings. | +| OIDC User Role Mapping | `CODER_OIDC_USER_ROLE_MAPPING` | [`--oidc-user-role-mapping`](../../reference/cli/server.md#--oidc-user-role-mapping) | `oidc.userRoleMapping` | `{}` | A map of the OIDC passed in user roles and the groups in Coder it should map to. This is useful if the group names do not match. If mapped to the empty string, the role will ignored. | +| OIDC Username Field | `CODER_OIDC_USERNAME_FIELD` | [`--oidc-username-field`](../../reference/cli/server.md#--oidc-username-field) | `oidc.usernameField` | `preferred_username` | OIDC claim field to use as the username. | +| OpenID Connect sign in text | `CODER_OIDC_SIGN_IN_TEXT` | [`--oidc-sign-in-text`](../../reference/cli/server.md#--oidc-sign-in-text) | `oidc.signInText` | `OpenID Connect` | The text to show on the OpenID Connect sign in button. | +| OpenID connect icon URL | `CODER_OIDC_ICON_URL` | [`--oidc-icon-url`](../../reference/cli/server.md#--oidc-icon-url) | `oidc.iconURL` | - | URL pointing to the icon to use on the OpenID Connect login button. | +| Signups disabled text | `CODER_OIDC_SIGNUPS_DISABLED_TEXT` | [`--oidc-signups-disabled-text`](../../reference/cli/server.md#--oidc-signups-disabled-text) | `oidc.signupsDisabledText` | - | The custom text to show on the error page informing about disabled OIDC signups. Markdown format is supported. | +| Skip OIDC issuer checks (not recommended) | `CODER_DANGEROUS_OIDC_SKIP_ISSUER_CHECKS` | [`--dangerous-oidc-skip-issuer-checks`](../../reference/cli/server.md#--dangerous-oidc-skip-issuer-checks) | `oidc.dangerousSkipIssuerChecks` | - | OIDC issuer urls must match in the request, the id_token 'iss' claim, and in the well-known configuration. This flag disables that requirement, and can lead to an insecure OIDC configuration. It is not recommended to use this flag. | + +## Provisioning + +| Setting | Env var | Flag | YAML | Default | Description | +|-----------------------------------------|-------------------------------------------|------------------------------------------------------------------------------------------------------------|------------------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------| +| Force Cancel Interval | `CODER_PROVISIONER_FORCE_CANCEL_INTERVAL` | [`--provisioner-force-cancel-interval`](../../reference/cli/server.md#--provisioner-force-cancel-interval) | `provisioning.forceCancelInterval` | `10m0s` | Time to force cancel provisioning tasks that are stuck. | +| Poll Interval | `CODER_PROVISIONER_DAEMON_POLL_INTERVAL` | [`--provisioner-daemon-poll-interval`](../../reference/cli/server.md#--provisioner-daemon-poll-interval) | `provisioning.daemonPollInterval` | `1s` | Deprecated and ignored. | +| Poll Jitter | `CODER_PROVISIONER_DAEMON_POLL_JITTER` | [`--provisioner-daemon-poll-jitter`](../../reference/cli/server.md#--provisioner-daemon-poll-jitter) | `provisioning.daemonPollJitter` | `100ms` | Deprecated and ignored. | +| Provisioner Daemon Pre-shared Key (PSK) | `CODER_PROVISIONER_DAEMON_PSK` | [`--provisioner-daemon-psk`](../../reference/cli/server.md#--provisioner-daemon-psk) | - | - | Pre-shared key to authenticate external provisioner daemons to Coder server. | +| Provisioner Daemons | `CODER_PROVISIONER_DAEMONS` | [`--provisioner-daemons`](../../reference/cli/server.md#--provisioner-daemons) | `provisioning.daemons` | `3` | Number of provisioner daemons to create on start. If builds are stuck in queued state for a long time, consider increasing this. | + +## Retention + +| Setting | Env var | Flag | YAML | Default | Description | +|--------------------------------|----------------------------------------|------------------------------------------------------------------------------------------------------|----------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| API Keys Retention | `CODER_API_KEYS_RETENTION` | [`--api-keys-retention`](../../reference/cli/server.md#--api-keys-retention) | `retention.api_keys` | `7d` | How long expired API keys are retained before being deleted. Keeping expired keys allows the backend to return a more helpful error when a user tries to use an expired key. Set to 0 to disable automatic deletion of expired keys. | +| Audit Logs Retention | `CODER_AUDIT_LOGS_RETENTION` | [`--audit-logs-retention`](../../reference/cli/server.md#--audit-logs-retention) | `retention.audit_logs` | `0` | How long audit log entries are retained. Set to 0 to disable (keep indefinitely). We advise keeping audit logs for at least a year, and in accordance with your compliance requirements. | +| Connection Logs Retention | `CODER_CONNECTION_LOGS_RETENTION` | [`--connection-logs-retention`](../../reference/cli/server.md#--connection-logs-retention) | `retention.connection_logs` | `0` | How long connection log entries are retained. Set to 0 to disable (keep indefinitely). | +| Workspace Agent Logs Retention | `CODER_WORKSPACE_AGENT_LOGS_RETENTION` | [`--workspace-agent-logs-retention`](../../reference/cli/server.md#--workspace-agent-logs-retention) | `retention.workspace_agent_logs` | `7d` | How long workspace agent logs are retained. Logs from non-latest builds are deleted if the agent hasn't connected within this period. Logs from the latest build are always retained. Set to 0 to disable automatic deletion. | + +## Telemetry + +| Setting | Env var | Flag | YAML | Default | Description | +|------------------|--------------------------|------------------------------------------------------------|--------------------|---------|--------------------------------------------------------------------------------------------------------| +| Telemetry Enable | `CODER_TELEMETRY_ENABLE` | [`--telemetry`](../../reference/cli/server.md#--telemetry) | `telemetry.enable` | `true` | Whether telemetry is enabled or not. Coder collects anonymized usage data to help improve our product. | + +## Template Builder + +| Setting | Env var | Flag | YAML | Default | Description | +|-------------------------------|---------------------------------------|----------------------------------------------------------------------------------------------------|-------------------------------|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------| +| Disable Template Builder | `CODER_DISABLE_TEMPLATE_BUILDER` | [`--disable-template-builder`](../../reference/cli/server.md#--disable-template-builder) | `templateBuilder.disabled` | - | Disable the template builder feature for guided template creation. When disabled, all /api/v2/templatebuilder/* endpoints return 404. | +| Template Builder Registry URL | `CODER_TEMPLATE_BUILDER_REGISTRY_URL` | [`--template-builder-registry-url`](../../reference/cli/server.md#--template-builder-registry-url) | `templateBuilder.registryURL` | `https://registry.coder.com` | The base URL of the module registry used by the template builder for module source paths. | + +## User Quiet Hours Schedule + +| Setting | Env var | Flag | YAML | Default | Description | +|------------------------------|--------------------------------------|--------------------------------------------------------------------------------------------------|----------------------------------------------------|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Allow Custom Quiet Hours | `CODER_ALLOW_CUSTOM_QUIET_HOURS` | [`--allow-custom-quiet-hours`](../../reference/cli/server.md#--allow-custom-quiet-hours) | `userQuietHoursSchedule.allowCustomQuietHours` | `true` | Allow users to set their own quiet hours schedule for workspaces to stop in (depending on template autostop requirement settings). If false, users can't change their quiet hours schedule and the site default is always used. | +| Default Quiet Hours Schedule | `CODER_QUIET_HOURS_DEFAULT_SCHEDULE` | [`--default-quiet-hours-schedule`](../../reference/cli/server.md#--default-quiet-hours-schedule) | `userQuietHoursSchedule.defaultQuietHoursSchedule` | `CRON_TZ=UTC 0 0 * * *` | The default daily cron schedule applied to users that haven't set a custom quiet hours schedule themselves. The quiet hours schedule determines when workspaces will be force stopped due to the template's autostop requirement, and will round the max deadline up to be within the user's quiet hours window (or default). The format is the same as the standard cron format, but the day-of-month, month and day-of-week must be *. Only one hour and minute can be specified (ranges or comma separated values are not supported). | + +## Workspace Prebuilds + +| Setting | Env var | Flag | YAML | Default | Description | +|-------------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|---------|---------------------------------------------------| +| Reconciliation Interval | `CODER_WORKSPACE_PREBUILDS_RECONCILIATION_INTERVAL` | [`--workspace-prebuilds-reconciliation-interval`](../../reference/cli/server.md#--workspace-prebuilds-reconciliation-interval) | `workspace_prebuilds.reconciliation_interval` | `1m0s` | How often to reconcile workspace prebuilds state. | + +## ⚠️ Dangerous + +| Setting | Env var | Flag | YAML | Default | Description | +|--------------------------------------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| DANGEROUS: Allow Path App Sharing | `CODER_DANGEROUS_ALLOW_PATH_APP_SHARING` | [`--dangerous-allow-path-app-sharing`](../../reference/cli/server.md#--dangerous-allow-path-app-sharing) | - | - | Allow workspace apps that are not served from subdomains to be shared. Path-based app sharing is DISABLED by default for security purposes. Path-based apps can make requests to the Coder API and pose a security risk when the workspace serves malicious JavaScript. Path-based apps can be disabled entirely with --disable-path-apps for further security. | +| DANGEROUS: Allow Site Owners to Access Path Apps | `CODER_DANGEROUS_ALLOW_PATH_APP_SITE_OWNER_ACCESS` | [`--dangerous-allow-path-app-site-owner-access`](../../reference/cli/server.md#--dangerous-allow-path-app-site-owner-access) | - | - | Allow site-owners to access workspace apps from workspaces they do not own. Owners cannot access path-based apps they do not own by default. Path-based apps can make requests to the Coder API and pose a security risk when the workspace serves malicious JavaScript. Path-based apps can be disabled entirely with --disable-path-apps for further security. | diff --git a/docs/admin/setup/index.md b/docs/admin/setup/index.md index fc3193e3f64d0..41e977d0c6b56 100644 --- a/docs/admin/setup/index.md +++ b/docs/admin/setup/index.md @@ -4,6 +4,11 @@ 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). +> [!TIP] +> Need to look up an exact environment variable, CLI flag, or YAML key for a +> setting? See the [configuration reference](./configuration-reference.md) for +> a searchable table of every option. + ## Access URL `CODER_ACCESS_URL` is required if you are not using the tunnel. Set this to the diff --git a/docs/admin/users/github-auth.md b/docs/admin/users/github-auth.md index 4d07abb1e2e18..01482fdd6fb19 100644 --- a/docs/admin/users/github-auth.md +++ b/docs/admin/users/github-auth.md @@ -85,18 +85,9 @@ CODER_OAUTH2_GITHUB_DEFAULT_PROVIDER_ENABLE=false ## Step 2: Configure Coder with the OAuth credentials -Go to your Coder host and run the following command to start up the Coder server: - -```sh -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" -``` - -> [!NOTE] -> 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: +Coder server reads these settings from environment variables. On a host +running Coder as a system service, add the variables to +`/etc/coder.d/coder.env`: ```sh CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true @@ -105,6 +96,9 @@ CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05" CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c" ``` +Then restart Coder with `sudo service coder restart`. For GitHub Enterprise +support, also set `CODER_OAUTH2_GITHUB_ENTERPRISE_BASE_URL`. + > [!TIP] > To allow everyone to sign up using GitHub, set: > @@ -112,10 +106,7 @@ CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c" > 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: +If deploying Coder via Helm, set the same variables in `values.yaml`: ```yaml coder: @@ -134,12 +125,22 @@ coder: # value: "true" ``` -To upgrade Coder, run: +Then upgrade Coder with: ```sh helm upgrade coder-v2/coder -n -f values.yaml ``` +> [!NOTE] +> Every option above also has an equivalent CLI flag (for example, +> `CODER_OAUTH2_GITHUB_CLIENT_ID` becomes `--oauth2-github-client-id`). +> CLI flags are convenient for ad-hoc invocations of `coder server` during +> local development. For production deployments, prefer environment +> variables so the configuration lives with the service unit, container, or +> Helm chart that manages Coder. See the +> [configuration reference](../setup/configuration-reference.md) for the +> full mapping between environment variables and flags. + 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. diff --git a/docs/manifest.json b/docs/manifest.json index ffa3db636851a..033ebbd7274a9 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -424,6 +424,11 @@ "path": "./admin/setup/appearance.md", "state": ["premium"] }, + { + "title": "Configuration Reference", + "description": "Searchable table of every Coder server setting with its environment variable, CLI flag, and YAML key", + "path": "./admin/setup/configuration-reference.md" + }, { "title": "Telemetry", "description": "Learn what usage telemetry Coder collects", diff --git a/scripts/configdocgen/main.go b/scripts/configdocgen/main.go new file mode 100644 index 0000000000000..00f745e326e39 --- /dev/null +++ b/scripts/configdocgen/main.go @@ -0,0 +1,206 @@ +// Command configdocgen produces a single-page configuration reference for +// Coder server. The page lists every visible deployment option grouped by +// its serpent Group, with columns for the environment variable, CLI flag, +// YAML key, default, and description. The intent is to give operators a +// single searchable lookup table; for the full per-flag detail, the page +// links back to docs/reference/cli/server.md, which the existing +// scripts/clidocgen already generates from the same source. +// +// The source of truth is codersdk.DeploymentValues, so this generator stays +// in sync automatically whenever options are added, renamed, or removed. +package main + +import ( + "flag" + "fmt" + "sort" + "strings" + + "github.com/coder/coder/v2/codersdk" + "github.com/coder/coder/v2/scripts/atomicwrite" + "github.com/coder/flog" + "github.com/coder/serpent" +) + +const header = ` +# Configuration reference + +Coder server is configured primarily through environment variables. This page +lists every option so you can search by environment variable name, CLI flag, or +YAML key. For first-time setup guidance and worked examples, see +[Configure Control Plane Access](./index.md). + +Every option below can be set via: + +- An environment variable (recommended for production deployments running as a + system service, container, or Helm chart). +- A CLI flag passed to ` + "`coder server`" + ` (useful for one-off invocations + and local development). +- A key in a YAML configuration file passed with ` + "`--config`" + `. + +For a full description of each option's accepted values and behavior, follow +the flag link into [` + "`coder server`" + ` CLI reference](../../reference/cli/server.md). + +` + +// row carries the rendered cells for one option. +type row struct { + name string + env string + flag string + yaml string + defValue string + desc string +} + +// section is one heading level of options, grouped by serpent.Group. +type section struct { + title string + rows []row +} + +func main() { + out := flag.String("out", "docs/admin/setup/configuration-reference.md", "path to write the generated reference page") + flag.Parse() + + var vals codersdk.DeploymentValues + opts := vals.Options() + + sections := buildSections(opts) + body := renderSections(sections) + + if err := atomicwrite.File(*out, []byte(header+body)); err != nil { + flog.Fatalf("write %s: %v", *out, err) + } + flog.Successf("wrote %s", *out) +} + +// buildSections groups options by their serpent group, skipping hidden +// options and options that have no environment variable, flag, or YAML key +// (those cannot be set by an operator). +func buildSections(opts serpent.OptionSet) []section { + bySection := map[string]*section{} + var order []string + + for _, opt := range opts { + if opt.Hidden { + continue + } + if opt.Env == "" && opt.Flag == "" && opt.YAML == "" { + continue + } + + title := "General" + if opt.Group != nil { + full := opt.Group.FullName() + if full != "" { + title = full + } + } + if _, ok := bySection[title]; !ok { + s := §ion{title: title} + bySection[title] = s + order = append(order, title) + } + bySection[title].rows = append(bySection[title].rows, optionToRow(opt)) + } + + for _, key := range order { + s := bySection[key] + sort.Slice(s.rows, func(i, j int) bool { + return s.rows[i].name < s.rows[j].name + }) + } + + sort.Strings(order) + // Put General first because it carries the most common first-time setup + // options (Postgres, cache directory, support links, etc.). + for i, key := range order { + if key == "General" && i != 0 { + order = append([]string{"General"}, append(order[:i], order[i+1:]...)...) + break + } + } + result := make([]section, 0, len(order)) + for _, key := range order { + result = append(result, *bySection[key]) + } + return result +} + +func optionToRow(opt serpent.Option) row { + env := dash(opt.Env) + if opt.Env != "" { + env = "`" + opt.Env + "`" + } + + flagCell := dash("") + if opt.Flag != "" { + flagCell = fmt.Sprintf("[`--%s`](../../reference/cli/server.md#--%s)", opt.Flag, opt.Flag) + } + + yamlCell := dash(opt.YAMLPath()) + if opt.YAMLPath() != "" { + yamlCell = "`" + opt.YAMLPath() + "`" + } + + def := opt.Default + if def == "" && opt.DefaultFn != nil { + // DefaultFn results depend on the host environment, so we cannot + // safely evaluate them here. Mark them as dynamic so readers know to + // check the CLI reference for the resolved default. + def = "(dynamic)" + } + defCell := dash(def) + if def != "" { + defCell = "`" + def + "`" + } + + return row{ + name: opt.Name, + env: env, + flag: flagCell, + yaml: yamlCell, + defValue: defCell, + desc: sanitizeDesc(opt.Description), + } +} + +func dash(s string) string { + if s == "" { + return "-" + } + return s +} + +// sanitizeDesc collapses whitespace and escapes pipes so the description fits +// inside a markdown table cell. Long sentences are kept; readers can follow +// the flag link for canonical wording. +func sanitizeDesc(s string) string { + s = strings.TrimSpace(s) + s = strings.ReplaceAll(s, "\n", " ") + s = strings.ReplaceAll(s, "\r", " ") + for strings.Contains(s, " ") { + s = strings.ReplaceAll(s, " ", " ") + } + s = strings.ReplaceAll(s, "|", `\|`) + if s == "" { + return "-" + } + return s +} + +func renderSections(sections []section) string { + var b strings.Builder + for _, sec := range sections { + _, _ = fmt.Fprintf(&b, "## %s\n\n", sec.title) + _, _ = b.WriteString("| Setting | Env var | Flag | YAML | Default | Description |\n") + _, _ = b.WriteString("|---|---|---|---|---|---|\n") + for _, r := range sec.rows { + _, _ = fmt.Fprintf(&b, "| %s | %s | %s | %s | %s | %s |\n", + r.name, r.env, r.flag, r.yaml, r.defValue, r.desc) + } + _, _ = b.WriteString("\n") + } + return b.String() +} From daba9ed6dc202a4aed01cf44a57c1d98a153a76c Mon Sep 17 00:00:00 2001 From: Ben Potter Date: Wed, 10 Jun 2026 01:35:15 +0000 Subject: [PATCH 02/13] docs: wire configuration reference into make gen and make output deterministic --- Makefile | 2 + docs/admin/setup/configuration-reference.md | 46 ++++++++-------- scripts/configdocgen/main.go | 60 ++++++++++++++------- 3 files changed, 65 insertions(+), 43 deletions(-) diff --git a/Makefile b/Makefile index b6f14f3af5b02..46292550e6d8b 100644 --- a/Makefile +++ b/Makefile @@ -1005,6 +1005,7 @@ GEN_FILES := \ docs/reference/cli/index.md \ docs/admin/security/audit-logs.md \ docs/install/releases/feature-stages.md \ + docs/admin/setup/configuration-reference.md \ coderd/apidoc/swagger.json \ docs/manifest.json \ provisioner/terraform/testdata/version \ @@ -1103,6 +1104,7 @@ gen/mark-fresh: docs/reference/cli/index.md \ docs/admin/security/audit-logs.md \ docs/install/releases/feature-stages.md \ + docs/admin/setup/configuration-reference.md \ coderd/apidoc/swagger.json \ docs/manifest.json \ site/e2e/provisionerGenerated.ts \ diff --git a/docs/admin/setup/configuration-reference.md b/docs/admin/setup/configuration-reference.md index 00a491b3a873f..698bc8db17ea3 100644 --- a/docs/admin/setup/configuration-reference.md +++ b/docs/admin/setup/configuration-reference.md @@ -19,29 +19,29 @@ the flag link into [`coder server` CLI reference](../../reference/cli/server.md) ## General -| Setting | Env var | Flag | YAML | Default | Description | -|----------------------------------------------|------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Allow Workspace Renames | `CODER_ALLOW_WORKSPACE_RENAMES` | [`--allow-workspace-renames`](../../reference/cli/server.md#--allow-workspace-renames) | `allowWorkspaceRenames` | `false` | Allow users to rename their workspaces. WARNING: Renaming a workspace can cause Terraform resources that depend on the workspace name to be destroyed and recreated, potentially causing data loss. Only enable this if your templates do not use workspace names in resource identifiers, or if you understand the risks. | -| Cache Directory | `CODER_CACHE_DIRECTORY` | [`--cache-dir`](../../reference/cli/server.md#--cache-dir) | `cacheDir` | `/home/coder/.cache/coder` | The directory to cache temporary files. If unspecified and $CACHE_DIRECTORY is set, it will be used for compatibility with systemd. This directory is NOT safe to be configured as a shared directory across coderd/provisionerd replicas. | -| Default OAuth Refresh Lifetime | `CODER_DEFAULT_OAUTH_REFRESH_LIFETIME` | [`--default-oauth-refresh-lifetime`](../../reference/cli/server.md#--default-oauth-refresh-lifetime) | `defaultOAuthRefreshLifetime` | `720h0m0s` | The default lifetime duration for OAuth2 refresh tokens. This controls how long refresh tokens remain valid after issuance or rotation. | -| Default Token Lifetime | `CODER_DEFAULT_TOKEN_LIFETIME` | [`--default-token-lifetime`](../../reference/cli/server.md#--default-token-lifetime) | `defaultTokenLifetime` | `168h0m0s` | The default lifetime duration for API tokens. This value is used when creating a token without specifying a duration, such as when authenticating the CLI or an IDE plugin. | -| Disable Chat Sharing | `CODER_DISABLE_CHAT_SHARING` | [`--disable-chat-sharing`](../../reference/cli/server.md#--disable-chat-sharing) | `disableChatSharing` | - | Disable chat sharing. Chat ACL checking is disabled and only owners can access their chats. | -| Disable Owner Workspace Access | `CODER_DISABLE_OWNER_WORKSPACE_ACCESS` | [`--disable-owner-workspace-access`](../../reference/cli/server.md#--disable-owner-workspace-access) | `disableOwnerWorkspaceAccess` | - | Remove the permission for the 'owner' role to have workspace execution on all workspaces. This prevents the 'owner' from ssh, apps, and terminal access based on the 'owner' role. They still have their user permissions to access their own workspaces. | -| Disable Path Apps | `CODER_DISABLE_PATH_APPS` | [`--disable-path-apps`](../../reference/cli/server.md#--disable-path-apps) | `disablePathApps` | - | Disable workspace apps that are not served from subdomains. Path-based apps can make requests to the Coder API and pose a security risk when the workspace serves malicious JavaScript. This is recommended for security purposes if a --wildcard-access-url is configured. | -| Disable Workspace Sharing | `CODER_DISABLE_WORKSPACE_SHARING` | [`--disable-workspace-sharing`](../../reference/cli/server.md#--disable-workspace-sharing) | `disableWorkspaceSharing` | - | Disable workspace sharing. Workspace ACL checking is disabled and only owners can have ssh, apps and terminal access to workspaces. Access based on the 'owner' role is also allowed unless disabled via --disable-owner-workspace-access. | -| Enable swagger endpoint | `CODER_SWAGGER_ENABLE` | [`--swagger-enable`](../../reference/cli/server.md#--swagger-enable) | `enableSwagger` | - | Expose the swagger endpoint via /swagger. | -| Experiments | `CODER_EXPERIMENTS` | [`--experiments`](../../reference/cli/server.md#--experiments) | `experiments` | - | Enable one or more experiments. These are not ready for production. Separate multiple experiments with commas, or enter '*' to opt-in to all available experiments. | -| External Auth GitHub Default Provider Enable | `CODER_EXTERNAL_AUTH_GITHUB_DEFAULT_PROVIDER_ENABLE` | [`--external-auth-github-default-provider-enable`](../../reference/cli/server.md#--external-auth-github-default-provider-enable) | `externalAuthGithubDefaultProviderEnable` | `true` | Enable the default GitHub external auth provider managed by Coder. | -| External Token Encryption Keys | `CODER_EXTERNAL_TOKEN_ENCRYPTION_KEYS` | [`--external-token-encryption-keys`](../../reference/cli/server.md#--external-token-encryption-keys) | - | - | Encrypt OIDC and Git authentication tokens with AES-256-GCM in the database. The value must be a comma-separated list of base64-encoded keys. Each key, when base64-decoded, must be exactly 32 bytes in length. The first key will be used to encrypt new values. Subsequent keys will be used as a fallback when decrypting. During normal operation it is recommended to only set one key unless you are in the process of rotating keys with the `coder server dbcrypt rotate` command. | -| Postgres Auth | `CODER_PG_AUTH` | [`--postgres-auth`](../../reference/cli/server.md#--postgres-auth) | `pgAuth` | `password` | Type of auth to use when connecting to postgres. For AWS RDS, using IAM authentication (awsiamrds) is recommended. | -| Postgres Connection Max Idle | `CODER_PG_CONN_MAX_IDLE` | [`--postgres-conn-max-idle`](../../reference/cli/server.md#--postgres-conn-max-idle) | `pgConnMaxIdle` | `auto` | Maximum number of idle connections to the database. Set to "auto" (the default) to use max open / 3. Value must be greater or equal to 0; 0 means explicitly no idle connections. | -| Postgres Connection Max Open | `CODER_PG_CONN_MAX_OPEN` | [`--postgres-conn-max-open`](../../reference/cli/server.md#--postgres-conn-max-open) | `pgConnMaxOpen` | `10` | Maximum number of open connections to the database. Defaults to 10. | -| Postgres Connection URL | `CODER_PG_CONNECTION_URL` | [`--postgres-url`](../../reference/cli/server.md#--postgres-url) | - | - | URL of a PostgreSQL database. 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". Note that any special characters in the URL must be URL-encoded. | -| SCIM API Key | `CODER_SCIM_AUTH_HEADER` | [`--scim-auth-header`](../../reference/cli/server.md#--scim-auth-header) | - | - | Enables SCIM and sets the authentication header for the built-in SCIM server. New users are automatically created with OIDC authentication. | -| SSH Keygen Algorithm | `CODER_SSH_KEYGEN_ALGORITHM` | [`--ssh-keygen-algorithm`](../../reference/cli/server.md#--ssh-keygen-algorithm) | `sshKeygenAlgorithm` | `ed25519` | The algorithm to use for generating ssh keys. Accepted values are "ed25519", "ecdsa", or "rsa4096". | -| Support Links | `CODER_SUPPORT_LINKS` | [`--support-links`](../../reference/cli/server.md#--support-links) | `supportLinks` | - | Support links to display in the top right drop down menu. | -| Terms of Service URL | `CODER_TERMS_OF_SERVICE_URL` | [`--terms-of-service-url`](../../reference/cli/server.md#--terms-of-service-url) | `termsOfServiceURL` | - | A URL to an external Terms of Service that must be accepted by users when logging in. | -| Update Check | `CODER_UPDATE_CHECK` | [`--update-check`](../../reference/cli/server.md#--update-check) | `updateCheck` | `false` | Periodically check for new releases of Coder and inform the owner. The check is performed once per day. | +| Setting | Env var | Flag | YAML | Default | Description | +|----------------------------------------------|------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Allow Workspace Renames | `CODER_ALLOW_WORKSPACE_RENAMES` | [`--allow-workspace-renames`](../../reference/cli/server.md#--allow-workspace-renames) | `allowWorkspaceRenames` | `false` | Allow users to rename their workspaces. WARNING: Renaming a workspace can cause Terraform resources that depend on the workspace name to be destroyed and recreated, potentially causing data loss. Only enable this if your templates do not use workspace names in resource identifiers, or if you understand the risks. | +| Cache Directory | `CODER_CACHE_DIRECTORY` | [`--cache-dir`](../../reference/cli/server.md#--cache-dir) | `cacheDir` | `~/.cache/coder` | The directory to cache temporary files. If unspecified and $CACHE_DIRECTORY is set, it will be used for compatibility with systemd. This directory is NOT safe to be configured as a shared directory across coderd/provisionerd replicas. | +| Default OAuth Refresh Lifetime | `CODER_DEFAULT_OAUTH_REFRESH_LIFETIME` | [`--default-oauth-refresh-lifetime`](../../reference/cli/server.md#--default-oauth-refresh-lifetime) | `defaultOAuthRefreshLifetime` | `720h0m0s` | The default lifetime duration for OAuth2 refresh tokens. This controls how long refresh tokens remain valid after issuance or rotation. | +| Default Token Lifetime | `CODER_DEFAULT_TOKEN_LIFETIME` | [`--default-token-lifetime`](../../reference/cli/server.md#--default-token-lifetime) | `defaultTokenLifetime` | `168h0m0s` | The default lifetime duration for API tokens. This value is used when creating a token without specifying a duration, such as when authenticating the CLI or an IDE plugin. | +| Disable Chat Sharing | `CODER_DISABLE_CHAT_SHARING` | [`--disable-chat-sharing`](../../reference/cli/server.md#--disable-chat-sharing) | `disableChatSharing` | - | Disable chat sharing. Chat ACL checking is disabled and only owners can access their chats. | +| Disable Owner Workspace Access | `CODER_DISABLE_OWNER_WORKSPACE_ACCESS` | [`--disable-owner-workspace-access`](../../reference/cli/server.md#--disable-owner-workspace-access) | `disableOwnerWorkspaceAccess` | - | Remove the permission for the 'owner' role to have workspace execution on all workspaces. This prevents the 'owner' from ssh, apps, and terminal access based on the 'owner' role. They still have their user permissions to access their own workspaces. | +| Disable Path Apps | `CODER_DISABLE_PATH_APPS` | [`--disable-path-apps`](../../reference/cli/server.md#--disable-path-apps) | `disablePathApps` | - | Disable workspace apps that are not served from subdomains. Path-based apps can make requests to the Coder API and pose a security risk when the workspace serves malicious JavaScript. This is recommended for security purposes if a --wildcard-access-url is configured. | +| Disable Workspace Sharing | `CODER_DISABLE_WORKSPACE_SHARING` | [`--disable-workspace-sharing`](../../reference/cli/server.md#--disable-workspace-sharing) | `disableWorkspaceSharing` | - | Disable workspace sharing. Workspace ACL checking is disabled and only owners can have ssh, apps and terminal access to workspaces. Access based on the 'owner' role is also allowed unless disabled via --disable-owner-workspace-access. | +| Enable swagger endpoint | `CODER_SWAGGER_ENABLE` | [`--swagger-enable`](../../reference/cli/server.md#--swagger-enable) | `enableSwagger` | - | Expose the swagger endpoint via /swagger. | +| Experiments | `CODER_EXPERIMENTS` | [`--experiments`](../../reference/cli/server.md#--experiments) | `experiments` | - | Enable one or more experiments. These are not ready for production. Separate multiple experiments with commas, or enter '*' to opt-in to all available experiments. | +| External Auth GitHub Default Provider Enable | `CODER_EXTERNAL_AUTH_GITHUB_DEFAULT_PROVIDER_ENABLE` | [`--external-auth-github-default-provider-enable`](../../reference/cli/server.md#--external-auth-github-default-provider-enable) | `externalAuthGithubDefaultProviderEnable` | `true` | Enable the default GitHub external auth provider managed by Coder. | +| External Token Encryption Keys | `CODER_EXTERNAL_TOKEN_ENCRYPTION_KEYS` | [`--external-token-encryption-keys`](../../reference/cli/server.md#--external-token-encryption-keys) | - | - | Encrypt OIDC and Git authentication tokens with AES-256-GCM in the database. The value must be a comma-separated list of base64-encoded keys. Each key, when base64-decoded, must be exactly 32 bytes in length. The first key will be used to encrypt new values. Subsequent keys will be used as a fallback when decrypting. During normal operation it is recommended to only set one key unless you are in the process of rotating keys with the `coder server dbcrypt rotate` command. | +| Postgres Auth | `CODER_PG_AUTH` | [`--postgres-auth`](../../reference/cli/server.md#--postgres-auth) | `pgAuth` | `password` | Type of auth to use when connecting to postgres. For AWS RDS, using IAM authentication (awsiamrds) is recommended. | +| Postgres Connection Max Idle | `CODER_PG_CONN_MAX_IDLE` | [`--postgres-conn-max-idle`](../../reference/cli/server.md#--postgres-conn-max-idle) | `pgConnMaxIdle` | `auto` | Maximum number of idle connections to the database. Set to "auto" (the default) to use max open / 3. Value must be greater or equal to 0; 0 means explicitly no idle connections. | +| Postgres Connection Max Open | `CODER_PG_CONN_MAX_OPEN` | [`--postgres-conn-max-open`](../../reference/cli/server.md#--postgres-conn-max-open) | `pgConnMaxOpen` | `10` | Maximum number of open connections to the database. Defaults to 10. | +| Postgres Connection URL | `CODER_PG_CONNECTION_URL` | [`--postgres-url`](../../reference/cli/server.md#--postgres-url) | - | - | URL of a PostgreSQL database. 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". Note that any special characters in the URL must be URL-encoded. | +| SCIM API Key | `CODER_SCIM_AUTH_HEADER` | [`--scim-auth-header`](../../reference/cli/server.md#--scim-auth-header) | - | - | Enables SCIM and sets the authentication header for the built-in SCIM server. New users are automatically created with OIDC authentication. | +| SSH Keygen Algorithm | `CODER_SSH_KEYGEN_ALGORITHM` | [`--ssh-keygen-algorithm`](../../reference/cli/server.md#--ssh-keygen-algorithm) | `sshKeygenAlgorithm` | `ed25519` | The algorithm to use for generating ssh keys. Accepted values are "ed25519", "ecdsa", or "rsa4096". | +| Support Links | `CODER_SUPPORT_LINKS` | [`--support-links`](../../reference/cli/server.md#--support-links) | `supportLinks` | - | Support links to display in the top right drop down menu. | +| Terms of Service URL | `CODER_TERMS_OF_SERVICE_URL` | [`--terms-of-service-url`](../../reference/cli/server.md#--terms-of-service-url) | `termsOfServiceURL` | - | A URL to an external Terms of Service that must be accepted by users when logging in. | +| Update Check | `CODER_UPDATE_CHECK` | [`--update-check`](../../reference/cli/server.md#--update-check) | `updateCheck` | `false` | Periodically check for new releases of Coder and inform the owner. The check is performed once per day. | ## AI Gateway diff --git a/scripts/configdocgen/main.go b/scripts/configdocgen/main.go index 00f745e326e39..6603d4e95324c 100644 --- a/scripts/configdocgen/main.go +++ b/scripts/configdocgen/main.go @@ -13,6 +13,7 @@ package main import ( "flag" "fmt" + "os" "sort" "strings" @@ -59,7 +60,38 @@ type section struct { rows []row } +// prepareEnv mirrors scripts/clidocgen so the generated defaults do not +// depend on the generating host. Without it, defaults derived from +// os.UserCacheDir and the config dir embed the local home directory. +func prepareEnv() { + // Unset CODER_ environment variables + for _, env := range os.Environ() { + if strings.HasPrefix(env, "CODER_") { + split := strings.SplitN(env, "=", 2) + if err := os.Unsetenv(split[0]); err != nil { + panic(err) + } + } + } + + // Override default OS values to ensure the same generated results. + err := os.Setenv("CLIDOCGEN_CACHE_DIRECTORY", "~/.cache") + if err != nil { + panic(err) + } + err = os.Setenv("CLIDOCGEN_CONFIG_DIRECTORY", "~/.config/coderv2") + if err != nil { + panic(err) + } + err = os.Setenv("TMPDIR", "/tmp") + if err != nil { + panic(err) + } +} + func main() { + prepareEnv() + out := flag.String("out", "docs/admin/setup/configuration-reference.md", "path to write the generated reference page") flag.Parse() @@ -129,21 +161,11 @@ func buildSections(opts serpent.OptionSet) []section { } func optionToRow(opt serpent.Option) row { - env := dash(opt.Env) - if opt.Env != "" { - env = "`" + opt.Env + "`" - } - - flagCell := dash("") + flagCell := "-" if opt.Flag != "" { flagCell = fmt.Sprintf("[`--%s`](../../reference/cli/server.md#--%s)", opt.Flag, opt.Flag) } - yamlCell := dash(opt.YAMLPath()) - if opt.YAMLPath() != "" { - yamlCell = "`" + opt.YAMLPath() + "`" - } - def := opt.Default if def == "" && opt.DefaultFn != nil { // DefaultFn results depend on the host environment, so we cannot @@ -151,26 +173,24 @@ func optionToRow(opt serpent.Option) row { // check the CLI reference for the resolved default. def = "(dynamic)" } - defCell := dash(def) - if def != "" { - defCell = "`" + def + "`" - } return row{ name: opt.Name, - env: env, + env: codeCell(opt.Env), flag: flagCell, - yaml: yamlCell, - defValue: defCell, + yaml: codeCell(opt.YAMLPath()), + defValue: codeCell(def), desc: sanitizeDesc(opt.Description), } } -func dash(s string) string { +// codeCell wraps s in backticks for a markdown table cell, or returns a dash +// placeholder when s is empty. +func codeCell(s string) string { if s == "" { return "-" } - return s + return "`" + s + "`" } // sanitizeDesc collapses whitespace and escapes pipes so the description fits From 0d44baa8ed3e6d92064bb44de1a35a62a248fb0c Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Mon, 29 Jun 2026 16:41:17 +0000 Subject: [PATCH 03/13] docs: regenerate configuration reference against current deployment values The page committed from the original branch was generated from an older codersdk.DeploymentValues snapshot. Regenerate it so it matches current main: adds CODER_SCIM_USE_LEGACY, the Networking / Cluster section with CODER_CLUSTER_HOST, CODER_BOUNDARY_LOG_RETENTION, and refreshed option descriptions (including the AI Gateway rename). Fixes the gen and check-docs CI failures. --- docs/admin/setup/configuration-reference.md | 46 ++++++++++++--------- 1 file changed, 27 insertions(+), 19 deletions(-) diff --git a/docs/admin/setup/configuration-reference.md b/docs/admin/setup/configuration-reference.md index 698bc8db17ea3..dd6d925be9d54 100644 --- a/docs/admin/setup/configuration-reference.md +++ b/docs/admin/setup/configuration-reference.md @@ -38,6 +38,7 @@ the flag link into [`coder server` CLI reference](../../reference/cli/server.md) | Postgres Connection Max Open | `CODER_PG_CONN_MAX_OPEN` | [`--postgres-conn-max-open`](../../reference/cli/server.md#--postgres-conn-max-open) | `pgConnMaxOpen` | `10` | Maximum number of open connections to the database. Defaults to 10. | | Postgres Connection URL | `CODER_PG_CONNECTION_URL` | [`--postgres-url`](../../reference/cli/server.md#--postgres-url) | - | - | URL of a PostgreSQL database. 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". Note that any special characters in the URL must be URL-encoded. | | SCIM API Key | `CODER_SCIM_AUTH_HEADER` | [`--scim-auth-header`](../../reference/cli/server.md#--scim-auth-header) | - | - | Enables SCIM and sets the authentication header for the built-in SCIM server. New users are automatically created with OIDC authentication. | +| SCIM Use Legacy | `CODER_SCIM_USE_LEGACY` | [`--scim-use-legacy`](../../reference/cli/server.md#--scim-use-legacy) | `scimUseLegacy` | `true` | Use the legacy SCIM implementation instead of the SCIM 2.0 handler. This is provided for backward compatibility for existing users. | | SSH Keygen Algorithm | `CODER_SSH_KEYGEN_ALGORITHM` | [`--ssh-keygen-algorithm`](../../reference/cli/server.md#--ssh-keygen-algorithm) | `sshKeygenAlgorithm` | `ed25519` | The algorithm to use for generating ssh keys. Accepted values are "ed25519", "ecdsa", or "rsa4096". | | Support Links | `CODER_SUPPORT_LINKS` | [`--support-links`](../../reference/cli/server.md#--support-links) | `supportLinks` | - | Support links to display in the top right drop down menu. | | Terms of Service URL | `CODER_TERMS_OF_SERVICE_URL` | [`--terms-of-service-url`](../../reference/cli/server.md#--terms-of-service-url) | `termsOfServiceURL` | - | A URL to an external Terms of Service that must be accepted by users when logging in. | @@ -49,7 +50,7 @@ the flag link into [`coder server` CLI reference](../../reference/cli/server.md) |--------------------------------------|----------------------------------------------|------------------------------------------------------------------------------------------------------------------|---------------------------------------|----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | AI Budget Period | `CODER_AI_BUDGET_PERIOD` | [`--ai-budget-period`](../../reference/cli/server.md#--ai-budget-period) | `ai_gateway.budget_period` | `month` | Determines when accumulated AI spend resets to zero, aligned to UTC calendar boundaries. Only "month" is currently supported. | | AI Budget Policy | `CODER_AI_BUDGET_POLICY` | [`--ai-budget-policy`](../../reference/cli/server.md#--ai-budget-policy) | `ai_gateway.budget_policy` | `highest` | Determines the effective group when a user belongs to multiple groups with AI budgets. "highest" selects the group with the largest spend limit, and is currently the only supported value. | -| AI Gateway API Dump Directory | `CODER_AI_GATEWAY_DUMP_DIR` | [`--ai-gateway-dump-dir`](../../reference/cli/server.md#--ai-gateway-dump-dir) | `ai_gateway.api_dump_dir` | - | Base directory for dumping AI Bridge request/response pairs to disk for debugging. When set, each provider writes under a subdirectory named after the provider. Sensitive headers are redacted. Leave empty to disable. | +| AI Gateway API Dump Directory | `CODER_AI_GATEWAY_DUMP_DIR` | [`--ai-gateway-dump-dir`](../../reference/cli/server.md#--ai-gateway-dump-dir) | `ai_gateway.api_dump_dir` | - | Base directory for dumping AI Gateway request/response pairs to disk for debugging. When set, each provider writes under a subdirectory named after the provider. Sensitive headers are redacted. Leave empty to disable. | | AI Gateway Allow BYOK | `CODER_AI_GATEWAY_ALLOW_BYOK` | [`--ai-gateway-allow-byok`](../../reference/cli/server.md#--ai-gateway-allow-byok) | `ai_gateway.allow_byok` | `true` | Allow users to provide their own LLM API keys or subscriptions. When disabled, only centralized key authentication is permitted. | | AI Gateway Anthropic Base URL | `CODER_AI_GATEWAY_ANTHROPIC_BASE_URL` | [`--ai-gateway-anthropic-base-url`](../../reference/cli/server.md#--ai-gateway-anthropic-base-url) | `ai_gateway.anthropic_base_url` | `https://api.anthropic.com/` | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The base URL of the Anthropic API. | | AI Gateway Anthropic Key | `CODER_AI_GATEWAY_ANTHROPIC_KEY` | [`--ai-gateway-anthropic-key`](../../reference/cli/server.md#--ai-gateway-anthropic-key) | - | - | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The key to authenticate against the Anthropic API. | @@ -92,13 +93,13 @@ the flag link into [`coder server` CLI reference](../../reference/cli/server.md) ## Client -| Setting | Env var | Flag | YAML | Default | Description | -|---------------------------|-----------------------------------|--------------------------------------------------------------------------------------------|----------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| CLI Upgrade Message | `CODER_CLI_UPGRADE_MESSAGE` | [`--cli-upgrade-message`](../../reference/cli/server.md#--cli-upgrade-message) | `client.cliUpgradeMessage` | - | The upgrade message to display to users when a client/server mismatch is detected. By default it instructs users to update using 'curl -L https://coder.com/install.sh \| sh'. | -| Hide AI Tasks | `CODER_HIDE_AI_TASKS` | [`--hide-ai-tasks`](../../reference/cli/server.md#--hide-ai-tasks) | `client.hideAITasks` | `false` | Hide AI tasks from the dashboard. | -| SSH Config Options | `CODER_SSH_CONFIG_OPTIONS` | [`--ssh-config-options`](../../reference/cli/server.md#--ssh-config-options) | `client.sshConfigOptions` | - | These SSH config options will override the default SSH config options. Provide options in "key=value" or "key value" format separated by commas.Using this incorrectly can break SSH to your deployment, use cautiously. | -| Web Terminal Renderer | `CODER_WEB_TERMINAL_RENDERER` | [`--web-terminal-renderer`](../../reference/cli/server.md#--web-terminal-renderer) | `client.webTerminalRenderer` | `canvas` | The renderer to use when opening a web terminal. Valid values are 'canvas', 'webgl', or 'dom'. | -| Workspace Hostname Suffix | `CODER_WORKSPACE_HOSTNAME_SUFFIX` | [`--workspace-hostname-suffix`](../../reference/cli/server.md#--workspace-hostname-suffix) | `client.workspaceHostnameSuffix` | `coder` | Workspace hostnames use this suffix in SSH config and Coder Connect on Coder Desktop. By default it is coder, resulting in names like myworkspace.coder. | +| Setting | Env var | Flag | YAML | Default | Description | +|---------------------------|-----------------------------------|--------------------------------------------------------------------------------------------|----------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| CLI Upgrade Message | `CODER_CLI_UPGRADE_MESSAGE` | [`--cli-upgrade-message`](../../reference/cli/server.md#--cli-upgrade-message) | `client.cliUpgradeMessage` | - | The upgrade message to display to users when a client/server mismatch is detected. By default it instructs users to update using 'curl -L https://coder.com/install.sh \| sh'. | +| Hide AI Tasks | `CODER_HIDE_AI_TASKS` | [`--hide-ai-tasks`](../../reference/cli/server.md#--hide-ai-tasks) | `client.hideAITasks` | `false` | Hide AI tasks from the dashboard. | +| SSH Config Options | `CODER_SSH_CONFIG_OPTIONS` | [`--ssh-config-options`](../../reference/cli/server.md#--ssh-config-options) | `client.sshConfigOptions` | - | These SSH config options will override the default SSH config options. Provide options in "key=value" or "key value" format separated by commas. Using this incorrectly can break SSH to your deployment, use cautiously. The following options are not allowed: Host, Match, Include, ProxyCommand, ProxyJump, LocalCommand, PermitLocalCommand, RemoteCommand, KnownHostsCommand, PKCS11Provider, SecurityKeyProvider, SmartcardDevice, XAuthLocation. Option values must not contain newline, carriage return, or NUL characters. | +| Web Terminal Renderer | `CODER_WEB_TERMINAL_RENDERER` | [`--web-terminal-renderer`](../../reference/cli/server.md#--web-terminal-renderer) | `client.webTerminalRenderer` | `canvas` | The renderer to use when opening a web terminal. Valid values are 'canvas', 'webgl', or 'dom'. | +| Workspace Hostname Suffix | `CODER_WORKSPACE_HOSTNAME_SUFFIX` | [`--workspace-hostname-suffix`](../../reference/cli/server.md#--workspace-hostname-suffix) | `client.workspaceHostnameSuffix` | `coder` | Workspace hostnames use this suffix in SSH config and Coder Connect on Coder Desktop. By default it is coder, resulting in names like myworkspace.coder. The suffix must not start with a dot, and must not contain spaces, newlines, or glob characters (* and ?). | ## Config @@ -192,13 +193,19 @@ the flag link into [`coder server` CLI reference](../../reference/cli/server.md) | Browser Only | `CODER_BROWSER_ONLY` | [`--browser-only`](../../reference/cli/server.md#--browser-only) | `networking.browserOnly` | - | Whether Coder only allows connections to workspaces via the browser. | | Docs URL | `CODER_DOCS_URL` | [`--docs-url`](../../reference/cli/server.md#--docs-url) | `networking.docsURL` | `https://coder.com/docs` | Specifies the custom docs URL. | | Proxy Trusted Headers | `CODER_PROXY_TRUSTED_HEADERS` | [`--proxy-trusted-headers`](../../reference/cli/server.md#--proxy-trusted-headers) | `networking.proxyTrustedHeaders` | - | Headers to trust for forwarding IP addresses. e.g. Cf-Connecting-Ip, True-Client-Ip, X-Forwarded-For. | -| Proxy Trusted Origins | `CODER_PROXY_TRUSTED_ORIGINS` | [`--proxy-trusted-origins`](../../reference/cli/server.md#--proxy-trusted-origins) | `networking.proxyTrustedOrigins` | - | Origin addresses to respect "proxy-trusted-headers". e.g. 192.168.1.0/24. | +| Proxy Trusted Origins | `CODER_PROXY_TRUSTED_ORIGINS` | [`--proxy-trusted-origins`](../../reference/cli/server.md#--proxy-trusted-origins) | `networking.proxyTrustedOrigins` | - | Origin addresses to respect "proxy-trusted-headers" and X-Forwarded-Host for subdomain app routing. e.g. 192.168.1.0/24. | | Redirect to Access URL | `CODER_REDIRECT_TO_ACCESS_URL` | [`--redirect-to-access-url`](../../reference/cli/server.md#--redirect-to-access-url) | `networking.redirectToAccessURL` | - | Specifies whether to redirect requests that do not match the access URL host. | | SameSite Auth Cookie | `CODER_SAMESITE_AUTH_COOKIE` | [`--samesite-auth-cookie`](../../reference/cli/server.md#--samesite-auth-cookie) | `networking.sameSiteAuthCookie` | `lax` | Controls the 'SameSite' property is set on browser session cookies. | | Secure Auth Cookie | `CODER_SECURE_AUTH_COOKIE` | [`--secure-auth-cookie`](../../reference/cli/server.md#--secure-auth-cookie) | `networking.secureAuthCookie` | `(dynamic)` | Controls if the 'Secure' property is set on browser session cookies. | | Wildcard Access URL | `CODER_WILDCARD_ACCESS_URL` | [`--wildcard-access-url`](../../reference/cli/server.md#--wildcard-access-url) | `networking.wildcardAccessURL` | - | Specifies the wildcard hostname to use for workspace applications in the form "*.example.com". | | __Host Prefix Cookies | `CODER_HOST_PREFIX_COOKIE` | [`--host-prefix-cookie`](../../reference/cli/server.md#--host-prefix-cookie) | `networking.hostPrefixCookie` | `false` | Recommended to be enabled. Enables `__Host-` prefix for cookies to guarantee they are only set by the right domain. This change is disruptive to any workspaces built before release 2.31, requiring a workspace restart. | +## Networking / Cluster + +| Setting | Env var | Flag | YAML | Default | Description | +|--------------|----------------------|------------------------------------------------------------------|----------------------------------|---------|----------------------------------------------------------------------| +| Cluster Host | `CODER_CLUSTER_HOST` | [`--cluster-host`](../../reference/cli/server.md#--cluster-host) | `networking.cluster.clusterHost` | - | Hostname or (more commonly) IP to reach this replica for clustering. | + ## Networking / DERP | Setting | Env var | Flag | YAML | Default | Description | @@ -349,12 +356,13 @@ the flag link into [`coder server` CLI reference](../../reference/cli/server.md) ## Retention -| Setting | Env var | Flag | YAML | Default | Description | -|--------------------------------|----------------------------------------|------------------------------------------------------------------------------------------------------|----------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| API Keys Retention | `CODER_API_KEYS_RETENTION` | [`--api-keys-retention`](../../reference/cli/server.md#--api-keys-retention) | `retention.api_keys` | `7d` | How long expired API keys are retained before being deleted. Keeping expired keys allows the backend to return a more helpful error when a user tries to use an expired key. Set to 0 to disable automatic deletion of expired keys. | -| Audit Logs Retention | `CODER_AUDIT_LOGS_RETENTION` | [`--audit-logs-retention`](../../reference/cli/server.md#--audit-logs-retention) | `retention.audit_logs` | `0` | How long audit log entries are retained. Set to 0 to disable (keep indefinitely). We advise keeping audit logs for at least a year, and in accordance with your compliance requirements. | -| Connection Logs Retention | `CODER_CONNECTION_LOGS_RETENTION` | [`--connection-logs-retention`](../../reference/cli/server.md#--connection-logs-retention) | `retention.connection_logs` | `0` | How long connection log entries are retained. Set to 0 to disable (keep indefinitely). | -| Workspace Agent Logs Retention | `CODER_WORKSPACE_AGENT_LOGS_RETENTION` | [`--workspace-agent-logs-retention`](../../reference/cli/server.md#--workspace-agent-logs-retention) | `retention.workspace_agent_logs` | `7d` | How long workspace agent logs are retained. Logs from non-latest builds are deleted if the agent hasn't connected within this period. Logs from the latest build are always retained. Set to 0 to disable automatic deletion. | +| Setting | Env var | Flag | YAML | Default | Description | +|--------------------------------|----------------------------------------|------------------------------------------------------------------------------------------------------|----------------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| API Keys Retention | `CODER_API_KEYS_RETENTION` | [`--api-keys-retention`](../../reference/cli/server.md#--api-keys-retention) | `retention.api_keys` | `7d` | How long expired API keys are retained before being deleted. Keeping expired keys allows the backend to return a more helpful error when a user tries to use an expired key. Set to 0 to disable automatic deletion of expired keys. | +| Audit Logs Retention | `CODER_AUDIT_LOGS_RETENTION` | [`--audit-logs-retention`](../../reference/cli/server.md#--audit-logs-retention) | `retention.audit_logs` | `0` | How long audit log entries are retained. Set to 0 to disable (keep indefinitely). We advise keeping audit logs for at least a year, and in accordance with your compliance requirements. | +| Boundary Log Retention | `CODER_BOUNDARY_LOG_RETENTION` | [`--boundary-log-retention`](../../reference/cli/server.md#--boundary-log-retention) | `retention.boundary_logs` | `0` | How long boundary audit log entries are retained. Boundary logs record HTTP requests processed by a Boundary confinement proxy. Set to 0 to disable automatic deletion (keep indefinitely). Adjust to match your organization's regulatory requirements. | +| Connection Logs Retention | `CODER_CONNECTION_LOGS_RETENTION` | [`--connection-logs-retention`](../../reference/cli/server.md#--connection-logs-retention) | `retention.connection_logs` | `0` | How long connection log entries are retained. Set to 0 to disable (keep indefinitely). | +| Workspace Agent Logs Retention | `CODER_WORKSPACE_AGENT_LOGS_RETENTION` | [`--workspace-agent-logs-retention`](../../reference/cli/server.md#--workspace-agent-logs-retention) | `retention.workspace_agent_logs` | `7d` | How long workspace agent logs are retained. Logs from non-latest builds are deleted if the agent hasn't connected within this period. Logs from the latest build are always retained. Set to 0 to disable automatic deletion. | ## Telemetry @@ -364,10 +372,10 @@ the flag link into [`coder server` CLI reference](../../reference/cli/server.md) ## Template Builder -| Setting | Env var | Flag | YAML | Default | Description | -|-------------------------------|---------------------------------------|----------------------------------------------------------------------------------------------------|-------------------------------|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------| -| Disable Template Builder | `CODER_DISABLE_TEMPLATE_BUILDER` | [`--disable-template-builder`](../../reference/cli/server.md#--disable-template-builder) | `templateBuilder.disabled` | - | Disable the template builder feature for guided template creation. When disabled, all /api/v2/templatebuilder/* endpoints return 404. | -| Template Builder Registry URL | `CODER_TEMPLATE_BUILDER_REGISTRY_URL` | [`--template-builder-registry-url`](../../reference/cli/server.md#--template-builder-registry-url) | `templateBuilder.registryURL` | `https://registry.coder.com` | The base URL of the module registry used by the template builder for module source paths. | +| Setting | Env var | Flag | YAML | Default | Description | +|-------------------------------|---------------------------------------|----------------------------------------------------------------------------------------------------|-------------------------------|----------------------|---------------------------------------------------------------------------------------------------------------------------------------| +| Disable Template Builder | `CODER_DISABLE_TEMPLATE_BUILDER` | [`--disable-template-builder`](../../reference/cli/server.md#--disable-template-builder) | `templateBuilder.disabled` | - | Disable the template builder feature for guided template creation. When disabled, all /api/v2/templatebuilder/* endpoints return 404. | +| Template Builder Registry URL | `CODER_TEMPLATE_BUILDER_REGISTRY_URL` | [`--template-builder-registry-url`](../../reference/cli/server.md#--template-builder-registry-url) | `templateBuilder.registryURL` | `registry.coder.com` | The base URL of the module registry used by the template builder for module source paths. | ## User Quiet Hours Schedule From dbd35d97a6471f29e51b834df8648af36f979bbe Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Mon, 29 Jun 2026 17:02:47 +0000 Subject: [PATCH 04/13] docs: fix configuration reference flag links for check-docs The generator linked every flag to server.md#--, but clidocgen anchors short-form flags by their full heading ("### -l, --log-filter" -> "#-l---log-filter"), so --config and --log-filter pointed at missing anchors. Derive the anchor from FlagShorthand to match. Also ignore the AWS Bedrock base URL in linkspector: it appears as an illustrative https://bedrock-runtime..amazonaws.com placeholder in an option description, matching the existing openai.com ignore patterns. --- .github/.linkspector.yml | 3 +++ docs/admin/setup/configuration-reference.md | 4 ++-- scripts/configdocgen/main.go | 9 ++++++++- 3 files changed, 13 insertions(+), 3 deletions(-) diff --git a/.github/.linkspector.yml b/.github/.linkspector.yml index 88ce877a0a9b8..0cc4d240480bb 100644 --- a/.github/.linkspector.yml +++ b/.github/.linkspector.yml @@ -38,5 +38,8 @@ ignorePatterns: - pattern: "merriam-webster.com" # npmjs.com returns 403 from GitHub runner IPs - pattern: "npmjs.com" + # AWS Bedrock base URL appears as an illustrative placeholder in + # the generated configuration reference, not as a live link. + - pattern: "bedrock-runtime" aliveStatusCodes: - 200 diff --git a/docs/admin/setup/configuration-reference.md b/docs/admin/setup/configuration-reference.md index dd6d925be9d54..2495eb5c8fc37 100644 --- a/docs/admin/setup/configuration-reference.md +++ b/docs/admin/setup/configuration-reference.md @@ -105,7 +105,7 @@ the flag link into [`coder server` CLI reference](../../reference/cli/server.md) | Setting | Env var | Flag | YAML | Default | Description | |--------------|---------------------|------------------------------------------------------------------|------|---------|--------------------------------------------------------| -| Config Path | `CODER_CONFIG_PATH` | [`--config`](../../reference/cli/server.md#--config) | - | - | Specify a YAML file to load configuration from. | +| Config Path | `CODER_CONFIG_PATH` | [`--config`](../../reference/cli/server.md#-c---config) | - | - | Specify a YAML file to load configuration from. | | Write Config | - | [`--write-config`](../../reference/cli/server.md#--write-config) | - | - | Write out the current server config as YAML to stdout. | ## Email @@ -151,7 +151,7 @@ the flag link into [`coder server` CLI reference](../../reference/cli/server.md) | Enable Terraform debug mode | `CODER_ENABLE_TERRAFORM_DEBUG_MODE` | [`--enable-terraform-debug-mode`](../../reference/cli/server.md#--enable-terraform-debug-mode) | `introspection.logging.enableTerraformDebugMode` | `false` | Allow administrators to enable Terraform debug output. | | Human Log Location | `CODER_LOGGING_HUMAN` | [`--log-human`](../../reference/cli/server.md#--log-human) | `introspection.logging.humanPath` | `/dev/stderr` | Output human-readable logs to a given file. | | JSON Log Location | `CODER_LOGGING_JSON` | [`--log-json`](../../reference/cli/server.md#--log-json) | `introspection.logging.jsonPath` | - | Output JSON logs to a given file. | -| Log Filter | `CODER_LOG_FILTER` | [`--log-filter`](../../reference/cli/server.md#--log-filter) | `introspection.logging.filter` | - | Filter debug logs by matching against a given regex. Use .* to match all debug logs. | +| Log Filter | `CODER_LOG_FILTER` | [`--log-filter`](../../reference/cli/server.md#-l---log-filter) | `introspection.logging.filter` | - | Filter debug logs by matching against a given regex. Use .* to match all debug logs. | | Stackdriver Log Location | `CODER_LOGGING_STACKDRIVER` | [`--log-stackdriver`](../../reference/cli/server.md#--log-stackdriver) | `introspection.logging.stackdriverPath` | - | Output Stackdriver compatible logs to a given file. | ## Introspection / Prometheus diff --git a/scripts/configdocgen/main.go b/scripts/configdocgen/main.go index 6603d4e95324c..24f5367c38e01 100644 --- a/scripts/configdocgen/main.go +++ b/scripts/configdocgen/main.go @@ -163,7 +163,14 @@ func buildSections(opts serpent.OptionSet) []section { func optionToRow(opt serpent.Option) row { flagCell := "-" if opt.Flag != "" { - flagCell = fmt.Sprintf("[`--%s`](../../reference/cli/server.md#--%s)", opt.Flag, opt.Flag) + // Link to the heading anchor that clidocgen emits in server.md. Flags + // with a shorthand render as "### -s, --flag" (anchor "-s---flag"); + // flags without one render as "### --flag" (anchor "--flag"). + anchor := "--" + opt.Flag + if opt.FlagShorthand != "" { + anchor = "-" + opt.FlagShorthand + "---" + opt.Flag + } + flagCell = fmt.Sprintf("[`--%s`](../../reference/cli/server.md#%s)", opt.Flag, anchor) } def := opt.Default From 517c38c3f949ec6a42f191b1f291a2c99b2cc908 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Wed, 8 Jul 2026 15:06:04 +0000 Subject: [PATCH 05/13] docs: address configuration reference review feedback Resolve the open findings from the coder-agents-review round: - Pin the Dangerous section to last explicitly via sectionRank instead of relying on the emoji sorting after ASCII letters (CRF-2). - Escape pipe characters in the Setting column so an option name cannot break a table row (CRF-5). - Soften the header's universal claim; the table shows "-" where a method does not apply (CRF-6). - Replace the "(dynamic)" default label with "(computed at runtime)" (CRF-7). - Trim comments that restate the code, per the repo comment rules (CRF-8). - Use strings.Cut and slices.Sort* over strings.SplitN and sort.* (CRF-11, CRF-12). - Make _gen/bin/configdocgen a normal Makefile prerequisite to match clidocgen (CRF-13). - Style guide: use sh fences and a real option (CODER_UPDATE_CHECK) in the examples (CRF-9, CRF-10). - github-auth.md: fix "it's" -> "its" (CRF-14). Regenerate the reference against current main; output is idempotent. Co-authored-by: Coder Agents --- .claude/docs/DOCS_STYLE_GUIDE.md | 8 +- Makefile | 2 +- docs/admin/setup/configuration-reference.md | 5 +- docs/admin/users/github-auth.md | 2 +- scripts/configdocgen/main.go | 96 ++++++++++++--------- 5 files changed, 62 insertions(+), 51 deletions(-) diff --git a/.claude/docs/DOCS_STYLE_GUIDE.md b/.claude/docs/DOCS_STYLE_GUIDE.md index 5045d36738aba..a58c63183406b 100644 --- a/.claude/docs/DOCS_STYLE_GUIDE.md +++ b/.claude/docs/DOCS_STYLE_GUIDE.md @@ -184,17 +184,17 @@ supporting note. Point readers at the for the full mapping between environment variables, flags, and YAML keys. ````markdown -```shell +```sh # Preferred for admin/setup docs: -CODER_DISABLE_TEMPLATE_INSIGHTS=true +CODER_UPDATE_CHECK=false ``` ```` CLI flag form, reserved for ad-hoc invocations: ````markdown -```shell -coder server --disable-template-insights +```sh +coder server --update-check=false ``` ```` diff --git a/Makefile b/Makefile index 46292550e6d8b..b7ae184a19eb4 100644 --- a/Makefile +++ b/Makefile @@ -1351,7 +1351,7 @@ docs/install/releases/feature-stages.md: \ pnpm exec markdown-table-formatter "$$tmpfile" && \ mv "$$tmpfile" "$@" && rm -rf "$$tmpdir" -docs/admin/setup/configuration-reference.md: node_modules/.installed $(wildcard scripts/configdocgen/*.go) $(wildcard codersdk/*.go) | _gen _gen/bin/configdocgen +docs/admin/setup/configuration-reference.md: node_modules/.installed $(wildcard scripts/configdocgen/*.go) $(wildcard codersdk/*.go) _gen/bin/configdocgen | _gen tmpdir=$$(mktemp -d -p _gen) && tmpfile=$$(realpath "$$tmpdir")/$(notdir $@) && \ _gen/bin/configdocgen --out="$$tmpfile" && \ pnpm exec markdownlint-cli2 --fix "$$tmpfile" && \ diff --git a/docs/admin/setup/configuration-reference.md b/docs/admin/setup/configuration-reference.md index 2495eb5c8fc37..d3bfbe1e030b1 100644 --- a/docs/admin/setup/configuration-reference.md +++ b/docs/admin/setup/configuration-reference.md @@ -6,7 +6,8 @@ lists every option so you can search by environment variable name, CLI flag, or YAML key. For first-time setup guidance and worked examples, see [Configure Control Plane Access](./index.md). -Every option below can be set via: +Most options can be set through any of the following. Where a method does not +apply to an option, that column shows `-`. - An environment variable (recommended for production deployments running as a system service, container, or Helm chart). @@ -196,7 +197,7 @@ the flag link into [`coder server` CLI reference](../../reference/cli/server.md) | Proxy Trusted Origins | `CODER_PROXY_TRUSTED_ORIGINS` | [`--proxy-trusted-origins`](../../reference/cli/server.md#--proxy-trusted-origins) | `networking.proxyTrustedOrigins` | - | Origin addresses to respect "proxy-trusted-headers" and X-Forwarded-Host for subdomain app routing. e.g. 192.168.1.0/24. | | Redirect to Access URL | `CODER_REDIRECT_TO_ACCESS_URL` | [`--redirect-to-access-url`](../../reference/cli/server.md#--redirect-to-access-url) | `networking.redirectToAccessURL` | - | Specifies whether to redirect requests that do not match the access URL host. | | SameSite Auth Cookie | `CODER_SAMESITE_AUTH_COOKIE` | [`--samesite-auth-cookie`](../../reference/cli/server.md#--samesite-auth-cookie) | `networking.sameSiteAuthCookie` | `lax` | Controls the 'SameSite' property is set on browser session cookies. | -| Secure Auth Cookie | `CODER_SECURE_AUTH_COOKIE` | [`--secure-auth-cookie`](../../reference/cli/server.md#--secure-auth-cookie) | `networking.secureAuthCookie` | `(dynamic)` | Controls if the 'Secure' property is set on browser session cookies. | +| Secure Auth Cookie | `CODER_SECURE_AUTH_COOKIE` | [`--secure-auth-cookie`](../../reference/cli/server.md#--secure-auth-cookie) | `networking.secureAuthCookie` | `(computed at runtime)` | Controls if the 'Secure' property is set on browser session cookies. | | Wildcard Access URL | `CODER_WILDCARD_ACCESS_URL` | [`--wildcard-access-url`](../../reference/cli/server.md#--wildcard-access-url) | `networking.wildcardAccessURL` | - | Specifies the wildcard hostname to use for workspace applications in the form "*.example.com". | | __Host Prefix Cookies | `CODER_HOST_PREFIX_COOKIE` | [`--host-prefix-cookie`](../../reference/cli/server.md#--host-prefix-cookie) | `networking.hostPrefixCookie` | `false` | Recommended to be enabled. Enables `__Host-` prefix for cookies to guarantee they are only set by the right domain. This change is disruptive to any workspaces built before release 2.31, requiring a workspace restart. | diff --git a/docs/admin/users/github-auth.md b/docs/admin/users/github-auth.md index 01482fdd6fb19..7ed1484898207 100644 --- a/docs/admin/users/github-auth.md +++ b/docs/admin/users/github-auth.md @@ -120,7 +120,7 @@ coder: # 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 + # If allowing everyone, comment out CODER_OAUTH2_GITHUB_ALLOWED_ORGS and its value #- name: CODER_OAUTH2_GITHUB_ALLOW_EVERYONE # value: "true" ``` diff --git a/scripts/configdocgen/main.go b/scripts/configdocgen/main.go index 24f5367c38e01..557dba000d058 100644 --- a/scripts/configdocgen/main.go +++ b/scripts/configdocgen/main.go @@ -1,20 +1,16 @@ -// Command configdocgen produces a single-page configuration reference for -// Coder server. The page lists every visible deployment option grouped by -// its serpent Group, with columns for the environment variable, CLI flag, -// YAML key, default, and description. The intent is to give operators a -// single searchable lookup table; for the full per-flag detail, the page -// links back to docs/reference/cli/server.md, which the existing -// scripts/clidocgen already generates from the same source. -// -// The source of truth is codersdk.DeploymentValues, so this generator stays -// in sync automatically whenever options are added, renamed, or removed. +// Command configdocgen generates the Coder server configuration reference at +// docs/admin/setup/configuration-reference.md from codersdk.DeploymentValues. +// It lists every visible deployment option grouped by serpent group, with its +// environment variable, CLI flag, YAML key, and default. Because the source is +// DeploymentValues, the page stays in sync as options change. package main import ( + "cmp" "flag" "fmt" "os" - "sort" + "slices" "strings" "github.com/coder/coder/v2/codersdk" @@ -31,7 +27,8 @@ lists every option so you can search by environment variable name, CLI flag, or YAML key. For first-time setup guidance and worked examples, see [Configure Control Plane Access](./index.md). -Every option below can be set via: +Most options can be set through any of the following. Where a method does not +apply to an option, that column shows ` + "`-`" + `. - An environment variable (recommended for production deployments running as a system service, container, or Helm chart). @@ -64,17 +61,15 @@ type section struct { // depend on the generating host. Without it, defaults derived from // os.UserCacheDir and the config dir embed the local home directory. func prepareEnv() { - // Unset CODER_ environment variables for _, env := range os.Environ() { if strings.HasPrefix(env, "CODER_") { - split := strings.SplitN(env, "=", 2) - if err := os.Unsetenv(split[0]); err != nil { + name, _, _ := strings.Cut(env, "=") + if err := os.Unsetenv(name); err != nil { panic(err) } } } - // Override default OS values to ensure the same generated results. err := os.Setenv("CLIDOCGEN_CACHE_DIRECTORY", "~/.cache") if err != nil { panic(err) @@ -130,29 +125,25 @@ func buildSections(opts serpent.OptionSet) []section { } } if _, ok := bySection[title]; !ok { - s := §ion{title: title} - bySection[title] = s + bySection[title] = §ion{title: title} order = append(order, title) } bySection[title].rows = append(bySection[title].rows, optionToRow(opt)) } for _, key := range order { - s := bySection[key] - sort.Slice(s.rows, func(i, j int) bool { - return s.rows[i].name < s.rows[j].name + slices.SortFunc(bySection[key].rows, func(a, b row) int { + return strings.Compare(a.name, b.name) }) } - sort.Strings(order) - // Put General first because it carries the most common first-time setup - // options (Postgres, cache directory, support links, etc.). - for i, key := range order { - if key == "General" && i != 0 { - order = append([]string{"General"}, append(order[:i], order[i+1:]...)...) - break + slices.SortStableFunc(order, func(a, b string) int { + if c := cmp.Compare(sectionRank(a), sectionRank(b)); c != 0 { + return c } - } + return strings.Compare(a, b) + }) + result := make([]section, 0, len(order)) for _, key := range order { result = append(result, *bySection[key]) @@ -160,12 +151,28 @@ func buildSections(opts serpent.OptionSet) []section { return result } +// sectionRank fixes the display order of sections. General comes first because +// it holds the most common first-time setup options (Postgres, cache +// directory, access URL). The Dangerous group comes last, regardless of its +// emoji prefix, so the reference does not steer operators toward risky +// settings. Every other section sorts alphabetically between them. +func sectionRank(title string) int { + switch { + case title == "General": + return -1 + case strings.HasSuffix(title, "Dangerous"): + return 1 + default: + return 0 + } +} + func optionToRow(opt serpent.Option) row { flagCell := "-" if opt.Flag != "" { - // Link to the heading anchor that clidocgen emits in server.md. Flags - // with a shorthand render as "### -s, --flag" (anchor "-s---flag"); - // flags without one render as "### --flag" (anchor "--flag"). + // clidocgen renders a flag heading as "### -s, --flag" when it has a + // shorthand and "### --flag" otherwise, so the anchor must include the + // shorthand to match. anchor := "--" + opt.Flag if opt.FlagShorthand != "" { anchor = "-" + opt.FlagShorthand + "---" + opt.Flag @@ -175,14 +182,14 @@ func optionToRow(opt serpent.Option) row { def := opt.Default if def == "" && opt.DefaultFn != nil { - // DefaultFn results depend on the host environment, so we cannot - // safely evaluate them here. Mark them as dynamic so readers know to - // check the CLI reference for the resolved default. - def = "(dynamic)" + // DefaultFn results depend on the host environment, so evaluating them + // here would leak host-specific values. Send the reader to the CLI + // reference for the resolved default instead. + def = "(computed at runtime)" } return row{ - name: opt.Name, + name: escapePipe(opt.Name), env: codeCell(opt.Env), flag: flagCell, yaml: codeCell(opt.YAMLPath()), @@ -191,8 +198,6 @@ func optionToRow(opt serpent.Option) row { } } -// codeCell wraps s in backticks for a markdown table cell, or returns a dash -// placeholder when s is empty. func codeCell(s string) string { if s == "" { return "-" @@ -200,9 +205,8 @@ func codeCell(s string) string { return "`" + s + "`" } -// sanitizeDesc collapses whitespace and escapes pipes so the description fits -// inside a markdown table cell. Long sentences are kept; readers can follow -// the flag link for canonical wording. +// sanitizeDesc collapses whitespace and escapes pipes so a description renders +// inside a single markdown table cell. func sanitizeDesc(s string) string { s = strings.TrimSpace(s) s = strings.ReplaceAll(s, "\n", " ") @@ -210,13 +214,19 @@ func sanitizeDesc(s string) string { for strings.Contains(s, " ") { s = strings.ReplaceAll(s, " ", " ") } - s = strings.ReplaceAll(s, "|", `\|`) + s = escapePipe(s) if s == "" { return "-" } return s } +// escapePipe escapes the markdown table cell delimiter so a value cannot break +// the surrounding row. +func escapePipe(s string) string { + return strings.ReplaceAll(s, "|", `\|`) +} + func renderSections(sections []section) string { var b strings.Builder for _, sec := range sections { From c1f77a2e573634655f35a9349545c158ba9fe210 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Wed, 8 Jul 2026 17:00:09 +0000 Subject: [PATCH 06/13] docs: render configuration reference as a per-setting list Replace the wide table with a nested, per-setting list so the reference fits without horizontal scrolling. Sections now nest by serpent group hierarchy (e.g. Email > Email authentication) and headings use sentence case with the redundant group prefix stripped (e.g. "AI Gateway Send Actor Headers" becomes "Send actor headers"). Deprecated options sort to the end of each section and lead with an emphasized marker, keeping heading anchors stable. --- docs/admin/setup/configuration-reference.md | 2145 ++++++++++++++++--- scripts/configdocgen/main.go | 455 +++- 2 files changed, 2143 insertions(+), 457 deletions(-) diff --git a/docs/admin/setup/configuration-reference.md b/docs/admin/setup/configuration-reference.md index d3bfbe1e030b1..76a4f052b3753 100644 --- a/docs/admin/setup/configuration-reference.md +++ b/docs/admin/setup/configuration-reference.md @@ -6,8 +6,8 @@ lists every option so you can search by environment variable name, CLI flag, or YAML key. For first-time setup guidance and worked examples, see [Configure Control Plane Access](./index.md). -Most options can be set through any of the following. Where a method does not -apply to an option, that column shows `-`. +Each option can be set through one or more of the methods below. An option lists +only the methods that apply to it. - An environment variable (recommended for production deployments running as a system service, container, or Helm chart). @@ -15,385 +15,1836 @@ apply to an option, that column shows `-`. and local development). - A key in a YAML configuration file passed with `--config`. -For a full description of each option's accepted values and behavior, follow -the flag link into [`coder server` CLI reference](../../reference/cli/server.md). +For a full description of each option's accepted values and behavior, follow the +flag link into the [`coder server` CLI reference](../../reference/cli/server.md). + +Deprecated options are listed at the end of each section. ## General -| Setting | Env var | Flag | YAML | Default | Description | -|----------------------------------------------|------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Allow Workspace Renames | `CODER_ALLOW_WORKSPACE_RENAMES` | [`--allow-workspace-renames`](../../reference/cli/server.md#--allow-workspace-renames) | `allowWorkspaceRenames` | `false` | Allow users to rename their workspaces. WARNING: Renaming a workspace can cause Terraform resources that depend on the workspace name to be destroyed and recreated, potentially causing data loss. Only enable this if your templates do not use workspace names in resource identifiers, or if you understand the risks. | -| Cache Directory | `CODER_CACHE_DIRECTORY` | [`--cache-dir`](../../reference/cli/server.md#--cache-dir) | `cacheDir` | `~/.cache/coder` | The directory to cache temporary files. If unspecified and $CACHE_DIRECTORY is set, it will be used for compatibility with systemd. This directory is NOT safe to be configured as a shared directory across coderd/provisionerd replicas. | -| Default OAuth Refresh Lifetime | `CODER_DEFAULT_OAUTH_REFRESH_LIFETIME` | [`--default-oauth-refresh-lifetime`](../../reference/cli/server.md#--default-oauth-refresh-lifetime) | `defaultOAuthRefreshLifetime` | `720h0m0s` | The default lifetime duration for OAuth2 refresh tokens. This controls how long refresh tokens remain valid after issuance or rotation. | -| Default Token Lifetime | `CODER_DEFAULT_TOKEN_LIFETIME` | [`--default-token-lifetime`](../../reference/cli/server.md#--default-token-lifetime) | `defaultTokenLifetime` | `168h0m0s` | The default lifetime duration for API tokens. This value is used when creating a token without specifying a duration, such as when authenticating the CLI or an IDE plugin. | -| Disable Chat Sharing | `CODER_DISABLE_CHAT_SHARING` | [`--disable-chat-sharing`](../../reference/cli/server.md#--disable-chat-sharing) | `disableChatSharing` | - | Disable chat sharing. Chat ACL checking is disabled and only owners can access their chats. | -| Disable Owner Workspace Access | `CODER_DISABLE_OWNER_WORKSPACE_ACCESS` | [`--disable-owner-workspace-access`](../../reference/cli/server.md#--disable-owner-workspace-access) | `disableOwnerWorkspaceAccess` | - | Remove the permission for the 'owner' role to have workspace execution on all workspaces. This prevents the 'owner' from ssh, apps, and terminal access based on the 'owner' role. They still have their user permissions to access their own workspaces. | -| Disable Path Apps | `CODER_DISABLE_PATH_APPS` | [`--disable-path-apps`](../../reference/cli/server.md#--disable-path-apps) | `disablePathApps` | - | Disable workspace apps that are not served from subdomains. Path-based apps can make requests to the Coder API and pose a security risk when the workspace serves malicious JavaScript. This is recommended for security purposes if a --wildcard-access-url is configured. | -| Disable Workspace Sharing | `CODER_DISABLE_WORKSPACE_SHARING` | [`--disable-workspace-sharing`](../../reference/cli/server.md#--disable-workspace-sharing) | `disableWorkspaceSharing` | - | Disable workspace sharing. Workspace ACL checking is disabled and only owners can have ssh, apps and terminal access to workspaces. Access based on the 'owner' role is also allowed unless disabled via --disable-owner-workspace-access. | -| Enable swagger endpoint | `CODER_SWAGGER_ENABLE` | [`--swagger-enable`](../../reference/cli/server.md#--swagger-enable) | `enableSwagger` | - | Expose the swagger endpoint via /swagger. | -| Experiments | `CODER_EXPERIMENTS` | [`--experiments`](../../reference/cli/server.md#--experiments) | `experiments` | - | Enable one or more experiments. These are not ready for production. Separate multiple experiments with commas, or enter '*' to opt-in to all available experiments. | -| External Auth GitHub Default Provider Enable | `CODER_EXTERNAL_AUTH_GITHUB_DEFAULT_PROVIDER_ENABLE` | [`--external-auth-github-default-provider-enable`](../../reference/cli/server.md#--external-auth-github-default-provider-enable) | `externalAuthGithubDefaultProviderEnable` | `true` | Enable the default GitHub external auth provider managed by Coder. | -| External Token Encryption Keys | `CODER_EXTERNAL_TOKEN_ENCRYPTION_KEYS` | [`--external-token-encryption-keys`](../../reference/cli/server.md#--external-token-encryption-keys) | - | - | Encrypt OIDC and Git authentication tokens with AES-256-GCM in the database. The value must be a comma-separated list of base64-encoded keys. Each key, when base64-decoded, must be exactly 32 bytes in length. The first key will be used to encrypt new values. Subsequent keys will be used as a fallback when decrypting. During normal operation it is recommended to only set one key unless you are in the process of rotating keys with the `coder server dbcrypt rotate` command. | -| Postgres Auth | `CODER_PG_AUTH` | [`--postgres-auth`](../../reference/cli/server.md#--postgres-auth) | `pgAuth` | `password` | Type of auth to use when connecting to postgres. For AWS RDS, using IAM authentication (awsiamrds) is recommended. | -| Postgres Connection Max Idle | `CODER_PG_CONN_MAX_IDLE` | [`--postgres-conn-max-idle`](../../reference/cli/server.md#--postgres-conn-max-idle) | `pgConnMaxIdle` | `auto` | Maximum number of idle connections to the database. Set to "auto" (the default) to use max open / 3. Value must be greater or equal to 0; 0 means explicitly no idle connections. | -| Postgres Connection Max Open | `CODER_PG_CONN_MAX_OPEN` | [`--postgres-conn-max-open`](../../reference/cli/server.md#--postgres-conn-max-open) | `pgConnMaxOpen` | `10` | Maximum number of open connections to the database. Defaults to 10. | -| Postgres Connection URL | `CODER_PG_CONNECTION_URL` | [`--postgres-url`](../../reference/cli/server.md#--postgres-url) | - | - | URL of a PostgreSQL database. 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". Note that any special characters in the URL must be URL-encoded. | -| SCIM API Key | `CODER_SCIM_AUTH_HEADER` | [`--scim-auth-header`](../../reference/cli/server.md#--scim-auth-header) | - | - | Enables SCIM and sets the authentication header for the built-in SCIM server. New users are automatically created with OIDC authentication. | -| SCIM Use Legacy | `CODER_SCIM_USE_LEGACY` | [`--scim-use-legacy`](../../reference/cli/server.md#--scim-use-legacy) | `scimUseLegacy` | `true` | Use the legacy SCIM implementation instead of the SCIM 2.0 handler. This is provided for backward compatibility for existing users. | -| SSH Keygen Algorithm | `CODER_SSH_KEYGEN_ALGORITHM` | [`--ssh-keygen-algorithm`](../../reference/cli/server.md#--ssh-keygen-algorithm) | `sshKeygenAlgorithm` | `ed25519` | The algorithm to use for generating ssh keys. Accepted values are "ed25519", "ecdsa", or "rsa4096". | -| Support Links | `CODER_SUPPORT_LINKS` | [`--support-links`](../../reference/cli/server.md#--support-links) | `supportLinks` | - | Support links to display in the top right drop down menu. | -| Terms of Service URL | `CODER_TERMS_OF_SERVICE_URL` | [`--terms-of-service-url`](../../reference/cli/server.md#--terms-of-service-url) | `termsOfServiceURL` | - | A URL to an external Terms of Service that must be accepted by users when logging in. | -| Update Check | `CODER_UPDATE_CHECK` | [`--update-check`](../../reference/cli/server.md#--update-check) | `updateCheck` | `false` | Periodically check for new releases of Coder and inform the owner. The check is performed once per day. | - -## AI Gateway - -| Setting | Env var | Flag | YAML | Default | Description | -|--------------------------------------|----------------------------------------------|------------------------------------------------------------------------------------------------------------------|---------------------------------------|----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| AI Budget Period | `CODER_AI_BUDGET_PERIOD` | [`--ai-budget-period`](../../reference/cli/server.md#--ai-budget-period) | `ai_gateway.budget_period` | `month` | Determines when accumulated AI spend resets to zero, aligned to UTC calendar boundaries. Only "month" is currently supported. | -| AI Budget Policy | `CODER_AI_BUDGET_POLICY` | [`--ai-budget-policy`](../../reference/cli/server.md#--ai-budget-policy) | `ai_gateway.budget_policy` | `highest` | Determines the effective group when a user belongs to multiple groups with AI budgets. "highest" selects the group with the largest spend limit, and is currently the only supported value. | -| AI Gateway API Dump Directory | `CODER_AI_GATEWAY_DUMP_DIR` | [`--ai-gateway-dump-dir`](../../reference/cli/server.md#--ai-gateway-dump-dir) | `ai_gateway.api_dump_dir` | - | Base directory for dumping AI Gateway request/response pairs to disk for debugging. When set, each provider writes under a subdirectory named after the provider. Sensitive headers are redacted. Leave empty to disable. | -| AI Gateway Allow BYOK | `CODER_AI_GATEWAY_ALLOW_BYOK` | [`--ai-gateway-allow-byok`](../../reference/cli/server.md#--ai-gateway-allow-byok) | `ai_gateway.allow_byok` | `true` | Allow users to provide their own LLM API keys or subscriptions. When disabled, only centralized key authentication is permitted. | -| AI Gateway Anthropic Base URL | `CODER_AI_GATEWAY_ANTHROPIC_BASE_URL` | [`--ai-gateway-anthropic-base-url`](../../reference/cli/server.md#--ai-gateway-anthropic-base-url) | `ai_gateway.anthropic_base_url` | `https://api.anthropic.com/` | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The base URL of the Anthropic API. | -| AI Gateway Anthropic Key | `CODER_AI_GATEWAY_ANTHROPIC_KEY` | [`--ai-gateway-anthropic-key`](../../reference/cli/server.md#--ai-gateway-anthropic-key) | - | - | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The key to authenticate against the Anthropic API. | -| AI Gateway Bedrock Access Key | `CODER_AI_GATEWAY_BEDROCK_ACCESS_KEY` | [`--ai-gateway-bedrock-access-key`](../../reference/cli/server.md#--ai-gateway-bedrock-access-key) | - | - | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The access key to authenticate against the AWS Bedrock API. | -| AI Gateway Bedrock Access Key Secret | `CODER_AI_GATEWAY_BEDROCK_ACCESS_KEY_SECRET` | [`--ai-gateway-bedrock-access-key-secret`](../../reference/cli/server.md#--ai-gateway-bedrock-access-key-secret) | - | - | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The access key secret to use with the access key to authenticate against the AWS Bedrock API. | -| AI Gateway Bedrock Base URL | `CODER_AI_GATEWAY_BEDROCK_BASE_URL` | [`--ai-gateway-bedrock-base-url`](../../reference/cli/server.md#--ai-gateway-bedrock-base-url) | `ai_gateway.bedrock_base_url` | - | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The base URL to use for the AWS Bedrock API. Use this setting to specify an exact URL to use. Takes precedence over CODER_AI_GATEWAY_BEDROCK_REGION. | -| AI Gateway Bedrock Model | `CODER_AI_GATEWAY_BEDROCK_MODEL` | [`--ai-gateway-bedrock-model`](../../reference/cli/server.md#--ai-gateway-bedrock-model) | `ai_gateway.bedrock_model` | `global.anthropic.claude-sonnet-4-5-20250929-v1:0` | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The model to use when making requests to the AWS Bedrock API. | -| AI Gateway Bedrock Region | `CODER_AI_GATEWAY_BEDROCK_REGION` | [`--ai-gateway-bedrock-region`](../../reference/cli/server.md#--ai-gateway-bedrock-region) | `ai_gateway.bedrock_region` | - | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The AWS Bedrock API region to use. Constructs a base URL to use for the AWS Bedrock API in the form of 'https://bedrock-runtime..amazonaws.com'. | -| AI Gateway Bedrock Small Fast Model | `CODER_AI_GATEWAY_BEDROCK_SMALL_FAST_MODEL` | [`--ai-gateway-bedrock-small-fastmodel`](../../reference/cli/server.md#--ai-gateway-bedrock-small-fastmodel) | `ai_gateway.bedrock_small_fast_model` | `global.anthropic.claude-haiku-4-5-20251001-v1:0` | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The small fast model to use when making requests to the AWS Bedrock API. Claude Code uses Haiku-class models to perform background tasks. See https://docs.claude.com/en/docs/claude-code/settings#environment-variables. | -| AI Gateway Circuit Breaker Enabled | `CODER_AI_GATEWAY_CIRCUIT_BREAKER_ENABLED` | [`--ai-gateway-circuit-breaker-enabled`](../../reference/cli/server.md#--ai-gateway-circuit-breaker-enabled) | `ai_gateway.circuit_breaker_enabled` | `false` | Enable the circuit breaker to protect against cascading failures from upstream AI provider overload (503, 529). | -| AI Gateway Data Retention Duration | `CODER_AI_GATEWAY_RETENTION` | [`--ai-gateway-retention`](../../reference/cli/server.md#--ai-gateway-retention) | `ai_gateway.retention` | `60d` | Length of time to retain data such as interceptions and all related records (token, prompt, tool use). | -| AI Gateway Enabled | `CODER_AI_GATEWAY_ENABLED` | [`--ai-gateway-enabled`](../../reference/cli/server.md#--ai-gateway-enabled) | `ai_gateway.enabled` | `true` | Whether to start an in-memory AI Gateway instance. | -| AI Gateway Max Concurrency | `CODER_AI_GATEWAY_MAX_CONCURRENCY` | [`--ai-gateway-max-concurrency`](../../reference/cli/server.md#--ai-gateway-max-concurrency) | `ai_gateway.max_concurrency` | `0` | Maximum number of concurrent AI Gateway requests per replica. Set to 0 to disable (unlimited). | -| AI Gateway OpenAI Base URL | `CODER_AI_GATEWAY_OPENAI_BASE_URL` | [`--ai-gateway-openai-base-url`](../../reference/cli/server.md#--ai-gateway-openai-base-url) | `ai_gateway.openai_base_url` | `https://api.openai.com/v1/` | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The base URL of the OpenAI API. | -| AI Gateway OpenAI Key | `CODER_AI_GATEWAY_OPENAI_KEY` | [`--ai-gateway-openai-key`](../../reference/cli/server.md#--ai-gateway-openai-key) | - | - | Deprecated: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The key to authenticate against the OpenAI API. | -| AI Gateway Rate Limit | `CODER_AI_GATEWAY_RATE_LIMIT` | [`--ai-gateway-rate-limit`](../../reference/cli/server.md#--ai-gateway-rate-limit) | `ai_gateway.rate_limit` | `0` | Maximum number of AI Gateway requests per second per replica. Set to 0 to disable (unlimited). | -| AI Gateway Send Actor Headers | `CODER_AI_GATEWAY_SEND_ACTOR_HEADERS` | [`--ai-gateway-send-actor-headers`](../../reference/cli/server.md#--ai-gateway-send-actor-headers) | `ai_gateway.send_actor_headers` | `false` | Once enabled, extra headers will be added to upstream requests to identify the user (actor) making requests to AI Gateway. This is only needed if you are using a proxy between AI Gateway and an upstream AI provider. This will send X-Ai-Bridge-Actor-Id (the ID of the user making the request) and X-Ai-Bridge-Actor-Metadata-Username (their username). | -| AI Gateway Structured Logging | `CODER_AI_GATEWAY_STRUCTURED_LOGGING` | [`--ai-gateway-structured-logging`](../../reference/cli/server.md#--ai-gateway-structured-logging) | `ai_gateway.structured_logging` | `false` | Emit structured logs for AI Gateway interception records. Use this for exporting these records to external SIEM or observability systems. | - -## AI Gateway Proxy - -| Setting | Env var | Flag | YAML | Default | Description | -|-------------------------------------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|------------------------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| AI Gateway Proxy API Dump Directory | `CODER_AI_GATEWAY_PROXY_DUMP_DIR` | [`--ai-gateway-proxy-dump-dir`](../../reference/cli/server.md#--ai-gateway-proxy-dump-dir) | `ai_gateway_proxy.api_dump_dir` | - | Directory for dumping MITM request/response pairs to disk for debugging. When set, each proxied request produces .req.txt and .resp.txt files organized by provider. Sensitive headers are redacted. Leave empty to disable. | -| AI Gateway Proxy Allowed Private CIDRs | `CODER_AI_GATEWAY_PROXY_ALLOWED_PRIVATE_CIDRS` | [`--ai-gateway-proxy-allowed-private-cidrs`](../../reference/cli/server.md#--ai-gateway-proxy-allowed-private-cidrs) | `ai_gateway_proxy.allowed_private_cidrs` | - | Comma-separated list of CIDR ranges that are permitted even though they fall within blocked private/reserved IP ranges. By default all private ranges are blocked to prevent SSRF attacks. Use this to allow access to specific internal networks. | -| AI Gateway Proxy Enabled | `CODER_AI_GATEWAY_PROXY_ENABLED` | [`--ai-gateway-proxy-enabled`](../../reference/cli/server.md#--ai-gateway-proxy-enabled) | `ai_gateway_proxy.enabled` | `false` | Enable the AI Gateway MITM Proxy for intercepting and decrypting AI provider requests. | -| AI Gateway Proxy Listen Address | `CODER_AI_GATEWAY_PROXY_LISTEN_ADDR` | [`--ai-gateway-proxy-listen-addr`](../../reference/cli/server.md#--ai-gateway-proxy-listen-addr) | `ai_gateway_proxy.listen_addr` | `:8888` | The address the AI Gateway Proxy will listen on. | -| AI Gateway Proxy MITM CA Certificate File | `CODER_AI_GATEWAY_PROXY_CERT_FILE` | [`--ai-gateway-proxy-cert-file`](../../reference/cli/server.md#--ai-gateway-proxy-cert-file) | `ai_gateway_proxy.cert_file` | - | Path to the CA certificate file used to intercept (MITM) HTTPS traffic from AI clients. This CA must be trusted by AI clients for the proxy to decrypt their requests. | -| AI Gateway Proxy MITM CA Key File | `CODER_AI_GATEWAY_PROXY_KEY_FILE` | [`--ai-gateway-proxy-key-file`](../../reference/cli/server.md#--ai-gateway-proxy-key-file) | `ai_gateway_proxy.key_file` | - | Path to the CA private key file used to intercept (MITM) HTTPS traffic from AI clients. | -| AI Gateway Proxy TLS Certificate File | `CODER_AI_GATEWAY_PROXY_TLS_CERT_FILE` | [`--ai-gateway-proxy-tls-cert-file`](../../reference/cli/server.md#--ai-gateway-proxy-tls-cert-file) | `ai_gateway_proxy.tls_cert_file` | - | Path to the TLS certificate file for the AI Gateway Proxy listener. Must be set together with AI Gateway Proxy TLS Key File. | -| AI Gateway Proxy TLS Key File | `CODER_AI_GATEWAY_PROXY_TLS_KEY_FILE` | [`--ai-gateway-proxy-tls-key-file`](../../reference/cli/server.md#--ai-gateway-proxy-tls-key-file) | `ai_gateway_proxy.tls_key_file` | - | Path to the TLS private key file for the AI Gateway Proxy listener. Must be set together with AI Gateway Proxy TLS Certificate File. | -| AI Gateway Proxy Upstream Proxy | `CODER_AI_GATEWAY_PROXY_UPSTREAM` | [`--ai-gateway-proxy-upstream`](../../reference/cli/server.md#--ai-gateway-proxy-upstream) | `ai_gateway_proxy.upstream_proxy` | - | URL of an upstream HTTP proxy to chain tunneled (non-allowlisted) requests through. Format: http://[user:pass@]host:port or https://[user:pass@]host:port. | -| AI Gateway Proxy Upstream Proxy CA | `CODER_AI_GATEWAY_PROXY_UPSTREAM_CA` | [`--ai-gateway-proxy-upstream-ca`](../../reference/cli/server.md#--ai-gateway-proxy-upstream-ca) | `ai_gateway_proxy.upstream_proxy_ca` | - | Path to a PEM-encoded CA certificate to trust for the upstream proxy's TLS connection. Only needed for HTTPS upstream proxies with certificates not trusted by the system. If not provided, the system certificate pool is used. | +### Allow workspace renames + +Allow users to rename their workspaces. WARNING: Renaming a workspace can cause Terraform resources that depend on the workspace name to be destroyed and recreated, potentially causing data loss. Only enable this if your templates do not use workspace names in resource identifiers, or if you understand the risks. + +- Environment variable: `CODER_ALLOW_WORKSPACE_RENAMES` +- CLI flag: [`--allow-workspace-renames`](../../reference/cli/server.md#--allow-workspace-renames) +- YAML key: `allowWorkspaceRenames` +- Default value: `false` + +### Cache directory + +The directory to cache temporary files. If unspecified and $CACHE_DIRECTORY is set, it will be used for compatibility with systemd. This directory is NOT safe to be configured as a shared directory across coderd/provisionerd replicas. + +- Environment variable: `CODER_CACHE_DIRECTORY` +- CLI flag: [`--cache-dir`](../../reference/cli/server.md#--cache-dir) +- YAML key: `cacheDir` +- Default value: `~/.cache/coder` + +### Default OAuth refresh lifetime + +The default lifetime duration for OAuth2 refresh tokens. This controls how long refresh tokens remain valid after issuance or rotation. + +- Environment variable: `CODER_DEFAULT_OAUTH_REFRESH_LIFETIME` +- CLI flag: [`--default-oauth-refresh-lifetime`](../../reference/cli/server.md#--default-oauth-refresh-lifetime) +- YAML key: `defaultOAuthRefreshLifetime` +- Default value: `720h0m0s` + +### Default token lifetime + +The default lifetime duration for API tokens. This value is used when creating a token without specifying a duration, such as when authenticating the CLI or an IDE plugin. + +- Environment variable: `CODER_DEFAULT_TOKEN_LIFETIME` +- CLI flag: [`--default-token-lifetime`](../../reference/cli/server.md#--default-token-lifetime) +- YAML key: `defaultTokenLifetime` +- Default value: `168h0m0s` + +### Disable chat sharing + +Disable chat sharing. Chat ACL checking is disabled and only owners can access their chats. + +- Environment variable: `CODER_DISABLE_CHAT_SHARING` +- CLI flag: [`--disable-chat-sharing`](../../reference/cli/server.md#--disable-chat-sharing) +- YAML key: `disableChatSharing` + +### Disable owner workspace access + +Remove the permission for the 'owner' role to have workspace execution on all workspaces. This prevents the 'owner' from ssh, apps, and terminal access based on the 'owner' role. They still have their user permissions to access their own workspaces. + +- Environment variable: `CODER_DISABLE_OWNER_WORKSPACE_ACCESS` +- CLI flag: [`--disable-owner-workspace-access`](../../reference/cli/server.md#--disable-owner-workspace-access) +- YAML key: `disableOwnerWorkspaceAccess` + +### Disable path apps + +Disable workspace apps that are not served from subdomains. Path-based apps can make requests to the Coder API and pose a security risk when the workspace serves malicious JavaScript. This is recommended for security purposes if a --wildcard-access-url is configured. + +- Environment variable: `CODER_DISABLE_PATH_APPS` +- CLI flag: [`--disable-path-apps`](../../reference/cli/server.md#--disable-path-apps) +- YAML key: `disablePathApps` + +### Disable workspace sharing + +Disable workspace sharing. Workspace ACL checking is disabled and only owners can have ssh, apps and terminal access to workspaces. Access based on the 'owner' role is also allowed unless disabled via --disable-owner-workspace-access. + +- Environment variable: `CODER_DISABLE_WORKSPACE_SHARING` +- CLI flag: [`--disable-workspace-sharing`](../../reference/cli/server.md#--disable-workspace-sharing) +- YAML key: `disableWorkspaceSharing` + +### Enable swagger endpoint + +Expose the swagger endpoint via /swagger. + +- Environment variable: `CODER_SWAGGER_ENABLE` +- CLI flag: [`--swagger-enable`](../../reference/cli/server.md#--swagger-enable) +- YAML key: `enableSwagger` + +### Experiments + +Enable one or more experiments. These are not ready for production. Separate multiple experiments with commas, or enter '*' to opt-in to all available experiments. + +- Environment variable: `CODER_EXPERIMENTS` +- CLI flag: [`--experiments`](../../reference/cli/server.md#--experiments) +- YAML key: `experiments` + +### External auth GitHub default provider enable + +Enable the default GitHub external auth provider managed by Coder. + +- Environment variable: `CODER_EXTERNAL_AUTH_GITHUB_DEFAULT_PROVIDER_ENABLE` +- CLI flag: [`--external-auth-github-default-provider-enable`](../../reference/cli/server.md#--external-auth-github-default-provider-enable) +- YAML key: `externalAuthGithubDefaultProviderEnable` +- Default value: `true` + +### External token encryption keys + +Encrypt OIDC and Git authentication tokens with AES-256-GCM in the database. The value must be a comma-separated list of base64-encoded keys. Each key, when base64-decoded, must be exactly 32 bytes in length. The first key will be used to encrypt new values. Subsequent keys will be used as a fallback when decrypting. During normal operation it is recommended to only set one key unless you are in the process of rotating keys with the `coder server dbcrypt rotate` command. + +- Environment variable: `CODER_EXTERNAL_TOKEN_ENCRYPTION_KEYS` +- CLI flag: [`--external-token-encryption-keys`](../../reference/cli/server.md#--external-token-encryption-keys) + +### Postgres auth + +Type of auth to use when connecting to postgres. For AWS RDS, using IAM authentication (awsiamrds) is recommended. + +- Environment variable: `CODER_PG_AUTH` +- CLI flag: [`--postgres-auth`](../../reference/cli/server.md#--postgres-auth) +- YAML key: `pgAuth` +- Default value: `password` + +### Postgres connection max idle + +Maximum number of idle connections to the database. Set to "auto" (the default) to use max open / 3. Value must be greater or equal to 0; 0 means explicitly no idle connections. + +- Environment variable: `CODER_PG_CONN_MAX_IDLE` +- CLI flag: [`--postgres-conn-max-idle`](../../reference/cli/server.md#--postgres-conn-max-idle) +- YAML key: `pgConnMaxIdle` +- Default value: `auto` + +### Postgres connection max open + +Maximum number of open connections to the database. Defaults to 10. + +- Environment variable: `CODER_PG_CONN_MAX_OPEN` +- CLI flag: [`--postgres-conn-max-open`](../../reference/cli/server.md#--postgres-conn-max-open) +- YAML key: `pgConnMaxOpen` +- Default value: `10` + +### Postgres connection URL + +URL of a PostgreSQL database. 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". Note that any special characters in the URL must be URL-encoded. + +- Environment variable: `CODER_PG_CONNECTION_URL` +- CLI flag: [`--postgres-url`](../../reference/cli/server.md#--postgres-url) + +### SCIM API key + +Enables SCIM and sets the authentication header for the built-in SCIM server. New users are automatically created with OIDC authentication. + +- Environment variable: `CODER_SCIM_AUTH_HEADER` +- CLI flag: [`--scim-auth-header`](../../reference/cli/server.md#--scim-auth-header) + +### SCIM use legacy + +Use the legacy SCIM implementation instead of the SCIM 2.0 handler. This is provided for backward compatibility for existing users. + +- Environment variable: `CODER_SCIM_USE_LEGACY` +- CLI flag: [`--scim-use-legacy`](../../reference/cli/server.md#--scim-use-legacy) +- YAML key: `scimUseLegacy` +- Default value: `true` + +### SSH keygen algorithm + +The algorithm to use for generating ssh keys. Accepted values are "ed25519", "ecdsa", or "rsa4096". + +- Environment variable: `CODER_SSH_KEYGEN_ALGORITHM` +- CLI flag: [`--ssh-keygen-algorithm`](../../reference/cli/server.md#--ssh-keygen-algorithm) +- YAML key: `sshKeygenAlgorithm` +- Default value: `ed25519` + +### Support links + +Support links to display in the top right drop down menu. + +- Environment variable: `CODER_SUPPORT_LINKS` +- CLI flag: [`--support-links`](../../reference/cli/server.md#--support-links) +- YAML key: `supportLinks` + +### Terms of service URL + +A URL to an external Terms of Service that must be accepted by users when logging in. + +- Environment variable: `CODER_TERMS_OF_SERVICE_URL` +- CLI flag: [`--terms-of-service-url`](../../reference/cli/server.md#--terms-of-service-url) +- YAML key: `termsOfServiceURL` + +### Update check + +Periodically check for new releases of Coder and inform the owner. The check is performed once per day. + +- Environment variable: `CODER_UPDATE_CHECK` +- CLI flag: [`--update-check`](../../reference/cli/server.md#--update-check) +- YAML key: `updateCheck` +- Default value: `false` + +## AI gateway + +### AI budget period + +Determines when accumulated AI spend resets to zero, aligned to UTC calendar boundaries. Only "month" is currently supported. + +- Environment variable: `CODER_AI_BUDGET_PERIOD` +- CLI flag: [`--ai-budget-period`](../../reference/cli/server.md#--ai-budget-period) +- YAML key: `ai_gateway.budget_period` +- Default value: `month` + +### AI budget policy + +Determines the effective group when a user belongs to multiple groups with AI budgets. "highest" selects the group with the largest spend limit, and is currently the only supported value. + +- Environment variable: `CODER_AI_BUDGET_POLICY` +- CLI flag: [`--ai-budget-policy`](../../reference/cli/server.md#--ai-budget-policy) +- YAML key: `ai_gateway.budget_policy` +- Default value: `highest` + +### API dump directory + +Base directory for dumping AI Gateway request/response pairs to disk for debugging. When set, each provider writes under a subdirectory named after the provider. Sensitive headers are redacted. Leave empty to disable. + +- Environment variable: `CODER_AI_GATEWAY_DUMP_DIR` +- CLI flag: [`--ai-gateway-dump-dir`](../../reference/cli/server.md#--ai-gateway-dump-dir) +- YAML key: `ai_gateway.api_dump_dir` + +### Allow BYOK + +Allow users to provide their own LLM API keys or subscriptions. When disabled, only centralized key authentication is permitted. + +- Environment variable: `CODER_AI_GATEWAY_ALLOW_BYOK` +- CLI flag: [`--ai-gateway-allow-byok`](../../reference/cli/server.md#--ai-gateway-allow-byok) +- YAML key: `ai_gateway.allow_byok` +- Default value: `true` + +### Circuit breaker enabled + +Enable the circuit breaker to protect against cascading failures from upstream AI provider overload (503, 529). + +- Environment variable: `CODER_AI_GATEWAY_CIRCUIT_BREAKER_ENABLED` +- CLI flag: [`--ai-gateway-circuit-breaker-enabled`](../../reference/cli/server.md#--ai-gateway-circuit-breaker-enabled) +- YAML key: `ai_gateway.circuit_breaker_enabled` +- Default value: `false` + +### Data retention duration + +Length of time to retain data such as interceptions and all related records (token, prompt, tool use). + +- Environment variable: `CODER_AI_GATEWAY_RETENTION` +- CLI flag: [`--ai-gateway-retention`](../../reference/cli/server.md#--ai-gateway-retention) +- YAML key: `ai_gateway.retention` +- Default value: `60d` + +### Enabled + +Whether to start an in-memory AI Gateway instance. + +- Environment variable: `CODER_AI_GATEWAY_ENABLED` +- CLI flag: [`--ai-gateway-enabled`](../../reference/cli/server.md#--ai-gateway-enabled) +- YAML key: `ai_gateway.enabled` +- Default value: `true` + +### Max concurrency + +Maximum number of concurrent AI Gateway requests per replica. Set to 0 to disable (unlimited). + +- Environment variable: `CODER_AI_GATEWAY_MAX_CONCURRENCY` +- CLI flag: [`--ai-gateway-max-concurrency`](../../reference/cli/server.md#--ai-gateway-max-concurrency) +- YAML key: `ai_gateway.max_concurrency` +- Default value: `0` + +### Rate limit + +Maximum number of AI Gateway requests per second per replica. Set to 0 to disable (unlimited). + +- Environment variable: `CODER_AI_GATEWAY_RATE_LIMIT` +- CLI flag: [`--ai-gateway-rate-limit`](../../reference/cli/server.md#--ai-gateway-rate-limit) +- YAML key: `ai_gateway.rate_limit` +- Default value: `0` + +### Send actor headers + +Once enabled, extra headers will be added to upstream requests to identify the user (actor) making requests to AI Gateway. This is only needed if you are using a proxy between AI Gateway and an upstream AI provider. This will send X-Ai-Bridge-Actor-Id (the ID of the user making the request) and X-Ai-Bridge-Actor-Metadata-Username (their username). + +- Environment variable: `CODER_AI_GATEWAY_SEND_ACTOR_HEADERS` +- CLI flag: [`--ai-gateway-send-actor-headers`](../../reference/cli/server.md#--ai-gateway-send-actor-headers) +- YAML key: `ai_gateway.send_actor_headers` +- Default value: `false` + +### Structured logging + +Emit structured logs for AI Gateway interception records. Use this for exporting these records to external SIEM or observability systems. + +- Environment variable: `CODER_AI_GATEWAY_STRUCTURED_LOGGING` +- CLI flag: [`--ai-gateway-structured-logging`](../../reference/cli/server.md#--ai-gateway-structured-logging) +- YAML key: `ai_gateway.structured_logging` +- Default value: `false` + +### Anthropic base URL + +**Deprecated**: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The base URL of the Anthropic API. + +- Environment variable: `CODER_AI_GATEWAY_ANTHROPIC_BASE_URL` +- CLI flag: [`--ai-gateway-anthropic-base-url`](../../reference/cli/server.md#--ai-gateway-anthropic-base-url) +- YAML key: `ai_gateway.anthropic_base_url` +- Default value: `https://api.anthropic.com/` + +### Anthropic key + +**Deprecated**: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The key to authenticate against the Anthropic API. + +- Environment variable: `CODER_AI_GATEWAY_ANTHROPIC_KEY` +- CLI flag: [`--ai-gateway-anthropic-key`](../../reference/cli/server.md#--ai-gateway-anthropic-key) + +### Bedrock access key + +**Deprecated**: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The access key to authenticate against the AWS Bedrock API. + +- Environment variable: `CODER_AI_GATEWAY_BEDROCK_ACCESS_KEY` +- CLI flag: [`--ai-gateway-bedrock-access-key`](../../reference/cli/server.md#--ai-gateway-bedrock-access-key) + +### Bedrock access key secret + +**Deprecated**: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The access key secret to use with the access key to authenticate against the AWS Bedrock API. + +- Environment variable: `CODER_AI_GATEWAY_BEDROCK_ACCESS_KEY_SECRET` +- CLI flag: [`--ai-gateway-bedrock-access-key-secret`](../../reference/cli/server.md#--ai-gateway-bedrock-access-key-secret) + +### Bedrock base URL + +**Deprecated**: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The base URL to use for the AWS Bedrock API. Use this setting to specify an exact URL to use. Takes precedence over CODER_AI_GATEWAY_BEDROCK_REGION. + +- Environment variable: `CODER_AI_GATEWAY_BEDROCK_BASE_URL` +- CLI flag: [`--ai-gateway-bedrock-base-url`](../../reference/cli/server.md#--ai-gateway-bedrock-base-url) +- YAML key: `ai_gateway.bedrock_base_url` + +### Bedrock model + +**Deprecated**: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The model to use when making requests to the AWS Bedrock API. + +- Environment variable: `CODER_AI_GATEWAY_BEDROCK_MODEL` +- CLI flag: [`--ai-gateway-bedrock-model`](../../reference/cli/server.md#--ai-gateway-bedrock-model) +- YAML key: `ai_gateway.bedrock_model` +- Default value: `global.anthropic.claude-sonnet-4-5-20250929-v1:0` + +### Bedrock region + +**Deprecated**: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The AWS Bedrock API region to use. Constructs a base URL to use for the AWS Bedrock API in the form of 'https://bedrock-runtime..amazonaws.com'. + +- Environment variable: `CODER_AI_GATEWAY_BEDROCK_REGION` +- CLI flag: [`--ai-gateway-bedrock-region`](../../reference/cli/server.md#--ai-gateway-bedrock-region) +- YAML key: `ai_gateway.bedrock_region` + +### Bedrock small fast model + +**Deprecated**: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The small fast model to use when making requests to the AWS Bedrock API. Claude Code uses Haiku-class models to perform background tasks. See https://docs.claude.com/en/docs/claude-code/settings#environment-variables. + +- Environment variable: `CODER_AI_GATEWAY_BEDROCK_SMALL_FAST_MODEL` +- CLI flag: [`--ai-gateway-bedrock-small-fastmodel`](../../reference/cli/server.md#--ai-gateway-bedrock-small-fastmodel) +- YAML key: `ai_gateway.bedrock_small_fast_model` +- Default value: `global.anthropic.claude-haiku-4-5-20251001-v1:0` + +### OpenAI base URL + +**Deprecated**: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The base URL of the OpenAI API. + +- Environment variable: `CODER_AI_GATEWAY_OPENAI_BASE_URL` +- CLI flag: [`--ai-gateway-openai-base-url`](../../reference/cli/server.md#--ai-gateway-openai-base-url) +- YAML key: `ai_gateway.openai_base_url` +- Default value: `https://api.openai.com/v1/` + +### OpenAI key + +**Deprecated**: manage AI Providers from the Coder UI or HTTP API. If set, this option seeds provider configuration at startup only exactly once. It will not be used in service runtime. The key to authenticate against the OpenAI API. + +- Environment variable: `CODER_AI_GATEWAY_OPENAI_KEY` +- CLI flag: [`--ai-gateway-openai-key`](../../reference/cli/server.md#--ai-gateway-openai-key) + +## AI gateway proxy + +### API dump directory + +Directory for dumping MITM request/response pairs to disk for debugging. When set, each proxied request produces .req.txt and .resp.txt files organized by provider. Sensitive headers are redacted. Leave empty to disable. + +- Environment variable: `CODER_AI_GATEWAY_PROXY_DUMP_DIR` +- CLI flag: [`--ai-gateway-proxy-dump-dir`](../../reference/cli/server.md#--ai-gateway-proxy-dump-dir) +- YAML key: `ai_gateway_proxy.api_dump_dir` + +### Allowed private CIDRs + +Comma-separated list of CIDR ranges that are permitted even though they fall within blocked private/reserved IP ranges. By default all private ranges are blocked to prevent SSRF attacks. Use this to allow access to specific internal networks. + +- Environment variable: `CODER_AI_GATEWAY_PROXY_ALLOWED_PRIVATE_CIDRS` +- CLI flag: [`--ai-gateway-proxy-allowed-private-cidrs`](../../reference/cli/server.md#--ai-gateway-proxy-allowed-private-cidrs) +- YAML key: `ai_gateway_proxy.allowed_private_cidrs` + +### Enabled + +Enable the AI Gateway MITM Proxy for intercepting and decrypting AI provider requests. + +- Environment variable: `CODER_AI_GATEWAY_PROXY_ENABLED` +- CLI flag: [`--ai-gateway-proxy-enabled`](../../reference/cli/server.md#--ai-gateway-proxy-enabled) +- YAML key: `ai_gateway_proxy.enabled` +- Default value: `false` + +### Listen address + +The address the AI Gateway Proxy will listen on. + +- Environment variable: `CODER_AI_GATEWAY_PROXY_LISTEN_ADDR` +- CLI flag: [`--ai-gateway-proxy-listen-addr`](../../reference/cli/server.md#--ai-gateway-proxy-listen-addr) +- YAML key: `ai_gateway_proxy.listen_addr` +- Default value: `:8888` + +### MITM CA certificate file + +Path to the CA certificate file used to intercept (MITM) HTTPS traffic from AI clients. This CA must be trusted by AI clients for the proxy to decrypt their requests. + +- Environment variable: `CODER_AI_GATEWAY_PROXY_CERT_FILE` +- CLI flag: [`--ai-gateway-proxy-cert-file`](../../reference/cli/server.md#--ai-gateway-proxy-cert-file) +- YAML key: `ai_gateway_proxy.cert_file` + +### MITM CA key file + +Path to the CA private key file used to intercept (MITM) HTTPS traffic from AI clients. + +- Environment variable: `CODER_AI_GATEWAY_PROXY_KEY_FILE` +- CLI flag: [`--ai-gateway-proxy-key-file`](../../reference/cli/server.md#--ai-gateway-proxy-key-file) +- YAML key: `ai_gateway_proxy.key_file` + +### TLS certificate file + +Path to the TLS certificate file for the AI Gateway Proxy listener. Must be set together with AI Gateway Proxy TLS Key File. + +- Environment variable: `CODER_AI_GATEWAY_PROXY_TLS_CERT_FILE` +- CLI flag: [`--ai-gateway-proxy-tls-cert-file`](../../reference/cli/server.md#--ai-gateway-proxy-tls-cert-file) +- YAML key: `ai_gateway_proxy.tls_cert_file` + +### TLS key file + +Path to the TLS private key file for the AI Gateway Proxy listener. Must be set together with AI Gateway Proxy TLS Certificate File. + +- Environment variable: `CODER_AI_GATEWAY_PROXY_TLS_KEY_FILE` +- CLI flag: [`--ai-gateway-proxy-tls-key-file`](../../reference/cli/server.md#--ai-gateway-proxy-tls-key-file) +- YAML key: `ai_gateway_proxy.tls_key_file` + +### Upstream proxy + +URL of an upstream HTTP proxy to chain tunneled (non-allowlisted) requests through. Format: http://[user:pass@]host:port or https://[user:pass@]host:port. + +- Environment variable: `CODER_AI_GATEWAY_PROXY_UPSTREAM` +- CLI flag: [`--ai-gateway-proxy-upstream`](../../reference/cli/server.md#--ai-gateway-proxy-upstream) +- YAML key: `ai_gateway_proxy.upstream_proxy` + +### Upstream proxy CA + +Path to a PEM-encoded CA certificate to trust for the upstream proxy's TLS connection. Only needed for HTTPS upstream proxies with certificates not trusted by the system. If not provided, the system certificate pool is used. + +- Environment variable: `CODER_AI_GATEWAY_PROXY_UPSTREAM_CA` +- CLI flag: [`--ai-gateway-proxy-upstream-ca`](../../reference/cli/server.md#--ai-gateway-proxy-upstream-ca) +- YAML key: `ai_gateway_proxy.upstream_proxy_ca` + +## Chat + +Configure the background chat processing daemon. + +### Debug logging enabled + +Force chat debug logging on for every chat, bypassing the runtime admin and user opt-in settings. + +- Environment variable: `CODER_CHAT_DEBUG_LOGGING_ENABLED` +- CLI flag: [`--chat-debug-logging-enabled`](../../reference/cli/server.md#--chat-debug-logging-enabled) +- YAML key: `chat.debugLoggingEnabled` +- Default value: `false` + +## Client + +These options change the behavior of how clients interact with the Coder. Clients include the Coder CLI, Coder Desktop, IDE extensions, and the web UI. + +### CLI upgrade message + +The upgrade message to display to users when a client/server mismatch is detected. By default it instructs users to update using 'curl -L https://coder.com/install.sh | sh'. + +- Environment variable: `CODER_CLI_UPGRADE_MESSAGE` +- CLI flag: [`--cli-upgrade-message`](../../reference/cli/server.md#--cli-upgrade-message) +- YAML key: `client.cliUpgradeMessage` + +### Hide AI tasks + +Hide AI tasks from the dashboard. + +- Environment variable: `CODER_HIDE_AI_TASKS` +- CLI flag: [`--hide-ai-tasks`](../../reference/cli/server.md#--hide-ai-tasks) +- YAML key: `client.hideAITasks` +- Default value: `false` + +### SSH config options + +These SSH config options will override the default SSH config options. Provide options in "key=value" or "key value" format separated by commas. Using this incorrectly can break SSH to your deployment, use cautiously. The following options are not allowed: Host, Match, Include, ProxyCommand, ProxyJump, LocalCommand, PermitLocalCommand, RemoteCommand, KnownHostsCommand, PKCS11Provider, SecurityKeyProvider, SmartcardDevice, XAuthLocation. Option values must not contain newline, carriage return, or NUL characters. + +- Environment variable: `CODER_SSH_CONFIG_OPTIONS` +- CLI flag: [`--ssh-config-options`](../../reference/cli/server.md#--ssh-config-options) +- YAML key: `client.sshConfigOptions` + +### Web terminal renderer + +The renderer to use when opening a web terminal. Valid values are 'canvas', 'webgl', or 'dom'. + +- Environment variable: `CODER_WEB_TERMINAL_RENDERER` +- CLI flag: [`--web-terminal-renderer`](../../reference/cli/server.md#--web-terminal-renderer) +- YAML key: `client.webTerminalRenderer` +- Default value: `canvas` + +### Workspace hostname suffix + +Workspace hostnames use this suffix in SSH config and Coder Connect on Coder Desktop. By default it is coder, resulting in names like myworkspace.coder. The suffix must not start with a dot, and must not contain spaces, newlines, or glob characters (* and ?). + +- Environment variable: `CODER_WORKSPACE_HOSTNAME_SUFFIX` +- CLI flag: [`--workspace-hostname-suffix`](../../reference/cli/server.md#--workspace-hostname-suffix) +- YAML key: `client.workspaceHostnameSuffix` +- Default value: `coder` + +## Config + +Use a YAML configuration file when your server launch become unwieldy. + +### Path + +Specify a YAML file to load configuration from. + +- Environment variable: `CODER_CONFIG_PATH` +- CLI flag: [`--config`](../../reference/cli/server.md#-c---config) + +### Write config + +Write out the current server config as YAML to stdout. + +- CLI flag: [`--write-config`](../../reference/cli/server.md#--write-config) + +## Email + +Configure how emails are sent. + +### Force TLS + +Force a TLS connection to the configured SMTP smarthost. + +- Environment variable: `CODER_EMAIL_FORCE_TLS` +- CLI flag: [`--email-force-tls`](../../reference/cli/server.md#--email-force-tls) +- YAML key: `email.forceTLS` +- Default value: `false` + +### From address + +The sender's address to use. + +- Environment variable: `CODER_EMAIL_FROM` +- CLI flag: [`--email-from`](../../reference/cli/server.md#--email-from) +- YAML key: `email.from` + +### Hello + +The hostname identifying the SMTP server. + +- Environment variable: `CODER_EMAIL_HELLO` +- CLI flag: [`--email-hello`](../../reference/cli/server.md#--email-hello) +- YAML key: `email.hello` +- Default value: `localhost` + +### Smarthost + +The intermediary SMTP host through which emails are sent. + +- Environment variable: `CODER_EMAIL_SMARTHOST` +- CLI flag: [`--email-smarthost`](../../reference/cli/server.md#--email-smarthost) +- YAML key: `email.smarthost` + +### Email authentication + +Configure SMTP authentication options. + +#### Identity + +Identity to use with PLAIN authentication. + +- Environment variable: `CODER_EMAIL_AUTH_IDENTITY` +- CLI flag: [`--email-auth-identity`](../../reference/cli/server.md#--email-auth-identity) +- YAML key: `email.emailAuth.identity` + +#### Password + +Password to use with PLAIN/LOGIN authentication. + +- Environment variable: `CODER_EMAIL_AUTH_PASSWORD` +- CLI flag: [`--email-auth-password`](../../reference/cli/server.md#--email-auth-password) + +#### Password file + +File from which to load password for use with PLAIN/LOGIN authentication. + +- Environment variable: `CODER_EMAIL_AUTH_PASSWORD_FILE` +- CLI flag: [`--email-auth-password-file`](../../reference/cli/server.md#--email-auth-password-file) +- YAML key: `email.emailAuth.passwordFile` + +#### Username + +Username to use with PLAIN/LOGIN authentication. + +- Environment variable: `CODER_EMAIL_AUTH_USERNAME` +- CLI flag: [`--email-auth-username`](../../reference/cli/server.md#--email-auth-username) +- YAML key: `email.emailAuth.username` + +### Email TLS + +Configure TLS for your SMTP server target. + +#### Certificate authority file + +CA certificate file to use. + +- Environment variable: `CODER_EMAIL_TLS_CACERTFILE` +- CLI flag: [`--email-tls-ca-cert-file`](../../reference/cli/server.md#--email-tls-ca-cert-file) +- YAML key: `email.emailTLS.caCertFile` + +#### Certificate file + +Certificate file to use. + +- Environment variable: `CODER_EMAIL_TLS_CERTFILE` +- CLI flag: [`--email-tls-cert-file`](../../reference/cli/server.md#--email-tls-cert-file) +- YAML key: `email.emailTLS.certFile` + +#### Certificate key file + +Certificate key file to use. + +- Environment variable: `CODER_EMAIL_TLS_CERTKEYFILE` +- CLI flag: [`--email-tls-cert-key-file`](../../reference/cli/server.md#--email-tls-cert-key-file) +- YAML key: `email.emailTLS.certKeyFile` + +#### Server name + +Server name to verify against the target certificate. + +- Environment variable: `CODER_EMAIL_TLS_SERVERNAME` +- CLI flag: [`--email-tls-server-name`](../../reference/cli/server.md#--email-tls-server-name) +- YAML key: `email.emailTLS.serverName` + +#### Skip certificate verification (insecure) + +Skip verification of the target server's certificate (insecure). + +- Environment variable: `CODER_EMAIL_TLS_SKIPVERIFY` +- CLI flag: [`--email-tls-skip-verify`](../../reference/cli/server.md#--email-tls-skip-verify) +- YAML key: `email.emailTLS.insecureSkipVerify` + +#### StartTLS + +Enable STARTTLS to upgrade insecure SMTP connections using TLS. + +- Environment variable: `CODER_EMAIL_TLS_STARTTLS` +- CLI flag: [`--email-tls-starttls`](../../reference/cli/server.md#--email-tls-starttls) +- YAML key: `email.emailTLS.startTLS` + +## Introspection + +Configure logging, tracing, stat collection, and metrics exporting. + +### Health check + +#### Refresh + +Refresh interval for healthchecks. + +- Environment variable: `CODER_HEALTH_CHECK_REFRESH` +- CLI flag: [`--health-check-refresh`](../../reference/cli/server.md#--health-check-refresh) +- YAML key: `introspection.healthcheck.refresh` +- Default value: `10m0s` + +#### Threshold: database + +The threshold for the database health check. If the median latency of the database exceeds this threshold over 5 attempts, the database is considered unhealthy. The default value is 15ms. + +- Environment variable: `CODER_HEALTH_CHECK_THRESHOLD_DATABASE` +- CLI flag: [`--health-check-threshold-database`](../../reference/cli/server.md#--health-check-threshold-database) +- YAML key: `introspection.healthcheck.thresholdDatabase` +- Default value: `15ms` + +### Logging + +#### Enable Terraform debug mode + +Allow administrators to enable Terraform debug output. + +- Environment variable: `CODER_ENABLE_TERRAFORM_DEBUG_MODE` +- CLI flag: [`--enable-terraform-debug-mode`](../../reference/cli/server.md#--enable-terraform-debug-mode) +- YAML key: `introspection.logging.enableTerraformDebugMode` +- Default value: `false` + +#### Human log location + +Output human-readable logs to a given file. + +- Environment variable: `CODER_LOGGING_HUMAN` +- CLI flag: [`--log-human`](../../reference/cli/server.md#--log-human) +- YAML key: `introspection.logging.humanPath` +- Default value: `/dev/stderr` + +#### JSON log location + +Output JSON logs to a given file. + +- Environment variable: `CODER_LOGGING_JSON` +- CLI flag: [`--log-json`](../../reference/cli/server.md#--log-json) +- YAML key: `introspection.logging.jsonPath` + +#### Log filter + +Filter debug logs by matching against a given regex. Use .* to match all debug logs. + +- Environment variable: `CODER_LOG_FILTER` +- CLI flag: [`--log-filter`](../../reference/cli/server.md#-l---log-filter) +- YAML key: `introspection.logging.filter` + +#### Stackdriver log location + +Output Stackdriver compatible logs to a given file. + +- Environment variable: `CODER_LOGGING_STACKDRIVER` +- CLI flag: [`--log-stackdriver`](../../reference/cli/server.md#--log-stackdriver) +- YAML key: `introspection.logging.stackdriverPath` + +### Prometheus + +#### Address + +The bind address to serve prometheus metrics. + +- Environment variable: `CODER_PROMETHEUS_ADDRESS` +- CLI flag: [`--prometheus-address`](../../reference/cli/server.md#--prometheus-address) +- YAML key: `introspection.prometheus.address` +- Default value: `127.0.0.1:2112` + +#### Aggregate agent stats by + +When collecting agent stats, aggregate metrics by a given set of comma-separated labels to reduce cardinality. Accepted values are agent_name, template_name, username, workspace_name. + +- Environment variable: `CODER_PROMETHEUS_AGGREGATE_AGENT_STATS_BY` +- CLI flag: [`--prometheus-aggregate-agent-stats-by`](../../reference/cli/server.md#--prometheus-aggregate-agent-stats-by) +- YAML key: `introspection.prometheus.aggregate_agent_stats_by` +- Default value: `agent_name,template_name,username,workspace_name` + +#### Collect agent stats + +Collect agent stats (may increase charges for metrics storage). + +- Environment variable: `CODER_PROMETHEUS_COLLECT_AGENT_STATS` +- CLI flag: [`--prometheus-collect-agent-stats`](../../reference/cli/server.md#--prometheus-collect-agent-stats) +- YAML key: `introspection.prometheus.collect_agent_stats` + +#### Collect database metrics + +Collect database query metrics (may increase charges for metrics storage). If set to false, a reduced set of database metrics are still collected. + +- Environment variable: `CODER_PROMETHEUS_COLLECT_DB_METRICS` +- CLI flag: [`--prometheus-collect-db-metrics`](../../reference/cli/server.md#--prometheus-collect-db-metrics) +- YAML key: `introspection.prometheus.collect_db_metrics` +- Default value: `false` + +#### Enable + +Serve prometheus metrics on the address defined by prometheus address. + +- Environment variable: `CODER_PROMETHEUS_ENABLE` +- CLI flag: [`--prometheus-enable`](../../reference/cli/server.md#--prometheus-enable) +- YAML key: `introspection.prometheus.enable` + +### Stats collection + +#### Usage stats + +##### Enable + +Enable the collection of application and workspace usage along with the associated API endpoints and the template insights page. Disabling this will also disable traffic and connection insights in the deployment stats shown to admins in the bottom bar of the Coder UI, and will prevent Prometheus collection of these values. + +- Environment variable: `CODER_STATS_COLLECTION_USAGE_STATS_ENABLE` +- CLI flag: [`--stats-collection-usage-stats-enable`](../../reference/cli/server.md#--stats-collection-usage-stats-enable) +- YAML key: `introspection.statsCollection.usageStats.enable` +- Default value: `true` + +### Tracing + +#### Capture logs in traces + +Enables capturing of logs as events in traces. This is useful for debugging, but may result in a very large amount of events being sent to the tracing backend which may incur significant costs. + +- Environment variable: `CODER_TRACE_LOGS` +- CLI flag: [`--trace-logs`](../../reference/cli/server.md#--trace-logs) +- YAML key: `introspection.tracing.captureLogs` + +#### Trace enable + +Whether application tracing data is collected. It exports to a backend configured by environment variables. See: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md. + +- Environment variable: `CODER_TRACE_ENABLE` +- CLI flag: [`--trace`](../../reference/cli/server.md#--trace) +- YAML key: `introspection.tracing.enable` + +#### Trace Honeycomb API key + +Enables trace exporting to Honeycomb.io using the provided API Key. + +- Environment variable: `CODER_TRACE_HONEYCOMB_API_KEY` +- CLI flag: [`--trace-honeycomb-api-key`](../../reference/cli/server.md#--trace-honeycomb-api-key) + +### pprof + +#### Address + +The bind address to serve pprof. + +- Environment variable: `CODER_PPROF_ADDRESS` +- CLI flag: [`--pprof-address`](../../reference/cli/server.md#--pprof-address) +- YAML key: `introspection.pprof.address` +- Default value: `127.0.0.1:6060` + +#### Enable + +Serve pprof metrics on the address defined by pprof address. + +- Environment variable: `CODER_PPROF_ENABLE` +- CLI flag: [`--pprof-enable`](../../reference/cli/server.md#--pprof-enable) +- YAML key: `introspection.pprof.enable` + +## Networking + +### Access URL + +The URL that users will use to access the Coder deployment. + +- Environment variable: `CODER_ACCESS_URL` +- CLI flag: [`--access-url`](../../reference/cli/server.md#--access-url) +- YAML key: `networking.accessURL` + +### Browser only + +Whether Coder only allows connections to workspaces via the browser. + +- Environment variable: `CODER_BROWSER_ONLY` +- CLI flag: [`--browser-only`](../../reference/cli/server.md#--browser-only) +- YAML key: `networking.browserOnly` + +### Docs URL + +Specifies the custom docs URL. + +- Environment variable: `CODER_DOCS_URL` +- CLI flag: [`--docs-url`](../../reference/cli/server.md#--docs-url) +- YAML key: `networking.docsURL` +- Default value: `https://coder.com/docs` + +### Proxy trusted headers + +Headers to trust for forwarding IP addresses. e.g. Cf-Connecting-Ip, True-Client-Ip, X-Forwarded-For. + +- Environment variable: `CODER_PROXY_TRUSTED_HEADERS` +- CLI flag: [`--proxy-trusted-headers`](../../reference/cli/server.md#--proxy-trusted-headers) +- YAML key: `networking.proxyTrustedHeaders` + +### Proxy trusted origins + +Origin addresses to respect "proxy-trusted-headers" and X-Forwarded-Host for subdomain app routing. e.g. 192.168.1.0/24. + +- Environment variable: `CODER_PROXY_TRUSTED_ORIGINS` +- CLI flag: [`--proxy-trusted-origins`](../../reference/cli/server.md#--proxy-trusted-origins) +- YAML key: `networking.proxyTrustedOrigins` + +### Redirect to access URL + +Specifies whether to redirect requests that do not match the access URL host. + +- Environment variable: `CODER_REDIRECT_TO_ACCESS_URL` +- CLI flag: [`--redirect-to-access-url`](../../reference/cli/server.md#--redirect-to-access-url) +- YAML key: `networking.redirectToAccessURL` + +### SameSite auth cookie + +Controls the 'SameSite' property is set on browser session cookies. + +- Environment variable: `CODER_SAMESITE_AUTH_COOKIE` +- CLI flag: [`--samesite-auth-cookie`](../../reference/cli/server.md#--samesite-auth-cookie) +- YAML key: `networking.sameSiteAuthCookie` +- Default value: `lax` + +### Secure auth cookie + +Controls if the 'Secure' property is set on browser session cookies. + +- Environment variable: `CODER_SECURE_AUTH_COOKIE` +- CLI flag: [`--secure-auth-cookie`](../../reference/cli/server.md#--secure-auth-cookie) +- YAML key: `networking.secureAuthCookie` +- Default value: `(computed at runtime)` + +### Wildcard access URL + +Specifies the wildcard hostname to use for workspace applications in the form "*.example.com". + +- Environment variable: `CODER_WILDCARD_ACCESS_URL` +- CLI flag: [`--wildcard-access-url`](../../reference/cli/server.md#--wildcard-access-url) +- YAML key: `networking.wildcardAccessURL` + +### __Host prefix cookies + +Recommended to be enabled. Enables `__Host-` prefix for cookies to guarantee they are only set by the right domain. This change is disruptive to any workspaces built before release 2.31, requiring a workspace restart. + +- Environment variable: `CODER_HOST_PREFIX_COOKIE` +- CLI flag: [`--host-prefix-cookie`](../../reference/cli/server.md#--host-prefix-cookie) +- YAML key: `networking.hostPrefixCookie` +- Default value: `false` + +### Cluster + +Configure network clustering. Coder Servers in the primary region form a cluster by communicating directly. + +#### Host + +Hostname or (more commonly) IP to reach this replica for clustering. + +- Environment variable: `CODER_CLUSTER_HOST` +- CLI flag: [`--cluster-host`](../../reference/cli/server.md#--cluster-host) +- YAML key: `networking.cluster.clusterHost` + +### DERP + +Most Coder deployments never have to think about DERP because all connections between workspaces and users are peer-to-peer. However, when Coder cannot establish a peer to peer connection, Coder uses a distributed relay network backed by Tailscale and WireGuard. + +#### Block direct connections + +Block peer-to-peer (aka. direct) workspace connections. All workspace connections from the CLI will be proxied through Coder (or custom configured DERP servers) and will never be peer-to-peer when enabled. Workspaces may still reach out to STUN servers to get their address until they are restarted after this change has been made, but new connections will still be proxied regardless. + +- Environment variable: `CODER_BLOCK_DIRECT` +- CLI flag: [`--block-direct-connections`](../../reference/cli/server.md#--block-direct-connections) +- YAML key: `networking.derp.blockDirect` + +#### Config path + +Path to read a DERP mapping from. See: https://tailscale.com/kb/1118/custom-derp-servers/. + +- Environment variable: `CODER_DERP_CONFIG_PATH` +- CLI flag: [`--derp-config-path`](../../reference/cli/server.md#--derp-config-path) +- YAML key: `networking.derp.configPath` + +#### Config URL + +URL to fetch a DERP mapping on startup. See: https://tailscale.com/kb/1118/custom-derp-servers/. + +- Environment variable: `CODER_DERP_CONFIG_URL` +- CLI flag: [`--derp-config-url`](../../reference/cli/server.md#--derp-config-url) +- YAML key: `networking.derp.url` + +#### Force WebSockets + +Force clients and agents to always use WebSocket to connect to DERP relay servers. By default, DERP uses `Upgrade: derp`, which may cause issues with some reverse proxies. Clients may automatically fallback to WebSocket if they detect an issue with `Upgrade: derp`, but this does not work in all situations. + +- Environment variable: `CODER_DERP_FORCE_WEBSOCKETS` +- CLI flag: [`--derp-force-websockets`](../../reference/cli/server.md#--derp-force-websockets) +- YAML key: `networking.derp.forceWebSockets` + +#### Server enable + +Whether to enable or disable the embedded DERP relay server. + +- Environment variable: `CODER_DERP_SERVER_ENABLE` +- CLI flag: [`--derp-server-enable`](../../reference/cli/server.md#--derp-server-enable) +- YAML key: `networking.derp.enable` +- Default value: `true` + +#### Server region name + +Region name that for the embedded DERP server. + +- Environment variable: `CODER_DERP_SERVER_REGION_NAME` +- CLI flag: [`--derp-server-region-name`](../../reference/cli/server.md#--derp-server-region-name) +- YAML key: `networking.derp.regionName` +- Default value: `Coder Embedded Relay` + +#### Server relay URL + +An HTTP URL that is accessible by other replicas to relay DERP traffic. Required for high availability. + +- Environment variable: `CODER_DERP_SERVER_RELAY_URL` +- CLI flag: [`--derp-server-relay-url`](../../reference/cli/server.md#--derp-server-relay-url) +- YAML key: `networking.derp.relayURL` + +#### Server STUN addresses + +Addresses for STUN servers to establish P2P connections. It's recommended to have at least two STUN servers to give users the best chance of connecting P2P to workspaces. Each STUN server will get it's own DERP region, with region IDs starting at `--derp-server-region-id + 1`. Use special value 'disable' to turn off STUN completely. + +- Environment variable: `CODER_DERP_SERVER_STUN_ADDRESSES` +- CLI flag: [`--derp-server-stun-addresses`](../../reference/cli/server.md#--derp-server-stun-addresses) +- YAML key: `networking.derp.stunAddresses` +- Default value: `stun.l.google.com:19302,stun1.l.google.com:19302,stun2.l.google.com:19302,stun3.l.google.com:19302,stun4.l.google.com:19302` + +### HTTP + +#### Additional CSP policy + +Coder configures a Content Security Policy (CSP) to protect against XSS attacks. This setting allows you to add additional CSP directives, which can open the attack surface of the deployment. Format matches the CSP directive format, e.g. --additional-csp-policy="script-src https://example.com". + +- Environment variable: `CODER_ADDITIONAL_CSP_POLICY` +- CLI flag: [`--additional-csp-policy`](../../reference/cli/server.md#--additional-csp-policy) +- YAML key: `networking.http.additionalCSPPolicy` + +#### Disable password authentication + +Disable password authentication. This is recommended for security purposes in production deployments that rely on an identity provider. Any user with the owner role will be able to sign in with their password regardless of this setting to avoid potential lock out. If you are locked out of your account, you can use the `coder server create-admin` command to create a new admin user directly in the database. + +- Environment variable: `CODER_DISABLE_PASSWORD_AUTH` +- CLI flag: [`--disable-password-auth`](../../reference/cli/server.md#--disable-password-auth) +- YAML key: `networking.http.disablePasswordAuth` + +#### Disable session expiry refresh + +Disable automatic session expiry bumping due to activity. This forces all sessions to become invalid after the session expiry duration has been reached. + +- Environment variable: `CODER_DISABLE_SESSION_EXPIRY_REFRESH` +- CLI flag: [`--disable-session-expiry-refresh`](../../reference/cli/server.md#--disable-session-expiry-refresh) +- YAML key: `networking.http.disableSessionExpiryRefresh` + +#### Address + +HTTP bind address of the server. Unset to disable the HTTP endpoint. + +- Environment variable: `CODER_HTTP_ADDRESS` +- CLI flag: [`--http-address`](../../reference/cli/server.md#--http-address) +- YAML key: `networking.http.httpAddress` +- Default value: `127.0.0.1:3000` + +#### Max token lifetime + +The maximum lifetime duration users can specify when creating an API token. + +- Environment variable: `CODER_MAX_TOKEN_LIFETIME` +- CLI flag: [`--max-token-lifetime`](../../reference/cli/server.md#--max-token-lifetime) +- YAML key: `networking.http.maxTokenLifetime` +- Default value: `876600h0m0s` + +#### Maximum admin token lifetime + +The maximum lifetime duration administrators can specify when creating an API token. + +- Environment variable: `CODER_MAX_ADMIN_TOKEN_LIFETIME` +- CLI flag: [`--max-admin-token-lifetime`](../../reference/cli/server.md#--max-admin-token-lifetime) +- YAML key: `networking.http.maxAdminTokenLifetime` +- Default value: `168h0m0s` + +#### Proxy health check interval + +The interval in which coderd should be checking the status of workspace proxies. + +- Environment variable: `CODER_PROXY_HEALTH_INTERVAL` +- CLI flag: [`--proxy-health-interval`](../../reference/cli/server.md#--proxy-health-interval) +- YAML key: `networking.http.proxyHealthInterval` +- Default value: `1m0s` + +#### Session duration + +The token expiry duration for browser sessions. Sessions may last longer if they are actively making requests, but this functionality can be disabled via --disable-session-expiry-refresh. + +- Environment variable: `CODER_SESSION_DURATION` +- CLI flag: [`--session-duration`](../../reference/cli/server.md#--session-duration) +- YAML key: `networking.http.sessionDuration` +- Default value: `24h0m0s` + +### TLS + +Configure TLS / HTTPS for your Coder deployment. If you're running Coder behind a TLS-terminating reverse proxy or are accessing Coder over a secure link, you can safely ignore these settings. + +#### Strict-Transport-Security + +Controls if the 'Strict-Transport-Security' header is set on all static file responses. This header should only be set if the server is accessed via HTTPS. This value is the MaxAge in seconds of the header. -## Chat +- Environment variable: `CODER_STRICT_TRANSPORT_SECURITY` +- CLI flag: [`--strict-transport-security`](../../reference/cli/server.md#--strict-transport-security) +- YAML key: `networking.tls.strictTransportSecurity` +- Default value: `0` -| Setting | Env var | Flag | YAML | Default | Description | -|-----------------------------|------------------------------------|----------------------------------------------------------------------------------------------|----------------------------|---------|---------------------------------------------------------------------------------------------------| -| Chat: Debug Logging Enabled | `CODER_CHAT_DEBUG_LOGGING_ENABLED` | [`--chat-debug-logging-enabled`](../../reference/cli/server.md#--chat-debug-logging-enabled) | `chat.debugLoggingEnabled` | `false` | Force chat debug logging on for every chat, bypassing the runtime admin and user opt-in settings. | +#### Strict-Transport-Security options -## Client +Two optional fields can be set in the Strict-Transport-Security header; 'includeSubDomains' and 'preload'. The 'strict-transport-security' flag must be set to a non-zero value for these options to be used. -| Setting | Env var | Flag | YAML | Default | Description | -|---------------------------|-----------------------------------|--------------------------------------------------------------------------------------------|----------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| CLI Upgrade Message | `CODER_CLI_UPGRADE_MESSAGE` | [`--cli-upgrade-message`](../../reference/cli/server.md#--cli-upgrade-message) | `client.cliUpgradeMessage` | - | The upgrade message to display to users when a client/server mismatch is detected. By default it instructs users to update using 'curl -L https://coder.com/install.sh \| sh'. | -| Hide AI Tasks | `CODER_HIDE_AI_TASKS` | [`--hide-ai-tasks`](../../reference/cli/server.md#--hide-ai-tasks) | `client.hideAITasks` | `false` | Hide AI tasks from the dashboard. | -| SSH Config Options | `CODER_SSH_CONFIG_OPTIONS` | [`--ssh-config-options`](../../reference/cli/server.md#--ssh-config-options) | `client.sshConfigOptions` | - | These SSH config options will override the default SSH config options. Provide options in "key=value" or "key value" format separated by commas. Using this incorrectly can break SSH to your deployment, use cautiously. The following options are not allowed: Host, Match, Include, ProxyCommand, ProxyJump, LocalCommand, PermitLocalCommand, RemoteCommand, KnownHostsCommand, PKCS11Provider, SecurityKeyProvider, SmartcardDevice, XAuthLocation. Option values must not contain newline, carriage return, or NUL characters. | -| Web Terminal Renderer | `CODER_WEB_TERMINAL_RENDERER` | [`--web-terminal-renderer`](../../reference/cli/server.md#--web-terminal-renderer) | `client.webTerminalRenderer` | `canvas` | The renderer to use when opening a web terminal. Valid values are 'canvas', 'webgl', or 'dom'. | -| Workspace Hostname Suffix | `CODER_WORKSPACE_HOSTNAME_SUFFIX` | [`--workspace-hostname-suffix`](../../reference/cli/server.md#--workspace-hostname-suffix) | `client.workspaceHostnameSuffix` | `coder` | Workspace hostnames use this suffix in SSH config and Coder Connect on Coder Desktop. By default it is coder, resulting in names like myworkspace.coder. The suffix must not start with a dot, and must not contain spaces, newlines, or glob characters (* and ?). | +- Environment variable: `CODER_STRICT_TRANSPORT_SECURITY_OPTIONS` +- CLI flag: [`--strict-transport-security-options`](../../reference/cli/server.md#--strict-transport-security-options) +- YAML key: `networking.tls.strictTransportSecurityOptions` -## Config +#### Address -| Setting | Env var | Flag | YAML | Default | Description | -|--------------|---------------------|------------------------------------------------------------------|------|---------|--------------------------------------------------------| -| Config Path | `CODER_CONFIG_PATH` | [`--config`](../../reference/cli/server.md#-c---config) | - | - | Specify a YAML file to load configuration from. | -| Write Config | - | [`--write-config`](../../reference/cli/server.md#--write-config) | - | - | Write out the current server config as YAML to stdout. | +HTTPS bind address of the server. -## Email +- Environment variable: `CODER_TLS_ADDRESS` +- CLI flag: [`--tls-address`](../../reference/cli/server.md#--tls-address) +- YAML key: `networking.tls.address` +- Default value: `127.0.0.1:3443` -| Setting | Env var | Flag | YAML | Default | Description | -|---------------------|-------------------------|------------------------------------------------------------------------|-------------------|-------------|-----------------------------------------------------------| -| Email: Force TLS | `CODER_EMAIL_FORCE_TLS` | [`--email-force-tls`](../../reference/cli/server.md#--email-force-tls) | `email.forceTLS` | `false` | Force a TLS connection to the configured SMTP smarthost. | -| Email: From Address | `CODER_EMAIL_FROM` | [`--email-from`](../../reference/cli/server.md#--email-from) | `email.from` | - | The sender's address to use. | -| Email: Hello | `CODER_EMAIL_HELLO` | [`--email-hello`](../../reference/cli/server.md#--email-hello) | `email.hello` | `localhost` | The hostname identifying the SMTP server. | -| Email: Smarthost | `CODER_EMAIL_SMARTHOST` | [`--email-smarthost`](../../reference/cli/server.md#--email-smarthost) | `email.smarthost` | - | The intermediary SMTP host through which emails are sent. | - -## Email / Email Authentication - -| Setting | Env var | Flag | YAML | Default | Description | -|---------------------------|----------------------------------|------------------------------------------------------------------------------------------|--------------------------------|---------|---------------------------------------------------------------------------| -| Email Auth: Identity | `CODER_EMAIL_AUTH_IDENTITY` | [`--email-auth-identity`](../../reference/cli/server.md#--email-auth-identity) | `email.emailAuth.identity` | - | Identity to use with PLAIN authentication. | -| Email Auth: Password | `CODER_EMAIL_AUTH_PASSWORD` | [`--email-auth-password`](../../reference/cli/server.md#--email-auth-password) | - | - | Password to use with PLAIN/LOGIN authentication. | -| Email Auth: Password File | `CODER_EMAIL_AUTH_PASSWORD_FILE` | [`--email-auth-password-file`](../../reference/cli/server.md#--email-auth-password-file) | `email.emailAuth.passwordFile` | - | File from which to load password for use with PLAIN/LOGIN authentication. | -| Email Auth: Username | `CODER_EMAIL_AUTH_USERNAME` | [`--email-auth-username`](../../reference/cli/server.md#--email-auth-username) | `email.emailAuth.username` | - | Username to use with PLAIN/LOGIN authentication. | - -## Email / Email TLS - -| Setting | Env var | Flag | YAML | Default | Description | -|-----------------------------------------------------|-------------------------------|----------------------------------------------------------------------------------------|-------------------------------------|---------|------------------------------------------------------------------| -| Email TLS: Certificate Authority File | `CODER_EMAIL_TLS_CACERTFILE` | [`--email-tls-ca-cert-file`](../../reference/cli/server.md#--email-tls-ca-cert-file) | `email.emailTLS.caCertFile` | - | CA certificate file to use. | -| Email TLS: Certificate File | `CODER_EMAIL_TLS_CERTFILE` | [`--email-tls-cert-file`](../../reference/cli/server.md#--email-tls-cert-file) | `email.emailTLS.certFile` | - | Certificate file to use. | -| Email TLS: Certificate Key File | `CODER_EMAIL_TLS_CERTKEYFILE` | [`--email-tls-cert-key-file`](../../reference/cli/server.md#--email-tls-cert-key-file) | `email.emailTLS.certKeyFile` | - | Certificate key file to use. | -| Email TLS: Server Name | `CODER_EMAIL_TLS_SERVERNAME` | [`--email-tls-server-name`](../../reference/cli/server.md#--email-tls-server-name) | `email.emailTLS.serverName` | - | Server name to verify against the target certificate. | -| Email TLS: Skip Certificate Verification (Insecure) | `CODER_EMAIL_TLS_SKIPVERIFY` | [`--email-tls-skip-verify`](../../reference/cli/server.md#--email-tls-skip-verify) | `email.emailTLS.insecureSkipVerify` | - | Skip verification of the target server's certificate (insecure). | -| Email TLS: StartTLS | `CODER_EMAIL_TLS_STARTTLS` | [`--email-tls-starttls`](../../reference/cli/server.md#--email-tls-starttls) | `email.emailTLS.startTLS` | - | Enable STARTTLS to upgrade insecure SMTP connections using TLS. | - -## Introspection / Health Check - -| Setting | Env var | Flag | YAML | Default | Description | -|----------------------------------|-----------------------------------------|--------------------------------------------------------------------------------------------------------|-----------------------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Health Check Refresh | `CODER_HEALTH_CHECK_REFRESH` | [`--health-check-refresh`](../../reference/cli/server.md#--health-check-refresh) | `introspection.healthcheck.refresh` | `10m0s` | Refresh interval for healthchecks. | -| Health Check Threshold: Database | `CODER_HEALTH_CHECK_THRESHOLD_DATABASE` | [`--health-check-threshold-database`](../../reference/cli/server.md#--health-check-threshold-database) | `introspection.healthcheck.thresholdDatabase` | `15ms` | The threshold for the database health check. If the median latency of the database exceeds this threshold over 5 attempts, the database is considered unhealthy. The default value is 15ms. | - -## Introspection / Logging - -| Setting | Env var | Flag | YAML | Default | Description | -|-----------------------------|-------------------------------------|------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------|--------------------------------------------------------------------------------------| -| Enable Terraform debug mode | `CODER_ENABLE_TERRAFORM_DEBUG_MODE` | [`--enable-terraform-debug-mode`](../../reference/cli/server.md#--enable-terraform-debug-mode) | `introspection.logging.enableTerraformDebugMode` | `false` | Allow administrators to enable Terraform debug output. | -| Human Log Location | `CODER_LOGGING_HUMAN` | [`--log-human`](../../reference/cli/server.md#--log-human) | `introspection.logging.humanPath` | `/dev/stderr` | Output human-readable logs to a given file. | -| JSON Log Location | `CODER_LOGGING_JSON` | [`--log-json`](../../reference/cli/server.md#--log-json) | `introspection.logging.jsonPath` | - | Output JSON logs to a given file. | -| Log Filter | `CODER_LOG_FILTER` | [`--log-filter`](../../reference/cli/server.md#-l---log-filter) | `introspection.logging.filter` | - | Filter debug logs by matching against a given regex. Use .* to match all debug logs. | -| Stackdriver Log Location | `CODER_LOGGING_STACKDRIVER` | [`--log-stackdriver`](../../reference/cli/server.md#--log-stackdriver) | `introspection.logging.stackdriverPath` | - | Output Stackdriver compatible logs to a given file. | - -## Introspection / Prometheus - -| Setting | Env var | Flag | YAML | Default | Description | -|-------------------------------------|---------------------------------------------|----------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Prometheus Address | `CODER_PROMETHEUS_ADDRESS` | [`--prometheus-address`](../../reference/cli/server.md#--prometheus-address) | `introspection.prometheus.address` | `127.0.0.1:2112` | The bind address to serve prometheus metrics. | -| Prometheus Aggregate Agent Stats By | `CODER_PROMETHEUS_AGGREGATE_AGENT_STATS_BY` | [`--prometheus-aggregate-agent-stats-by`](../../reference/cli/server.md#--prometheus-aggregate-agent-stats-by) | `introspection.prometheus.aggregate_agent_stats_by` | `agent_name,template_name,username,workspace_name` | When collecting agent stats, aggregate metrics by a given set of comma-separated labels to reduce cardinality. Accepted values are agent_name, template_name, username, workspace_name. | -| Prometheus Collect Agent Stats | `CODER_PROMETHEUS_COLLECT_AGENT_STATS` | [`--prometheus-collect-agent-stats`](../../reference/cli/server.md#--prometheus-collect-agent-stats) | `introspection.prometheus.collect_agent_stats` | - | Collect agent stats (may increase charges for metrics storage). | -| Prometheus Collect Database Metrics | `CODER_PROMETHEUS_COLLECT_DB_METRICS` | [`--prometheus-collect-db-metrics`](../../reference/cli/server.md#--prometheus-collect-db-metrics) | `introspection.prometheus.collect_db_metrics` | `false` | Collect database query metrics (may increase charges for metrics storage). If set to false, a reduced set of database metrics are still collected. | -| Prometheus Enable | `CODER_PROMETHEUS_ENABLE` | [`--prometheus-enable`](../../reference/cli/server.md#--prometheus-enable) | `introspection.prometheus.enable` | - | Serve prometheus metrics on the address defined by prometheus address. | - -## Introspection / Stats Collection / Usage Stats - -| Setting | Env var | Flag | YAML | Default | Description | -|-------------------------------------|---------------------------------------------|----------------------------------------------------------------------------------------------------------------|---------------------------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Stats Collection Usage Stats Enable | `CODER_STATS_COLLECTION_USAGE_STATS_ENABLE` | [`--stats-collection-usage-stats-enable`](../../reference/cli/server.md#--stats-collection-usage-stats-enable) | `introspection.statsCollection.usageStats.enable` | `true` | Enable the collection of application and workspace usage along with the associated API endpoints and the template insights page. Disabling this will also disable traffic and connection insights in the deployment stats shown to admins in the bottom bar of the Coder UI, and will prevent Prometheus collection of these values. | - -## Introspection / Tracing - -| Setting | Env var | Flag | YAML | Default | Description | -|-------------------------|---------------------------------|----------------------------------------------------------------------------------------|-------------------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Capture Logs in Traces | `CODER_TRACE_LOGS` | [`--trace-logs`](../../reference/cli/server.md#--trace-logs) | `introspection.tracing.captureLogs` | - | Enables capturing of logs as events in traces. This is useful for debugging, but may result in a very large amount of events being sent to the tracing backend which may incur significant costs. | -| Trace Enable | `CODER_TRACE_ENABLE` | [`--trace`](../../reference/cli/server.md#--trace) | `introspection.tracing.enable` | - | Whether application tracing data is collected. It exports to a backend configured by environment variables. See: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md. | -| Trace Honeycomb API Key | `CODER_TRACE_HONEYCOMB_API_KEY` | [`--trace-honeycomb-api-key`](../../reference/cli/server.md#--trace-honeycomb-api-key) | - | - | Enables trace exporting to Honeycomb.io using the provided API Key. | - -## Introspection / pprof - -| Setting | Env var | Flag | YAML | Default | Description | -|---------------|-----------------------|--------------------------------------------------------------------|-------------------------------|------------------|--------------------------------------------------------------| -| pprof Address | `CODER_PPROF_ADDRESS` | [`--pprof-address`](../../reference/cli/server.md#--pprof-address) | `introspection.pprof.address` | `127.0.0.1:6060` | The bind address to serve pprof. | -| pprof Enable | `CODER_PPROF_ENABLE` | [`--pprof-enable`](../../reference/cli/server.md#--pprof-enable) | `introspection.pprof.enable` | - | Serve pprof metrics on the address defined by pprof address. | +#### Allow insecure ciphers -## Networking +By default, only ciphers marked as 'secure' are allowed to be used. See https://github.com/golang/go/blob/master/src/crypto/tls/cipher_suites.go#L82-L95. + +- Environment variable: `CODER_TLS_ALLOW_INSECURE_CIPHERS` +- CLI flag: [`--tls-allow-insecure-ciphers`](../../reference/cli/server.md#--tls-allow-insecure-ciphers) +- YAML key: `networking.tls.tlsAllowInsecureCiphers` +- Default value: `false` + +#### Certificate files + +Path to each 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. + +- Environment variable: `CODER_TLS_CERT_FILE` +- CLI flag: [`--tls-cert-file`](../../reference/cli/server.md#--tls-cert-file) +- YAML key: `networking.tls.certFiles` + +#### Ciphers + +Specify specific TLS ciphers that allowed to be used. See https://github.com/golang/go/blob/master/src/crypto/tls/cipher_suites.go#L53-L75. + +- Environment variable: `CODER_TLS_CIPHERS` +- CLI flag: [`--tls-ciphers`](../../reference/cli/server.md#--tls-ciphers) +- YAML key: `networking.tls.tlsCiphers` + +#### Client auth + +Policy the server will follow for TLS Client Authentication. Accepted values are "none", "request", "require-any", "verify-if-given", or "require-and-verify". + +- Environment variable: `CODER_TLS_CLIENT_AUTH` +- CLI flag: [`--tls-client-auth`](../../reference/cli/server.md#--tls-client-auth) +- YAML key: `networking.tls.clientAuth` +- Default value: `none` + +#### Client CA files + +PEM-encoded Certificate Authority file used for checking the authenticity of client. + +- Environment variable: `CODER_TLS_CLIENT_CA_FILE` +- CLI flag: [`--tls-client-ca-file`](../../reference/cli/server.md#--tls-client-ca-file) +- YAML key: `networking.tls.clientCAFile` + +#### Client cert file + +Path to certificate for client TLS authentication. It requires a PEM-encoded file. + +- Environment variable: `CODER_TLS_CLIENT_CERT_FILE` +- CLI flag: [`--tls-client-cert-file`](../../reference/cli/server.md#--tls-client-cert-file) +- YAML key: `networking.tls.clientCertFile` + +#### Client key file + +Path to key for client TLS authentication. It requires a PEM-encoded file. + +- Environment variable: `CODER_TLS_CLIENT_KEY_FILE` +- CLI flag: [`--tls-client-key-file`](../../reference/cli/server.md#--tls-client-key-file) +- YAML key: `networking.tls.clientKeyFile` + +#### Enable + +Whether TLS will be enabled. + +- Environment variable: `CODER_TLS_ENABLE` +- CLI flag: [`--tls-enable`](../../reference/cli/server.md#--tls-enable) +- YAML key: `networking.tls.enable` + +#### Key files + +Paths to the private keys for each of the certificates. It requires a PEM-encoded file. + +- Environment variable: `CODER_TLS_KEY_FILE` +- CLI flag: [`--tls-key-file`](../../reference/cli/server.md#--tls-key-file) +- YAML key: `networking.tls.keyFiles` + +#### Minimum version + +Minimum supported version of TLS. Accepted values are "tls10", "tls11", "tls12" or "tls13". -| Setting | Env var | Flag | YAML | Default | Description | -|------------------------|--------------------------------|--------------------------------------------------------------------------------------|----------------------------------|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Access URL | `CODER_ACCESS_URL` | [`--access-url`](../../reference/cli/server.md#--access-url) | `networking.accessURL` | - | The URL that users will use to access the Coder deployment. | -| Browser Only | `CODER_BROWSER_ONLY` | [`--browser-only`](../../reference/cli/server.md#--browser-only) | `networking.browserOnly` | - | Whether Coder only allows connections to workspaces via the browser. | -| Docs URL | `CODER_DOCS_URL` | [`--docs-url`](../../reference/cli/server.md#--docs-url) | `networking.docsURL` | `https://coder.com/docs` | Specifies the custom docs URL. | -| Proxy Trusted Headers | `CODER_PROXY_TRUSTED_HEADERS` | [`--proxy-trusted-headers`](../../reference/cli/server.md#--proxy-trusted-headers) | `networking.proxyTrustedHeaders` | - | Headers to trust for forwarding IP addresses. e.g. Cf-Connecting-Ip, True-Client-Ip, X-Forwarded-For. | -| Proxy Trusted Origins | `CODER_PROXY_TRUSTED_ORIGINS` | [`--proxy-trusted-origins`](../../reference/cli/server.md#--proxy-trusted-origins) | `networking.proxyTrustedOrigins` | - | Origin addresses to respect "proxy-trusted-headers" and X-Forwarded-Host for subdomain app routing. e.g. 192.168.1.0/24. | -| Redirect to Access URL | `CODER_REDIRECT_TO_ACCESS_URL` | [`--redirect-to-access-url`](../../reference/cli/server.md#--redirect-to-access-url) | `networking.redirectToAccessURL` | - | Specifies whether to redirect requests that do not match the access URL host. | -| SameSite Auth Cookie | `CODER_SAMESITE_AUTH_COOKIE` | [`--samesite-auth-cookie`](../../reference/cli/server.md#--samesite-auth-cookie) | `networking.sameSiteAuthCookie` | `lax` | Controls the 'SameSite' property is set on browser session cookies. | -| Secure Auth Cookie | `CODER_SECURE_AUTH_COOKIE` | [`--secure-auth-cookie`](../../reference/cli/server.md#--secure-auth-cookie) | `networking.secureAuthCookie` | `(computed at runtime)` | Controls if the 'Secure' property is set on browser session cookies. | -| Wildcard Access URL | `CODER_WILDCARD_ACCESS_URL` | [`--wildcard-access-url`](../../reference/cli/server.md#--wildcard-access-url) | `networking.wildcardAccessURL` | - | Specifies the wildcard hostname to use for workspace applications in the form "*.example.com". | -| __Host Prefix Cookies | `CODER_HOST_PREFIX_COOKIE` | [`--host-prefix-cookie`](../../reference/cli/server.md#--host-prefix-cookie) | `networking.hostPrefixCookie` | `false` | Recommended to be enabled. Enables `__Host-` prefix for cookies to guarantee they are only set by the right domain. This change is disruptive to any workspaces built before release 2.31, requiring a workspace restart. | - -## Networking / Cluster - -| Setting | Env var | Flag | YAML | Default | Description | -|--------------|----------------------|------------------------------------------------------------------|----------------------------------|---------|----------------------------------------------------------------------| -| Cluster Host | `CODER_CLUSTER_HOST` | [`--cluster-host`](../../reference/cli/server.md#--cluster-host) | `networking.cluster.clusterHost` | - | Hostname or (more commonly) IP to reach this replica for clustering. | - -## Networking / DERP - -| Setting | Env var | Flag | YAML | Default | Description | -|----------------------------|------------------------------------|----------------------------------------------------------------------------------------------|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Block Direct Connections | `CODER_BLOCK_DIRECT` | [`--block-direct-connections`](../../reference/cli/server.md#--block-direct-connections) | `networking.derp.blockDirect` | - | Block peer-to-peer (aka. direct) workspace connections. All workspace connections from the CLI will be proxied through Coder (or custom configured DERP servers) and will never be peer-to-peer when enabled. Workspaces may still reach out to STUN servers to get their address until they are restarted after this change has been made, but new connections will still be proxied regardless. | -| DERP Config Path | `CODER_DERP_CONFIG_PATH` | [`--derp-config-path`](../../reference/cli/server.md#--derp-config-path) | `networking.derp.configPath` | - | Path to read a DERP mapping from. See: https://tailscale.com/kb/1118/custom-derp-servers/. | -| DERP Config URL | `CODER_DERP_CONFIG_URL` | [`--derp-config-url`](../../reference/cli/server.md#--derp-config-url) | `networking.derp.url` | - | URL to fetch a DERP mapping on startup. See: https://tailscale.com/kb/1118/custom-derp-servers/. | -| DERP Force WebSockets | `CODER_DERP_FORCE_WEBSOCKETS` | [`--derp-force-websockets`](../../reference/cli/server.md#--derp-force-websockets) | `networking.derp.forceWebSockets` | - | Force clients and agents to always use WebSocket to connect to DERP relay servers. By default, DERP uses `Upgrade: derp`, which may cause issues with some reverse proxies. Clients may automatically fallback to WebSocket if they detect an issue with `Upgrade: derp`, but this does not work in all situations. | -| DERP Server Enable | `CODER_DERP_SERVER_ENABLE` | [`--derp-server-enable`](../../reference/cli/server.md#--derp-server-enable) | `networking.derp.enable` | `true` | Whether to enable or disable the embedded DERP relay server. | -| DERP Server Region Name | `CODER_DERP_SERVER_REGION_NAME` | [`--derp-server-region-name`](../../reference/cli/server.md#--derp-server-region-name) | `networking.derp.regionName` | `Coder Embedded Relay` | Region name that for the embedded DERP server. | -| DERP Server Relay URL | `CODER_DERP_SERVER_RELAY_URL` | [`--derp-server-relay-url`](../../reference/cli/server.md#--derp-server-relay-url) | `networking.derp.relayURL` | - | An HTTP URL that is accessible by other replicas to relay DERP traffic. Required for high availability. | -| DERP Server STUN Addresses | `CODER_DERP_SERVER_STUN_ADDRESSES` | [`--derp-server-stun-addresses`](../../reference/cli/server.md#--derp-server-stun-addresses) | `networking.derp.stunAddresses` | `stun.l.google.com:19302,stun1.l.google.com:19302,stun2.l.google.com:19302,stun3.l.google.com:19302,stun4.l.google.com:19302` | Addresses for STUN servers to establish P2P connections. It's recommended to have at least two STUN servers to give users the best chance of connecting P2P to workspaces. Each STUN server will get it's own DERP region, with region IDs starting at `--derp-server-region-id + 1`. Use special value 'disable' to turn off STUN completely. | - -## Networking / HTTP - -| Setting | Env var | Flag | YAML | Default | Description | -|---------------------------------|----------------------------------------|------------------------------------------------------------------------------------------------------|-----------------------------------------------|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Additional CSP Policy | `CODER_ADDITIONAL_CSP_POLICY` | [`--additional-csp-policy`](../../reference/cli/server.md#--additional-csp-policy) | `networking.http.additionalCSPPolicy` | - | Coder configures a Content Security Policy (CSP) to protect against XSS attacks. This setting allows you to add additional CSP directives, which can open the attack surface of the deployment. Format matches the CSP directive format, e.g. --additional-csp-policy="script-src https://example.com". | -| Disable Password Authentication | `CODER_DISABLE_PASSWORD_AUTH` | [`--disable-password-auth`](../../reference/cli/server.md#--disable-password-auth) | `networking.http.disablePasswordAuth` | - | Disable password authentication. This is recommended for security purposes in production deployments that rely on an identity provider. Any user with the owner role will be able to sign in with their password regardless of this setting to avoid potential lock out. If you are locked out of your account, you can use the `coder server create-admin` command to create a new admin user directly in the database. | -| Disable Session Expiry Refresh | `CODER_DISABLE_SESSION_EXPIRY_REFRESH` | [`--disable-session-expiry-refresh`](../../reference/cli/server.md#--disable-session-expiry-refresh) | `networking.http.disableSessionExpiryRefresh` | - | Disable automatic session expiry bumping due to activity. This forces all sessions to become invalid after the session expiry duration has been reached. | -| HTTP Address | `CODER_HTTP_ADDRESS` | [`--http-address`](../../reference/cli/server.md#--http-address) | `networking.http.httpAddress` | `127.0.0.1:3000` | HTTP bind address of the server. Unset to disable the HTTP endpoint. | -| Max Token Lifetime | `CODER_MAX_TOKEN_LIFETIME` | [`--max-token-lifetime`](../../reference/cli/server.md#--max-token-lifetime) | `networking.http.maxTokenLifetime` | `876600h0m0s` | The maximum lifetime duration users can specify when creating an API token. | -| Maximum Admin Token Lifetime | `CODER_MAX_ADMIN_TOKEN_LIFETIME` | [`--max-admin-token-lifetime`](../../reference/cli/server.md#--max-admin-token-lifetime) | `networking.http.maxAdminTokenLifetime` | `168h0m0s` | The maximum lifetime duration administrators can specify when creating an API token. | -| Proxy Health Check Interval | `CODER_PROXY_HEALTH_INTERVAL` | [`--proxy-health-interval`](../../reference/cli/server.md#--proxy-health-interval) | `networking.http.proxyHealthInterval` | `1m0s` | The interval in which coderd should be checking the status of workspace proxies. | -| Session Duration | `CODER_SESSION_DURATION` | [`--session-duration`](../../reference/cli/server.md#--session-duration) | `networking.http.sessionDuration` | `24h0m0s` | The token expiry duration for browser sessions. Sessions may last longer if they are actively making requests, but this functionality can be disabled via --disable-session-expiry-refresh. | - -## Networking / TLS - -| Setting | Env var | Flag | YAML | Default | Description | -|-----------------------------------|-------------------------------------------|------------------------------------------------------------------------------------------------------------|-------------------------------------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Strict-Transport-Security | `CODER_STRICT_TRANSPORT_SECURITY` | [`--strict-transport-security`](../../reference/cli/server.md#--strict-transport-security) | `networking.tls.strictTransportSecurity` | `0` | Controls if the 'Strict-Transport-Security' header is set on all static file responses. This header should only be set if the server is accessed via HTTPS. This value is the MaxAge in seconds of the header. | -| Strict-Transport-Security Options | `CODER_STRICT_TRANSPORT_SECURITY_OPTIONS` | [`--strict-transport-security-options`](../../reference/cli/server.md#--strict-transport-security-options) | `networking.tls.strictTransportSecurityOptions` | - | Two optional fields can be set in the Strict-Transport-Security header; 'includeSubDomains' and 'preload'. The 'strict-transport-security' flag must be set to a non-zero value for these options to be used. | -| TLS Address | `CODER_TLS_ADDRESS` | [`--tls-address`](../../reference/cli/server.md#--tls-address) | `networking.tls.address` | `127.0.0.1:3443` | HTTPS bind address of the server. | -| TLS Allow Insecure Ciphers | `CODER_TLS_ALLOW_INSECURE_CIPHERS` | [`--tls-allow-insecure-ciphers`](../../reference/cli/server.md#--tls-allow-insecure-ciphers) | `networking.tls.tlsAllowInsecureCiphers` | `false` | By default, only ciphers marked as 'secure' are allowed to be used. See https://github.com/golang/go/blob/master/src/crypto/tls/cipher_suites.go#L82-L95. | -| TLS Certificate Files | `CODER_TLS_CERT_FILE` | [`--tls-cert-file`](../../reference/cli/server.md#--tls-cert-file) | `networking.tls.certFiles` | - | Path to each 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. | -| TLS Ciphers | `CODER_TLS_CIPHERS` | [`--tls-ciphers`](../../reference/cli/server.md#--tls-ciphers) | `networking.tls.tlsCiphers` | - | Specify specific TLS ciphers that allowed to be used. See https://github.com/golang/go/blob/master/src/crypto/tls/cipher_suites.go#L53-L75. | -| TLS Client Auth | `CODER_TLS_CLIENT_AUTH` | [`--tls-client-auth`](../../reference/cli/server.md#--tls-client-auth) | `networking.tls.clientAuth` | `none` | Policy the server will follow for TLS Client Authentication. Accepted values are "none", "request", "require-any", "verify-if-given", or "require-and-verify". | -| TLS Client CA Files | `CODER_TLS_CLIENT_CA_FILE` | [`--tls-client-ca-file`](../../reference/cli/server.md#--tls-client-ca-file) | `networking.tls.clientCAFile` | - | PEM-encoded Certificate Authority file used for checking the authenticity of client. | -| TLS Client Cert File | `CODER_TLS_CLIENT_CERT_FILE` | [`--tls-client-cert-file`](../../reference/cli/server.md#--tls-client-cert-file) | `networking.tls.clientCertFile` | - | Path to certificate for client TLS authentication. It requires a PEM-encoded file. | -| TLS Client Key File | `CODER_TLS_CLIENT_KEY_FILE` | [`--tls-client-key-file`](../../reference/cli/server.md#--tls-client-key-file) | `networking.tls.clientKeyFile` | - | Path to key for client TLS authentication. It requires a PEM-encoded file. | -| TLS Enable | `CODER_TLS_ENABLE` | [`--tls-enable`](../../reference/cli/server.md#--tls-enable) | `networking.tls.enable` | - | Whether TLS will be enabled. | -| TLS Key Files | `CODER_TLS_KEY_FILE` | [`--tls-key-file`](../../reference/cli/server.md#--tls-key-file) | `networking.tls.keyFiles` | - | Paths to the private keys for each of the certificates. It requires a PEM-encoded file. | -| TLS Minimum Version | `CODER_TLS_MIN_VERSION` | [`--tls-min-version`](../../reference/cli/server.md#--tls-min-version) | `networking.tls.minVersion` | `tls12` | Minimum supported version of TLS. Accepted values are "tls10", "tls11", "tls12" or "tls13". | +- Environment variable: `CODER_TLS_MIN_VERSION` +- CLI flag: [`--tls-min-version`](../../reference/cli/server.md#--tls-min-version) +- YAML key: `networking.tls.minVersion` +- Default value: `tls12` ## Notifications -| Setting | Env var | Flag | YAML | Default | Description | -|----------------------------------|-----------------------------------------|--------------------------------------------------------------------------------------------------------|---------------------------------|---------|-----------------------------------------------------------------------| -| Notifications: Dispatch Timeout | `CODER_NOTIFICATIONS_DISPATCH_TIMEOUT` | [`--notifications-dispatch-timeout`](../../reference/cli/server.md#--notifications-dispatch-timeout) | `notifications.dispatchTimeout` | `1m0s` | How long to wait while a notification is being sent before giving up. | -| Notifications: Max Send Attempts | `CODER_NOTIFICATIONS_MAX_SEND_ATTEMPTS` | [`--notifications-max-send-attempts`](../../reference/cli/server.md#--notifications-max-send-attempts) | `notifications.maxSendAttempts` | `5` | The upper limit of attempts to send a notification. | -| Notifications: Method | `CODER_NOTIFICATIONS_METHOD` | [`--notifications-method`](../../reference/cli/server.md#--notifications-method) | `notifications.method` | `smtp` | Which delivery method to use (available options: 'smtp', 'webhook'). | - -## Notifications / Email - -| Setting | Env var | Flag | YAML | Default | Description | -|------------------------------------|---------------------------------------|----------------------------------------------------------------------------------------------------|---------------------------------|---------|-----------------------------------------------------------| -| Notifications: Email: Force TLS | `CODER_NOTIFICATIONS_EMAIL_FORCE_TLS` | [`--notifications-email-force-tls`](../../reference/cli/server.md#--notifications-email-force-tls) | `notifications.email.forceTLS` | - | Force a TLS connection to the configured SMTP smarthost. | -| Notifications: Email: From Address | `CODER_NOTIFICATIONS_EMAIL_FROM` | [`--notifications-email-from`](../../reference/cli/server.md#--notifications-email-from) | `notifications.email.from` | - | The sender's address to use. | -| Notifications: Email: Hello | `CODER_NOTIFICATIONS_EMAIL_HELLO` | [`--notifications-email-hello`](../../reference/cli/server.md#--notifications-email-hello) | `notifications.email.hello` | - | The hostname identifying the SMTP server. | -| Notifications: Email: Smarthost | `CODER_NOTIFICATIONS_EMAIL_SMARTHOST` | [`--notifications-email-smarthost`](../../reference/cli/server.md#--notifications-email-smarthost) | `notifications.email.smarthost` | - | The intermediary SMTP host through which emails are sent. | - -## Notifications / Email / Email Authentication - -| Setting | Env var | Flag | YAML | Default | Description | -|------------------------------------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|----------------------------------------------|---------|---------------------------------------------------------------------------| -| Notifications: Email Auth: Identity | `CODER_NOTIFICATIONS_EMAIL_AUTH_IDENTITY` | [`--notifications-email-auth-identity`](../../reference/cli/server.md#--notifications-email-auth-identity) | `notifications.email.emailAuth.identity` | - | Identity to use with PLAIN authentication. | -| Notifications: Email Auth: Password | `CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD` | [`--notifications-email-auth-password`](../../reference/cli/server.md#--notifications-email-auth-password) | - | - | Password to use with PLAIN/LOGIN authentication. | -| Notifications: Email Auth: Password File | `CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD_FILE` | [`--notifications-email-auth-password-file`](../../reference/cli/server.md#--notifications-email-auth-password-file) | `notifications.email.emailAuth.passwordFile` | - | File from which to load password for use with PLAIN/LOGIN authentication. | -| Notifications: Email Auth: Username | `CODER_NOTIFICATIONS_EMAIL_AUTH_USERNAME` | [`--notifications-email-auth-username`](../../reference/cli/server.md#--notifications-email-auth-username) | `notifications.email.emailAuth.username` | - | Username to use with PLAIN/LOGIN authentication. | - -## Notifications / Email / Email TLS - -| Setting | Env var | Flag | YAML | Default | Description | -|--------------------------------------------------------------------|---------------------------------------------|--------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|---------|------------------------------------------------------------------| -| Notifications: Email TLS: Certificate Authority File | `CODER_NOTIFICATIONS_EMAIL_TLS_CACERTFILE` | [`--notifications-email-tls-ca-cert-file`](../../reference/cli/server.md#--notifications-email-tls-ca-cert-file) | `notifications.email.emailTLS.caCertFile` | - | CA certificate file to use. | -| Notifications: Email TLS: Certificate File | `CODER_NOTIFICATIONS_EMAIL_TLS_CERTFILE` | [`--notifications-email-tls-cert-file`](../../reference/cli/server.md#--notifications-email-tls-cert-file) | `notifications.email.emailTLS.certFile` | - | Certificate file to use. | -| Notifications: Email TLS: Certificate Key File | `CODER_NOTIFICATIONS_EMAIL_TLS_CERTKEYFILE` | [`--notifications-email-tls-cert-key-file`](../../reference/cli/server.md#--notifications-email-tls-cert-key-file) | `notifications.email.emailTLS.certKeyFile` | - | Certificate key file to use. | -| Notifications: Email TLS: Server Name | `CODER_NOTIFICATIONS_EMAIL_TLS_SERVERNAME` | [`--notifications-email-tls-server-name`](../../reference/cli/server.md#--notifications-email-tls-server-name) | `notifications.email.emailTLS.serverName` | - | Server name to verify against the target certificate. | -| Notifications: Email TLS: Skip Certificate Verification (Insecure) | `CODER_NOTIFICATIONS_EMAIL_TLS_SKIPVERIFY` | [`--notifications-email-tls-skip-verify`](../../reference/cli/server.md#--notifications-email-tls-skip-verify) | `notifications.email.emailTLS.insecureSkipVerify` | - | Skip verification of the target server's certificate (insecure). | -| Notifications: Email TLS: StartTLS | `CODER_NOTIFICATIONS_EMAIL_TLS_STARTTLS` | [`--notifications-email-tls-starttls`](../../reference/cli/server.md#--notifications-email-tls-starttls) | `notifications.email.emailTLS.startTLS` | - | Enable STARTTLS to upgrade insecure SMTP connections using TLS. | - -## Notifications / Inbox - -| Setting | Env var | Flag | YAML | Default | Description | -|-------------------------------|-------------------------------------|------------------------------------------------------------------------------------------------|-------------------------------|---------|---------------------| -| Notifications: Inbox: Enabled | `CODER_NOTIFICATIONS_INBOX_ENABLED` | [`--notifications-inbox-enabled`](../../reference/cli/server.md#--notifications-inbox-enabled) | `notifications.inbox.enabled` | `true` | Enable Coder Inbox. | - -## Notifications / Webhook - -| Setting | Env var | Flag | YAML | Default | Description | -|----------------------------------|----------------------------------------|------------------------------------------------------------------------------------------------------|----------------------------------|---------|-----------------------------------------| -| Notifications: Webhook: Endpoint | `CODER_NOTIFICATIONS_WEBHOOK_ENDPOINT` | [`--notifications-webhook-endpoint`](../../reference/cli/server.md#--notifications-webhook-endpoint) | `notifications.webhook.endpoint` | - | The endpoint to which to send webhooks. | - -## OAuth2 / GitHub - -| Setting | Env var | Flag | YAML | Default | Description | -|---------------------------------------|-----------------------------------------------|--------------------------------------------------------------------------------------------------------------------|---------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------| -| OAuth2 GitHub Allow Everyone | `CODER_OAUTH2_GITHUB_ALLOW_EVERYONE` | [`--oauth2-github-allow-everyone`](../../reference/cli/server.md#--oauth2-github-allow-everyone) | `oauth2.github.allowEveryone` | - | Allow all logins, setting this option means allowed orgs and teams must be empty. | -| OAuth2 GitHub Allow Signups | `CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS` | [`--oauth2-github-allow-signups`](../../reference/cli/server.md#--oauth2-github-allow-signups) | `oauth2.github.allowSignups` | - | Whether new users can sign up with GitHub. | -| OAuth2 GitHub Allowed Orgs | `CODER_OAUTH2_GITHUB_ALLOWED_ORGS` | [`--oauth2-github-allowed-orgs`](../../reference/cli/server.md#--oauth2-github-allowed-orgs) | `oauth2.github.allowedOrgs` | - | Organizations the user must be a member of to Login with GitHub. | -| OAuth2 GitHub Allowed Teams | `CODER_OAUTH2_GITHUB_ALLOWED_TEAMS` | [`--oauth2-github-allowed-teams`](../../reference/cli/server.md#--oauth2-github-allowed-teams) | `oauth2.github.allowedTeams` | - | Teams inside organizations the user must be a member of to Login with GitHub. Structured as: /. | -| OAuth2 GitHub Client ID | `CODER_OAUTH2_GITHUB_CLIENT_ID` | [`--oauth2-github-client-id`](../../reference/cli/server.md#--oauth2-github-client-id) | `oauth2.github.clientID` | - | Client ID for Login with GitHub. | -| OAuth2 GitHub Client Secret | `CODER_OAUTH2_GITHUB_CLIENT_SECRET` | [`--oauth2-github-client-secret`](../../reference/cli/server.md#--oauth2-github-client-secret) | - | - | Client secret for Login with GitHub. | -| OAuth2 GitHub Default Provider Enable | `CODER_OAUTH2_GITHUB_DEFAULT_PROVIDER_ENABLE` | [`--oauth2-github-default-provider-enable`](../../reference/cli/server.md#--oauth2-github-default-provider-enable) | `oauth2.github.defaultProviderEnable` | `true` | Enable the default GitHub OAuth2 provider managed by Coder. | -| OAuth2 GitHub Device Flow | `CODER_OAUTH2_GITHUB_DEVICE_FLOW` | [`--oauth2-github-device-flow`](../../reference/cli/server.md#--oauth2-github-device-flow) | `oauth2.github.deviceFlow` | `false` | Enable device flow for Login with GitHub. | -| OAuth2 GitHub Enterprise Base URL | `CODER_OAUTH2_GITHUB_ENTERPRISE_BASE_URL` | [`--oauth2-github-enterprise-base-url`](../../reference/cli/server.md#--oauth2-github-enterprise-base-url) | `oauth2.github.enterpriseBaseURL` | - | Base URL of a GitHub Enterprise deployment to use for Login with GitHub. | +Configure how notifications are processed and delivered. + +### Dispatch timeout + +How long to wait while a notification is being sent before giving up. + +- Environment variable: `CODER_NOTIFICATIONS_DISPATCH_TIMEOUT` +- CLI flag: [`--notifications-dispatch-timeout`](../../reference/cli/server.md#--notifications-dispatch-timeout) +- YAML key: `notifications.dispatchTimeout` +- Default value: `1m0s` + +### Max send attempts + +The upper limit of attempts to send a notification. + +- Environment variable: `CODER_NOTIFICATIONS_MAX_SEND_ATTEMPTS` +- CLI flag: [`--notifications-max-send-attempts`](../../reference/cli/server.md#--notifications-max-send-attempts) +- YAML key: `notifications.maxSendAttempts` +- Default value: `5` + +### Method + +Which delivery method to use (available options: 'smtp', 'webhook'). + +- Environment variable: `CODER_NOTIFICATIONS_METHOD` +- CLI flag: [`--notifications-method`](../../reference/cli/server.md#--notifications-method) +- YAML key: `notifications.method` +- Default value: `smtp` + +### Email + +Configure how email notifications are sent. + +#### Force TLS + +**Deprecated.** Force a TLS connection to the configured SMTP smarthost. + +- Environment variable: `CODER_NOTIFICATIONS_EMAIL_FORCE_TLS` +- CLI flag: [`--notifications-email-force-tls`](../../reference/cli/server.md#--notifications-email-force-tls) +- YAML key: `notifications.email.forceTLS` + +#### From address + +**Deprecated.** The sender's address to use. + +- Environment variable: `CODER_NOTIFICATIONS_EMAIL_FROM` +- CLI flag: [`--notifications-email-from`](../../reference/cli/server.md#--notifications-email-from) +- YAML key: `notifications.email.from` + +#### Hello + +**Deprecated.** The hostname identifying the SMTP server. + +- Environment variable: `CODER_NOTIFICATIONS_EMAIL_HELLO` +- CLI flag: [`--notifications-email-hello`](../../reference/cli/server.md#--notifications-email-hello) +- YAML key: `notifications.email.hello` + +#### Smarthost + +**Deprecated.** The intermediary SMTP host through which emails are sent. + +- Environment variable: `CODER_NOTIFICATIONS_EMAIL_SMARTHOST` +- CLI flag: [`--notifications-email-smarthost`](../../reference/cli/server.md#--notifications-email-smarthost) +- YAML key: `notifications.email.smarthost` + +#### Email authentication + +Configure SMTP authentication options. + +##### Identity + +**Deprecated.** Identity to use with PLAIN authentication. + +- Environment variable: `CODER_NOTIFICATIONS_EMAIL_AUTH_IDENTITY` +- CLI flag: [`--notifications-email-auth-identity`](../../reference/cli/server.md#--notifications-email-auth-identity) +- YAML key: `notifications.email.emailAuth.identity` + +##### Password + +**Deprecated.** Password to use with PLAIN/LOGIN authentication. + +- Environment variable: `CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD` +- CLI flag: [`--notifications-email-auth-password`](../../reference/cli/server.md#--notifications-email-auth-password) + +##### Password file + +**Deprecated.** File from which to load password for use with PLAIN/LOGIN authentication. + +- Environment variable: `CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD_FILE` +- CLI flag: [`--notifications-email-auth-password-file`](../../reference/cli/server.md#--notifications-email-auth-password-file) +- YAML key: `notifications.email.emailAuth.passwordFile` + +##### Username + +**Deprecated.** Username to use with PLAIN/LOGIN authentication. + +- Environment variable: `CODER_NOTIFICATIONS_EMAIL_AUTH_USERNAME` +- CLI flag: [`--notifications-email-auth-username`](../../reference/cli/server.md#--notifications-email-auth-username) +- YAML key: `notifications.email.emailAuth.username` + +#### Email TLS + +Configure TLS for your SMTP server target. + +##### Certificate authority file + +**Deprecated.** CA certificate file to use. + +- Environment variable: `CODER_NOTIFICATIONS_EMAIL_TLS_CACERTFILE` +- CLI flag: [`--notifications-email-tls-ca-cert-file`](../../reference/cli/server.md#--notifications-email-tls-ca-cert-file) +- YAML key: `notifications.email.emailTLS.caCertFile` + +##### Certificate file + +**Deprecated.** Certificate file to use. + +- Environment variable: `CODER_NOTIFICATIONS_EMAIL_TLS_CERTFILE` +- CLI flag: [`--notifications-email-tls-cert-file`](../../reference/cli/server.md#--notifications-email-tls-cert-file) +- YAML key: `notifications.email.emailTLS.certFile` + +##### Certificate key file + +**Deprecated.** Certificate key file to use. + +- Environment variable: `CODER_NOTIFICATIONS_EMAIL_TLS_CERTKEYFILE` +- CLI flag: [`--notifications-email-tls-cert-key-file`](../../reference/cli/server.md#--notifications-email-tls-cert-key-file) +- YAML key: `notifications.email.emailTLS.certKeyFile` + +##### Server name + +**Deprecated.** Server name to verify against the target certificate. + +- Environment variable: `CODER_NOTIFICATIONS_EMAIL_TLS_SERVERNAME` +- CLI flag: [`--notifications-email-tls-server-name`](../../reference/cli/server.md#--notifications-email-tls-server-name) +- YAML key: `notifications.email.emailTLS.serverName` + +##### Skip certificate verification (insecure) + +**Deprecated.** Skip verification of the target server's certificate (insecure). + +- Environment variable: `CODER_NOTIFICATIONS_EMAIL_TLS_SKIPVERIFY` +- CLI flag: [`--notifications-email-tls-skip-verify`](../../reference/cli/server.md#--notifications-email-tls-skip-verify) +- YAML key: `notifications.email.emailTLS.insecureSkipVerify` + +##### StartTLS + +**Deprecated.** Enable STARTTLS to upgrade insecure SMTP connections using TLS. + +- Environment variable: `CODER_NOTIFICATIONS_EMAIL_TLS_STARTTLS` +- CLI flag: [`--notifications-email-tls-starttls`](../../reference/cli/server.md#--notifications-email-tls-starttls) +- YAML key: `notifications.email.emailTLS.startTLS` + +### Inbox + +#### Enabled + +Enable Coder Inbox. + +- Environment variable: `CODER_NOTIFICATIONS_INBOX_ENABLED` +- CLI flag: [`--notifications-inbox-enabled`](../../reference/cli/server.md#--notifications-inbox-enabled) +- YAML key: `notifications.inbox.enabled` +- Default value: `true` + +### Webhook + +#### Endpoint + +The endpoint to which to send webhooks. + +- Environment variable: `CODER_NOTIFICATIONS_WEBHOOK_ENDPOINT` +- CLI flag: [`--notifications-webhook-endpoint`](../../reference/cli/server.md#--notifications-webhook-endpoint) +- YAML key: `notifications.webhook.endpoint` + +## OAuth2 + +Configure login and user-provisioning with GitHub via oAuth2. + +### GitHub + +#### Allow everyone + +Allow all logins, setting this option means allowed orgs and teams must be empty. + +- Environment variable: `CODER_OAUTH2_GITHUB_ALLOW_EVERYONE` +- CLI flag: [`--oauth2-github-allow-everyone`](../../reference/cli/server.md#--oauth2-github-allow-everyone) +- YAML key: `oauth2.github.allowEveryone` + +#### Allow signups + +Whether new users can sign up with GitHub. + +- Environment variable: `CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS` +- CLI flag: [`--oauth2-github-allow-signups`](../../reference/cli/server.md#--oauth2-github-allow-signups) +- YAML key: `oauth2.github.allowSignups` + +#### Allowed orgs + +Organizations the user must be a member of to Login with GitHub. + +- Environment variable: `CODER_OAUTH2_GITHUB_ALLOWED_ORGS` +- CLI flag: [`--oauth2-github-allowed-orgs`](../../reference/cli/server.md#--oauth2-github-allowed-orgs) +- YAML key: `oauth2.github.allowedOrgs` + +#### Allowed teams + +Teams inside organizations the user must be a member of to Login with GitHub. Structured as: /. + +- Environment variable: `CODER_OAUTH2_GITHUB_ALLOWED_TEAMS` +- CLI flag: [`--oauth2-github-allowed-teams`](../../reference/cli/server.md#--oauth2-github-allowed-teams) +- YAML key: `oauth2.github.allowedTeams` + +#### Client ID + +Client ID for Login with GitHub. + +- Environment variable: `CODER_OAUTH2_GITHUB_CLIENT_ID` +- CLI flag: [`--oauth2-github-client-id`](../../reference/cli/server.md#--oauth2-github-client-id) +- YAML key: `oauth2.github.clientID` + +#### Client secret + +Client secret for Login with GitHub. + +- Environment variable: `CODER_OAUTH2_GITHUB_CLIENT_SECRET` +- CLI flag: [`--oauth2-github-client-secret`](../../reference/cli/server.md#--oauth2-github-client-secret) + +#### Default provider enable + +Enable the default GitHub OAuth2 provider managed by Coder. + +- Environment variable: `CODER_OAUTH2_GITHUB_DEFAULT_PROVIDER_ENABLE` +- CLI flag: [`--oauth2-github-default-provider-enable`](../../reference/cli/server.md#--oauth2-github-default-provider-enable) +- YAML key: `oauth2.github.defaultProviderEnable` +- Default value: `true` + +#### Device flow + +Enable device flow for Login with GitHub. + +- Environment variable: `CODER_OAUTH2_GITHUB_DEVICE_FLOW` +- CLI flag: [`--oauth2-github-device-flow`](../../reference/cli/server.md#--oauth2-github-device-flow) +- YAML key: `oauth2.github.deviceFlow` +- Default value: `false` + +#### Enterprise base URL + +Base URL of a GitHub Enterprise deployment to use for Login with GitHub. + +- Environment variable: `CODER_OAUTH2_GITHUB_ENTERPRISE_BASE_URL` +- CLI flag: [`--oauth2-github-enterprise-base-url`](../../reference/cli/server.md#--oauth2-github-enterprise-base-url) +- YAML key: `oauth2.github.enterpriseBaseURL` ## OIDC -| Setting | Env var | Flag | YAML | Default | Description | -|-------------------------------------------|-------------------------------------------|------------------------------------------------------------------------------------------------------------|----------------------------------|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Enable OIDC Group Auto Create | `CODER_OIDC_GROUP_AUTO_CREATE` | [`--oidc-group-auto-create`](../../reference/cli/server.md#--oidc-group-auto-create) | `oidc.enableGroupAutoCreate` | `false` | Automatically creates missing groups from a user's groups claim. | -| OIDC Allow Signups | `CODER_OIDC_ALLOW_SIGNUPS` | [`--oidc-allow-signups`](../../reference/cli/server.md#--oidc-allow-signups) | `oidc.allowSignups` | `true` | Whether new users can sign up with OIDC. | -| OIDC Allowed Groups | `CODER_OIDC_ALLOWED_GROUPS` | [`--oidc-allowed-groups`](../../reference/cli/server.md#--oidc-allowed-groups) | `oidc.groupAllowed` | - | If provided any group name not in the list will not be allowed to authenticate. This allows for restricting access to a specific set of groups. This filter is applied after the group mapping and before the regex filter. | -| OIDC Auth URL Parameters | `CODER_OIDC_AUTH_URL_PARAMS` | [`--oidc-auth-url-params`](../../reference/cli/server.md#--oidc-auth-url-params) | `oidc.authURLParams` | `{"access_type": "offline"}` | OIDC auth URL parameters to pass to the upstream provider. | -| OIDC Client Cert File | `CODER_OIDC_CLIENT_CERT_FILE` | [`--oidc-client-cert-file`](../../reference/cli/server.md#--oidc-client-cert-file) | `oidc.oidcClientCertFile` | - | Pem encoded certificate file to use for oauth2 PKI/JWT authorization. The public certificate that accompanies oidc-client-key-file. A standard x509 certificate is expected. | -| OIDC Client ID | `CODER_OIDC_CLIENT_ID` | [`--oidc-client-id`](../../reference/cli/server.md#--oidc-client-id) | `oidc.clientID` | - | Client ID to use for Login with OIDC. | -| OIDC Client Key File | `CODER_OIDC_CLIENT_KEY_FILE` | [`--oidc-client-key-file`](../../reference/cli/server.md#--oidc-client-key-file) | `oidc.oidcClientKeyFile` | - | Pem encoded RSA private key to use for oauth2 PKI/JWT authorization. This can be used instead of oidc-client-secret if your IDP supports it. | -| OIDC Client Secret | `CODER_OIDC_CLIENT_SECRET` | [`--oidc-client-secret`](../../reference/cli/server.md#--oidc-client-secret) | - | - | Client secret to use for Login with OIDC. | -| OIDC Email Domain | `CODER_OIDC_EMAIL_DOMAIN` | [`--oidc-email-domain`](../../reference/cli/server.md#--oidc-email-domain) | `oidc.emailDomain` | - | Email domains that clients logging in with OIDC must match. | -| OIDC Email Field | `CODER_OIDC_EMAIL_FIELD` | [`--oidc-email-field`](../../reference/cli/server.md#--oidc-email-field) | `oidc.emailField` | `email` | OIDC claim field to use as the email. | -| OIDC Group Field | `CODER_OIDC_GROUP_FIELD` | [`--oidc-group-field`](../../reference/cli/server.md#--oidc-group-field) | `oidc.groupField` | - | This field must be set if using the group sync feature and the scope name is not 'groups'. Set to the claim to be used for groups. | -| OIDC Group Mapping | `CODER_OIDC_GROUP_MAPPING` | [`--oidc-group-mapping`](../../reference/cli/server.md#--oidc-group-mapping) | `oidc.groupMapping` | `{}` | A map of OIDC group IDs and the group in Coder it should map to. This is useful for when OIDC providers only return group IDs. | -| OIDC Ignore Email Verified | `CODER_OIDC_IGNORE_EMAIL_VERIFIED` | [`--oidc-ignore-email-verified`](../../reference/cli/server.md#--oidc-ignore-email-verified) | `oidc.ignoreEmailVerified` | - | Ignore the email_verified claim from the upstream provider. | -| OIDC Ignore UserInfo | `CODER_OIDC_IGNORE_USERINFO` | [`--oidc-ignore-userinfo`](../../reference/cli/server.md#--oidc-ignore-userinfo) | `oidc.ignoreUserInfo` | `false` | Ignore the userinfo endpoint and only use the ID token for user information. | -| OIDC Issuer URL | `CODER_OIDC_ISSUER_URL` | [`--oidc-issuer-url`](../../reference/cli/server.md#--oidc-issuer-url) | `oidc.issuerURL` | - | Issuer URL to use for Login with OIDC. | -| OIDC Name Field | `CODER_OIDC_NAME_FIELD` | [`--oidc-name-field`](../../reference/cli/server.md#--oidc-name-field) | `oidc.nameField` | `name` | OIDC claim field to use as the name. | -| OIDC Regex Group Filter | `CODER_OIDC_GROUP_REGEX_FILTER` | [`--oidc-group-regex-filter`](../../reference/cli/server.md#--oidc-group-regex-filter) | `oidc.groupRegexFilter` | `.*` | If provided any group name not matching the regex is ignored. This allows for filtering out groups that are not needed. This filter is applied after the group mapping. | -| OIDC Scopes | `CODER_OIDC_SCOPES` | [`--oidc-scopes`](../../reference/cli/server.md#--oidc-scopes) | `oidc.scopes` | `openid,profile,email` | Scopes to grant when authenticating with OIDC. | -| OIDC User Role Default | `CODER_OIDC_USER_ROLE_DEFAULT` | [`--oidc-user-role-default`](../../reference/cli/server.md#--oidc-user-role-default) | `oidc.userRoleDefault` | - | If user role sync is enabled, these roles are always included for all authenticated users. The 'member' role is always assigned. | -| OIDC User Role Field | `CODER_OIDC_USER_ROLE_FIELD` | [`--oidc-user-role-field`](../../reference/cli/server.md#--oidc-user-role-field) | `oidc.userRoleField` | - | This field must be set if using the user roles sync feature. Set this to the name of the claim used to store the user's role. The roles should be sent as an array of strings. | -| OIDC User Role Mapping | `CODER_OIDC_USER_ROLE_MAPPING` | [`--oidc-user-role-mapping`](../../reference/cli/server.md#--oidc-user-role-mapping) | `oidc.userRoleMapping` | `{}` | A map of the OIDC passed in user roles and the groups in Coder it should map to. This is useful if the group names do not match. If mapped to the empty string, the role will ignored. | -| OIDC Username Field | `CODER_OIDC_USERNAME_FIELD` | [`--oidc-username-field`](../../reference/cli/server.md#--oidc-username-field) | `oidc.usernameField` | `preferred_username` | OIDC claim field to use as the username. | -| OpenID Connect sign in text | `CODER_OIDC_SIGN_IN_TEXT` | [`--oidc-sign-in-text`](../../reference/cli/server.md#--oidc-sign-in-text) | `oidc.signInText` | `OpenID Connect` | The text to show on the OpenID Connect sign in button. | -| OpenID connect icon URL | `CODER_OIDC_ICON_URL` | [`--oidc-icon-url`](../../reference/cli/server.md#--oidc-icon-url) | `oidc.iconURL` | - | URL pointing to the icon to use on the OpenID Connect login button. | -| Signups disabled text | `CODER_OIDC_SIGNUPS_DISABLED_TEXT` | [`--oidc-signups-disabled-text`](../../reference/cli/server.md#--oidc-signups-disabled-text) | `oidc.signupsDisabledText` | - | The custom text to show on the error page informing about disabled OIDC signups. Markdown format is supported. | -| Skip OIDC issuer checks (not recommended) | `CODER_DANGEROUS_OIDC_SKIP_ISSUER_CHECKS` | [`--dangerous-oidc-skip-issuer-checks`](../../reference/cli/server.md#--dangerous-oidc-skip-issuer-checks) | `oidc.dangerousSkipIssuerChecks` | - | OIDC issuer urls must match in the request, the id_token 'iss' claim, and in the well-known configuration. This flag disables that requirement, and can lead to an insecure OIDC configuration. It is not recommended to use this flag. | +### Enable OIDC group auto create + +Automatically creates missing groups from a user's groups claim. + +- Environment variable: `CODER_OIDC_GROUP_AUTO_CREATE` +- CLI flag: [`--oidc-group-auto-create`](../../reference/cli/server.md#--oidc-group-auto-create) +- YAML key: `oidc.enableGroupAutoCreate` +- Default value: `false` + +### Allow signups + +Whether new users can sign up with OIDC. + +- Environment variable: `CODER_OIDC_ALLOW_SIGNUPS` +- CLI flag: [`--oidc-allow-signups`](../../reference/cli/server.md#--oidc-allow-signups) +- YAML key: `oidc.allowSignups` +- Default value: `true` + +### Allowed groups + +If provided any group name not in the list will not be allowed to authenticate. This allows for restricting access to a specific set of groups. This filter is applied after the group mapping and before the regex filter. + +- Environment variable: `CODER_OIDC_ALLOWED_GROUPS` +- CLI flag: [`--oidc-allowed-groups`](../../reference/cli/server.md#--oidc-allowed-groups) +- YAML key: `oidc.groupAllowed` + +### Auth URL parameters + +OIDC auth URL parameters to pass to the upstream provider. + +- Environment variable: `CODER_OIDC_AUTH_URL_PARAMS` +- CLI flag: [`--oidc-auth-url-params`](../../reference/cli/server.md#--oidc-auth-url-params) +- YAML key: `oidc.authURLParams` +- Default value: `{"access_type": "offline"}` + +### Client cert file + +Pem encoded certificate file to use for oauth2 PKI/JWT authorization. The public certificate that accompanies oidc-client-key-file. A standard x509 certificate is expected. + +- Environment variable: `CODER_OIDC_CLIENT_CERT_FILE` +- CLI flag: [`--oidc-client-cert-file`](../../reference/cli/server.md#--oidc-client-cert-file) +- YAML key: `oidc.oidcClientCertFile` + +### Client ID + +Client ID to use for Login with OIDC. + +- Environment variable: `CODER_OIDC_CLIENT_ID` +- CLI flag: [`--oidc-client-id`](../../reference/cli/server.md#--oidc-client-id) +- YAML key: `oidc.clientID` + +### Client key file + +Pem encoded RSA private key to use for oauth2 PKI/JWT authorization. This can be used instead of oidc-client-secret if your IDP supports it. + +- Environment variable: `CODER_OIDC_CLIENT_KEY_FILE` +- CLI flag: [`--oidc-client-key-file`](../../reference/cli/server.md#--oidc-client-key-file) +- YAML key: `oidc.oidcClientKeyFile` + +### Client secret + +Client secret to use for Login with OIDC. + +- Environment variable: `CODER_OIDC_CLIENT_SECRET` +- CLI flag: [`--oidc-client-secret`](../../reference/cli/server.md#--oidc-client-secret) + +### Email domain + +Email domains that clients logging in with OIDC must match. + +- Environment variable: `CODER_OIDC_EMAIL_DOMAIN` +- CLI flag: [`--oidc-email-domain`](../../reference/cli/server.md#--oidc-email-domain) +- YAML key: `oidc.emailDomain` + +### Email field + +OIDC claim field to use as the email. + +- Environment variable: `CODER_OIDC_EMAIL_FIELD` +- CLI flag: [`--oidc-email-field`](../../reference/cli/server.md#--oidc-email-field) +- YAML key: `oidc.emailField` +- Default value: `email` + +### Group field + +This field must be set if using the group sync feature and the scope name is not 'groups'. Set to the claim to be used for groups. + +- Environment variable: `CODER_OIDC_GROUP_FIELD` +- CLI flag: [`--oidc-group-field`](../../reference/cli/server.md#--oidc-group-field) +- YAML key: `oidc.groupField` + +### Group mapping + +A map of OIDC group IDs and the group in Coder it should map to. This is useful for when OIDC providers only return group IDs. + +- Environment variable: `CODER_OIDC_GROUP_MAPPING` +- CLI flag: [`--oidc-group-mapping`](../../reference/cli/server.md#--oidc-group-mapping) +- YAML key: `oidc.groupMapping` +- Default value: `{}` + +### Ignore email verified + +Ignore the email_verified claim from the upstream provider. + +- Environment variable: `CODER_OIDC_IGNORE_EMAIL_VERIFIED` +- CLI flag: [`--oidc-ignore-email-verified`](../../reference/cli/server.md#--oidc-ignore-email-verified) +- YAML key: `oidc.ignoreEmailVerified` + +### Ignore UserInfo + +Ignore the userinfo endpoint and only use the ID token for user information. + +- Environment variable: `CODER_OIDC_IGNORE_USERINFO` +- CLI flag: [`--oidc-ignore-userinfo`](../../reference/cli/server.md#--oidc-ignore-userinfo) +- YAML key: `oidc.ignoreUserInfo` +- Default value: `false` + +### Issuer URL + +Issuer URL to use for Login with OIDC. + +- Environment variable: `CODER_OIDC_ISSUER_URL` +- CLI flag: [`--oidc-issuer-url`](../../reference/cli/server.md#--oidc-issuer-url) +- YAML key: `oidc.issuerURL` + +### Name field + +OIDC claim field to use as the name. + +- Environment variable: `CODER_OIDC_NAME_FIELD` +- CLI flag: [`--oidc-name-field`](../../reference/cli/server.md#--oidc-name-field) +- YAML key: `oidc.nameField` +- Default value: `name` + +### Regex group filter + +If provided any group name not matching the regex is ignored. This allows for filtering out groups that are not needed. This filter is applied after the group mapping. + +- Environment variable: `CODER_OIDC_GROUP_REGEX_FILTER` +- CLI flag: [`--oidc-group-regex-filter`](../../reference/cli/server.md#--oidc-group-regex-filter) +- YAML key: `oidc.groupRegexFilter` +- Default value: `.*` + +### Scopes + +Scopes to grant when authenticating with OIDC. + +- Environment variable: `CODER_OIDC_SCOPES` +- CLI flag: [`--oidc-scopes`](../../reference/cli/server.md#--oidc-scopes) +- YAML key: `oidc.scopes` +- Default value: `openid,profile,email` + +### User role default + +If user role sync is enabled, these roles are always included for all authenticated users. The 'member' role is always assigned. + +- Environment variable: `CODER_OIDC_USER_ROLE_DEFAULT` +- CLI flag: [`--oidc-user-role-default`](../../reference/cli/server.md#--oidc-user-role-default) +- YAML key: `oidc.userRoleDefault` + +### User role field + +This field must be set if using the user roles sync feature. Set this to the name of the claim used to store the user's role. The roles should be sent as an array of strings. + +- Environment variable: `CODER_OIDC_USER_ROLE_FIELD` +- CLI flag: [`--oidc-user-role-field`](../../reference/cli/server.md#--oidc-user-role-field) +- YAML key: `oidc.userRoleField` + +### User role mapping + +A map of the OIDC passed in user roles and the groups in Coder it should map to. This is useful if the group names do not match. If mapped to the empty string, the role will ignored. + +- Environment variable: `CODER_OIDC_USER_ROLE_MAPPING` +- CLI flag: [`--oidc-user-role-mapping`](../../reference/cli/server.md#--oidc-user-role-mapping) +- YAML key: `oidc.userRoleMapping` +- Default value: `{}` + +### Username field + +OIDC claim field to use as the username. + +- Environment variable: `CODER_OIDC_USERNAME_FIELD` +- CLI flag: [`--oidc-username-field`](../../reference/cli/server.md#--oidc-username-field) +- YAML key: `oidc.usernameField` +- Default value: `preferred_username` + +### OpenID connect sign in text + +The text to show on the OpenID Connect sign in button. + +- Environment variable: `CODER_OIDC_SIGN_IN_TEXT` +- CLI flag: [`--oidc-sign-in-text`](../../reference/cli/server.md#--oidc-sign-in-text) +- YAML key: `oidc.signInText` +- Default value: `OpenID Connect` + +### OpenID connect icon URL + +URL pointing to the icon to use on the OpenID Connect login button. + +- Environment variable: `CODER_OIDC_ICON_URL` +- CLI flag: [`--oidc-icon-url`](../../reference/cli/server.md#--oidc-icon-url) +- YAML key: `oidc.iconURL` + +### Signups disabled text + +The custom text to show on the error page informing about disabled OIDC signups. Markdown format is supported. + +- Environment variable: `CODER_OIDC_SIGNUPS_DISABLED_TEXT` +- CLI flag: [`--oidc-signups-disabled-text`](../../reference/cli/server.md#--oidc-signups-disabled-text) +- YAML key: `oidc.signupsDisabledText` + +### Skip OIDC issuer checks (not recommended) + +OIDC issuer urls must match in the request, the id_token 'iss' claim, and in the well-known configuration. This flag disables that requirement, and can lead to an insecure OIDC configuration. It is not recommended to use this flag. + +- Environment variable: `CODER_DANGEROUS_OIDC_SKIP_ISSUER_CHECKS` +- CLI flag: [`--dangerous-oidc-skip-issuer-checks`](../../reference/cli/server.md#--dangerous-oidc-skip-issuer-checks) +- YAML key: `oidc.dangerousSkipIssuerChecks` ## Provisioning -| Setting | Env var | Flag | YAML | Default | Description | -|-----------------------------------------|-------------------------------------------|------------------------------------------------------------------------------------------------------------|------------------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------| -| Force Cancel Interval | `CODER_PROVISIONER_FORCE_CANCEL_INTERVAL` | [`--provisioner-force-cancel-interval`](../../reference/cli/server.md#--provisioner-force-cancel-interval) | `provisioning.forceCancelInterval` | `10m0s` | Time to force cancel provisioning tasks that are stuck. | -| Poll Interval | `CODER_PROVISIONER_DAEMON_POLL_INTERVAL` | [`--provisioner-daemon-poll-interval`](../../reference/cli/server.md#--provisioner-daemon-poll-interval) | `provisioning.daemonPollInterval` | `1s` | Deprecated and ignored. | -| Poll Jitter | `CODER_PROVISIONER_DAEMON_POLL_JITTER` | [`--provisioner-daemon-poll-jitter`](../../reference/cli/server.md#--provisioner-daemon-poll-jitter) | `provisioning.daemonPollJitter` | `100ms` | Deprecated and ignored. | -| Provisioner Daemon Pre-shared Key (PSK) | `CODER_PROVISIONER_DAEMON_PSK` | [`--provisioner-daemon-psk`](../../reference/cli/server.md#--provisioner-daemon-psk) | - | - | Pre-shared key to authenticate external provisioner daemons to Coder server. | -| Provisioner Daemons | `CODER_PROVISIONER_DAEMONS` | [`--provisioner-daemons`](../../reference/cli/server.md#--provisioner-daemons) | `provisioning.daemons` | `3` | Number of provisioner daemons to create on start. If builds are stuck in queued state for a long time, consider increasing this. | +Tune the behavior of the provisioner, which is responsible for creating, updating, and deleting workspace resources. + +### Force cancel interval + +Time to force cancel provisioning tasks that are stuck. + +- Environment variable: `CODER_PROVISIONER_FORCE_CANCEL_INTERVAL` +- CLI flag: [`--provisioner-force-cancel-interval`](../../reference/cli/server.md#--provisioner-force-cancel-interval) +- YAML key: `provisioning.forceCancelInterval` +- Default value: `10m0s` + +### Provisioner daemon pre-shared key (PSK) + +Pre-shared key to authenticate external provisioner daemons to Coder server. + +- Environment variable: `CODER_PROVISIONER_DAEMON_PSK` +- CLI flag: [`--provisioner-daemon-psk`](../../reference/cli/server.md#--provisioner-daemon-psk) + +### Provisioner daemons + +Number of provisioner daemons to create on start. If builds are stuck in queued state for a long time, consider increasing this. + +- Environment variable: `CODER_PROVISIONER_DAEMONS` +- CLI flag: [`--provisioner-daemons`](../../reference/cli/server.md#--provisioner-daemons) +- YAML key: `provisioning.daemons` +- Default value: `3` + +### Poll interval + +**Deprecated** and ignored. + +- Environment variable: `CODER_PROVISIONER_DAEMON_POLL_INTERVAL` +- CLI flag: [`--provisioner-daemon-poll-interval`](../../reference/cli/server.md#--provisioner-daemon-poll-interval) +- YAML key: `provisioning.daemonPollInterval` +- Default value: `1s` + +### Poll jitter + +**Deprecated** and ignored. + +- Environment variable: `CODER_PROVISIONER_DAEMON_POLL_JITTER` +- CLI flag: [`--provisioner-daemon-poll-jitter`](../../reference/cli/server.md#--provisioner-daemon-poll-jitter) +- YAML key: `provisioning.daemonPollJitter` +- Default value: `100ms` ## Retention -| Setting | Env var | Flag | YAML | Default | Description | -|--------------------------------|----------------------------------------|------------------------------------------------------------------------------------------------------|----------------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| API Keys Retention | `CODER_API_KEYS_RETENTION` | [`--api-keys-retention`](../../reference/cli/server.md#--api-keys-retention) | `retention.api_keys` | `7d` | How long expired API keys are retained before being deleted. Keeping expired keys allows the backend to return a more helpful error when a user tries to use an expired key. Set to 0 to disable automatic deletion of expired keys. | -| Audit Logs Retention | `CODER_AUDIT_LOGS_RETENTION` | [`--audit-logs-retention`](../../reference/cli/server.md#--audit-logs-retention) | `retention.audit_logs` | `0` | How long audit log entries are retained. Set to 0 to disable (keep indefinitely). We advise keeping audit logs for at least a year, and in accordance with your compliance requirements. | -| Boundary Log Retention | `CODER_BOUNDARY_LOG_RETENTION` | [`--boundary-log-retention`](../../reference/cli/server.md#--boundary-log-retention) | `retention.boundary_logs` | `0` | How long boundary audit log entries are retained. Boundary logs record HTTP requests processed by a Boundary confinement proxy. Set to 0 to disable automatic deletion (keep indefinitely). Adjust to match your organization's regulatory requirements. | -| Connection Logs Retention | `CODER_CONNECTION_LOGS_RETENTION` | [`--connection-logs-retention`](../../reference/cli/server.md#--connection-logs-retention) | `retention.connection_logs` | `0` | How long connection log entries are retained. Set to 0 to disable (keep indefinitely). | -| Workspace Agent Logs Retention | `CODER_WORKSPACE_AGENT_LOGS_RETENTION` | [`--workspace-agent-logs-retention`](../../reference/cli/server.md#--workspace-agent-logs-retention) | `retention.workspace_agent_logs` | `7d` | How long workspace agent logs are retained. Logs from non-latest builds are deleted if the agent hasn't connected within this period. Logs from the latest build are always retained. Set to 0 to disable automatic deletion. | +Configure data retention policies for various database tables. Retention policies automatically purge old data to reduce database size and improve performance. Setting a retention duration to 0 disables automatic purging for that data type. + +### API keys retention + +How long expired API keys are retained before being deleted. Keeping expired keys allows the backend to return a more helpful error when a user tries to use an expired key. Set to 0 to disable automatic deletion of expired keys. + +- Environment variable: `CODER_API_KEYS_RETENTION` +- CLI flag: [`--api-keys-retention`](../../reference/cli/server.md#--api-keys-retention) +- YAML key: `retention.api_keys` +- Default value: `7d` + +### Audit logs retention + +How long audit log entries are retained. Set to 0 to disable (keep indefinitely). We advise keeping audit logs for at least a year, and in accordance with your compliance requirements. + +- Environment variable: `CODER_AUDIT_LOGS_RETENTION` +- CLI flag: [`--audit-logs-retention`](../../reference/cli/server.md#--audit-logs-retention) +- YAML key: `retention.audit_logs` +- Default value: `0` + +### Boundary log retention + +How long boundary audit log entries are retained. Boundary logs record HTTP requests processed by a Boundary confinement proxy. Set to 0 to disable automatic deletion (keep indefinitely). Adjust to match your organization's regulatory requirements. + +- Environment variable: `CODER_BOUNDARY_LOG_RETENTION` +- CLI flag: [`--boundary-log-retention`](../../reference/cli/server.md#--boundary-log-retention) +- YAML key: `retention.boundary_logs` +- Default value: `0` + +### Connection logs retention + +How long connection log entries are retained. Set to 0 to disable (keep indefinitely). + +- Environment variable: `CODER_CONNECTION_LOGS_RETENTION` +- CLI flag: [`--connection-logs-retention`](../../reference/cli/server.md#--connection-logs-retention) +- YAML key: `retention.connection_logs` +- Default value: `0` + +### Workspace agent logs retention + +How long workspace agent logs are retained. Logs from non-latest builds are deleted if the agent hasn't connected within this period. Logs from the latest build are always retained. Set to 0 to disable automatic deletion. + +- Environment variable: `CODER_WORKSPACE_AGENT_LOGS_RETENTION` +- CLI flag: [`--workspace-agent-logs-retention`](../../reference/cli/server.md#--workspace-agent-logs-retention) +- YAML key: `retention.workspace_agent_logs` +- Default value: `7d` ## Telemetry -| Setting | Env var | Flag | YAML | Default | Description | -|------------------|--------------------------|------------------------------------------------------------|--------------------|---------|--------------------------------------------------------------------------------------------------------| -| Telemetry Enable | `CODER_TELEMETRY_ENABLE` | [`--telemetry`](../../reference/cli/server.md#--telemetry) | `telemetry.enable` | `true` | Whether telemetry is enabled or not. Coder collects anonymized usage data to help improve our product. | +Telemetry is critical to our ability to improve Coder. We strip all personal information before sending data to our servers. Please only disable telemetry when required by your organization's security policy. + +### Enable + +Whether telemetry is enabled or not. Coder collects anonymized usage data to help improve our product. + +- Environment variable: `CODER_TELEMETRY_ENABLE` +- CLI flag: [`--telemetry`](../../reference/cli/server.md#--telemetry) +- YAML key: `telemetry.enable` +- Default value: `true` + +## Template builder + +### Disable template builder + +Disable the template builder feature for guided template creation. When disabled, all /api/v2/templatebuilder/* endpoints return 404. -## Template Builder +- Environment variable: `CODER_DISABLE_TEMPLATE_BUILDER` +- CLI flag: [`--disable-template-builder`](../../reference/cli/server.md#--disable-template-builder) +- YAML key: `templateBuilder.disabled` -| Setting | Env var | Flag | YAML | Default | Description | -|-------------------------------|---------------------------------------|----------------------------------------------------------------------------------------------------|-------------------------------|----------------------|---------------------------------------------------------------------------------------------------------------------------------------| -| Disable Template Builder | `CODER_DISABLE_TEMPLATE_BUILDER` | [`--disable-template-builder`](../../reference/cli/server.md#--disable-template-builder) | `templateBuilder.disabled` | - | Disable the template builder feature for guided template creation. When disabled, all /api/v2/templatebuilder/* endpoints return 404. | -| Template Builder Registry URL | `CODER_TEMPLATE_BUILDER_REGISTRY_URL` | [`--template-builder-registry-url`](../../reference/cli/server.md#--template-builder-registry-url) | `templateBuilder.registryURL` | `registry.coder.com` | The base URL of the module registry used by the template builder for module source paths. | +### Registry URL -## User Quiet Hours Schedule +The base URL of the module registry used by the template builder for module source paths. -| Setting | Env var | Flag | YAML | Default | Description | -|------------------------------|--------------------------------------|--------------------------------------------------------------------------------------------------|----------------------------------------------------|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Allow Custom Quiet Hours | `CODER_ALLOW_CUSTOM_QUIET_HOURS` | [`--allow-custom-quiet-hours`](../../reference/cli/server.md#--allow-custom-quiet-hours) | `userQuietHoursSchedule.allowCustomQuietHours` | `true` | Allow users to set their own quiet hours schedule for workspaces to stop in (depending on template autostop requirement settings). If false, users can't change their quiet hours schedule and the site default is always used. | -| Default Quiet Hours Schedule | `CODER_QUIET_HOURS_DEFAULT_SCHEDULE` | [`--default-quiet-hours-schedule`](../../reference/cli/server.md#--default-quiet-hours-schedule) | `userQuietHoursSchedule.defaultQuietHoursSchedule` | `CRON_TZ=UTC 0 0 * * *` | The default daily cron schedule applied to users that haven't set a custom quiet hours schedule themselves. The quiet hours schedule determines when workspaces will be force stopped due to the template's autostop requirement, and will round the max deadline up to be within the user's quiet hours window (or default). The format is the same as the standard cron format, but the day-of-month, month and day-of-week must be *. Only one hour and minute can be specified (ranges or comma separated values are not supported). | +- Environment variable: `CODER_TEMPLATE_BUILDER_REGISTRY_URL` +- CLI flag: [`--template-builder-registry-url`](../../reference/cli/server.md#--template-builder-registry-url) +- YAML key: `templateBuilder.registryURL` +- Default value: `registry.coder.com` -## Workspace Prebuilds +## User quiet hours schedule -| Setting | Env var | Flag | YAML | Default | Description | -|-------------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|---------|---------------------------------------------------| -| Reconciliation Interval | `CODER_WORKSPACE_PREBUILDS_RECONCILIATION_INTERVAL` | [`--workspace-prebuilds-reconciliation-interval`](../../reference/cli/server.md#--workspace-prebuilds-reconciliation-interval) | `workspace_prebuilds.reconciliation_interval` | `1m0s` | How often to reconcile workspace prebuilds state. | +Allow users to set quiet hours schedules each day for workspaces to avoid workspaces stopping during the day due to template scheduling. + +### Allow custom quiet hours + +Allow users to set their own quiet hours schedule for workspaces to stop in (depending on template autostop requirement settings). If false, users can't change their quiet hours schedule and the site default is always used. + +- Environment variable: `CODER_ALLOW_CUSTOM_QUIET_HOURS` +- CLI flag: [`--allow-custom-quiet-hours`](../../reference/cli/server.md#--allow-custom-quiet-hours) +- YAML key: `userQuietHoursSchedule.allowCustomQuietHours` +- Default value: `true` + +### Default quiet hours schedule + +The default daily cron schedule applied to users that haven't set a custom quiet hours schedule themselves. The quiet hours schedule determines when workspaces will be force stopped due to the template's autostop requirement, and will round the max deadline up to be within the user's quiet hours window (or default). The format is the same as the standard cron format, but the day-of-month, month and day-of-week must be *. Only one hour and minute can be specified (ranges or comma separated values are not supported). + +- Environment variable: `CODER_QUIET_HOURS_DEFAULT_SCHEDULE` +- CLI flag: [`--default-quiet-hours-schedule`](../../reference/cli/server.md#--default-quiet-hours-schedule) +- YAML key: `userQuietHoursSchedule.defaultQuietHoursSchedule` +- Default value: `CRON_TZ=UTC 0 0 * * *` + +## Workspace prebuilds + +Configure how workspace prebuilds behave. + +### Reconciliation interval + +How often to reconcile workspace prebuilds state. + +- Environment variable: `CODER_WORKSPACE_PREBUILDS_RECONCILIATION_INTERVAL` +- CLI flag: [`--workspace-prebuilds-reconciliation-interval`](../../reference/cli/server.md#--workspace-prebuilds-reconciliation-interval) +- YAML key: `workspace_prebuilds.reconciliation_interval` +- Default value: `1m0s` ## ⚠️ Dangerous -| Setting | Env var | Flag | YAML | Default | Description | -|--------------------------------------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| DANGEROUS: Allow Path App Sharing | `CODER_DANGEROUS_ALLOW_PATH_APP_SHARING` | [`--dangerous-allow-path-app-sharing`](../../reference/cli/server.md#--dangerous-allow-path-app-sharing) | - | - | Allow workspace apps that are not served from subdomains to be shared. Path-based app sharing is DISABLED by default for security purposes. Path-based apps can make requests to the Coder API and pose a security risk when the workspace serves malicious JavaScript. Path-based apps can be disabled entirely with --disable-path-apps for further security. | -| DANGEROUS: Allow Site Owners to Access Path Apps | `CODER_DANGEROUS_ALLOW_PATH_APP_SITE_OWNER_ACCESS` | [`--dangerous-allow-path-app-site-owner-access`](../../reference/cli/server.md#--dangerous-allow-path-app-site-owner-access) | - | - | Allow site-owners to access workspace apps from workspaces they do not own. Owners cannot access path-based apps they do not own by default. Path-based apps can make requests to the Coder API and pose a security risk when the workspace serves malicious JavaScript. Path-based apps can be disabled entirely with --disable-path-apps for further security. | +### Allow path app sharing + +Allow workspace apps that are not served from subdomains to be shared. Path-based app sharing is DISABLED by default for security purposes. Path-based apps can make requests to the Coder API and pose a security risk when the workspace serves malicious JavaScript. Path-based apps can be disabled entirely with --disable-path-apps for further security. + +- Environment variable: `CODER_DANGEROUS_ALLOW_PATH_APP_SHARING` +- CLI flag: [`--dangerous-allow-path-app-sharing`](../../reference/cli/server.md#--dangerous-allow-path-app-sharing) + +### Allow site owners to access path apps + +Allow site-owners to access workspace apps from workspaces they do not own. Owners cannot access path-based apps they do not own by default. Path-based apps can make requests to the Coder API and pose a security risk when the workspace serves malicious JavaScript. Path-based apps can be disabled entirely with --disable-path-apps for further security. + +- Environment variable: `CODER_DANGEROUS_ALLOW_PATH_APP_SITE_OWNER_ACCESS` +- CLI flag: [`--dangerous-allow-path-app-site-owner-access`](../../reference/cli/server.md#--dangerous-allow-path-app-site-owner-access) diff --git a/scripts/configdocgen/main.go b/scripts/configdocgen/main.go index 557dba000d058..74aaf2b53ef07 100644 --- a/scripts/configdocgen/main.go +++ b/scripts/configdocgen/main.go @@ -1,8 +1,10 @@ // Command configdocgen generates the Coder server configuration reference at // docs/admin/setup/configuration-reference.md from codersdk.DeploymentValues. -// It lists every visible deployment option grouped by serpent group, with its -// environment variable, CLI flag, YAML key, and default. Because the source is -// DeploymentValues, the page stays in sync as options change. +// It lists every visible deployment option grouped by serpent group. Each +// option is rendered as a heading with its description followed by the +// environment variable, CLI flag, YAML key, and default that apply to it. +// Because the source is DeploymentValues, the page stays in sync as options +// change. package main import ( @@ -12,6 +14,7 @@ import ( "os" "slices" "strings" + "unicode" "github.com/coder/coder/v2/codersdk" "github.com/coder/coder/v2/scripts/atomicwrite" @@ -27,8 +30,8 @@ lists every option so you can search by environment variable name, CLI flag, or YAML key. For first-time setup guidance and worked examples, see [Configure Control Plane Access](./index.md). -Most options can be set through any of the following. Where a method does not -apply to an option, that column shows ` + "`-`" + `. +Each option can be set through one or more of the methods below. An option lists +only the methods that apply to it. - An environment variable (recommended for production deployments running as a system service, container, or Helm chart). @@ -36,25 +39,52 @@ apply to an option, that column shows ` + "`-`" + `. and local development). - A key in a YAML configuration file passed with ` + "`--config`" + `. -For a full description of each option's accepted values and behavior, follow -the flag link into [` + "`coder server`" + ` CLI reference](../../reference/cli/server.md). +For a full description of each option's accepted values and behavior, follow the +flag link into the [` + "`coder server`" + ` CLI reference](../../reference/cli/server.md). + +Deprecated options are listed at the end of each section. ` -// row carries the rendered cells for one option. -type row struct { - name string - env string - flag string - yaml string - defValue string - desc string +// generalSection holds options that do not belong to a serpent group. +const generalSection = "General" + +// option is the normalized data needed to render one deployment option. +type option struct { + title string // short, sentence-case heading text + env string + flagName string + flagAnchor string + yaml string + defValue string + desc string + deprecated bool + sortKey string // original serpent name, for stable ordering +} + +// node is one section of the reference: a serpent group (or the synthetic +// "General" group) with its direct options and any child sections. +type node struct { + name string // raw group name (leaf); sentence-cased at render time + intro string // group description, if any + options []option + children []*node + childIdx map[string]*node } -// section is one heading level of options, grouped by serpent.Group. -type section struct { - title string - rows []row +func newNode(name string) *node { + return &node{name: name, childIdx: map[string]*node{}} +} + +// child returns the named child section, creating it on first use. +func (n *node) child(name string) *node { + if c, ok := n.childIdx[name]; ok { + return c + } + c := newNode(name) + n.childIdx[name] = c + n.children = append(n.children, c) + return c } // prepareEnv mirrors scripts/clidocgen so the generated defaults do not @@ -93,22 +123,22 @@ func main() { var vals codersdk.DeploymentValues opts := vals.Options() - sections := buildSections(opts) - body := renderSections(sections) + root := buildTree(opts) + body := render(root) - if err := atomicwrite.File(*out, []byte(header+body)); err != nil { + content := header + body + content = strings.TrimRight(content, "\n") + "\n" + if err := atomicwrite.File(*out, []byte(content)); err != nil { flog.Fatalf("write %s: %v", *out, err) } flog.Successf("wrote %s", *out) } -// buildSections groups options by their serpent group, skipping hidden -// options and options that have no environment variable, flag, or YAML key -// (those cannot be set by an operator). -func buildSections(opts serpent.OptionSet) []section { - bySection := map[string]*section{} - var order []string - +// buildTree groups options into a section tree, skipping hidden options and +// options that have no environment variable, flag, or YAML key (those cannot +// be set by an operator). +func buildTree(opts serpent.OptionSet) *node { + root := newNode("") for _, opt := range opts { if opt.Hidden { continue @@ -116,128 +146,333 @@ func buildSections(opts serpent.OptionSet) []section { if opt.Env == "" && opt.Flag == "" && opt.YAML == "" { continue } + sec := sectionFor(root, opt.Group) + sec.options = append(sec.options, toOption(opt)) + } + sortTree(root) + return root +} - title := "General" - if opt.Group != nil { - full := opt.Group.FullName() - if full != "" { - title = full - } +// sectionFor returns the section node for an option's group, creating the +// chain of ancestor sections as needed. Options with no group (or an unnamed +// group) live in the General section. +func sectionFor(root *node, g *serpent.Group) *node { + if g == nil { + return root.child(generalSection) + } + cur := root + for _, anc := range g.Ancestry() { + if anc.Name == "" { + return root.child(generalSection) } - if _, ok := bySection[title]; !ok { - bySection[title] = §ion{title: title} - order = append(order, title) + cur = cur.child(anc.Name) + if cur.intro == "" { + cur.intro = collapse(anc.Description) } - bySection[title].rows = append(bySection[title].rows, optionToRow(opt)) } + return cur +} - for _, key := range order { - slices.SortFunc(bySection[key].rows, func(a, b row) int { - return strings.Compare(a.name, b.name) - }) +func toOption(opt serpent.Option) option { + var flagName, flagAnchor string + if opt.Flag != "" { + flagName = "--" + opt.Flag + // clidocgen renders a flag heading as "### -s, --flag" when it has a + // shorthand and "### --flag" otherwise, so the anchor must include the + // shorthand to match. + flagAnchor = "--" + opt.Flag + if opt.FlagShorthand != "" { + flagAnchor = "-" + opt.FlagShorthand + "---" + opt.Flag + } } - slices.SortStableFunc(order, func(a, b string) int { - if c := cmp.Compare(sectionRank(a), sectionRank(b)); c != 0 { + def := opt.Default + if def == "" && opt.DefaultFn != nil { + // DefaultFn results depend on the host environment, so evaluating them + // here would leak host-specific values. Send the reader to the CLI + // reference for the resolved default instead. + def = "(computed at runtime)" + } + + return option{ + title: shortTitle(opt), + env: opt.Env, + flagName: flagName, + flagAnchor: flagAnchor, + yaml: opt.YAMLPath(), + defValue: def, + desc: collapse(opt.Description), + deprecated: isDeprecated(opt), + sortKey: opt.Name, + } +} + +// isDeprecated reports whether an option is deprecated. serpent tracks +// replacements in UseInstead, and codersdk also marks some options by leading +// the description with "Deprecated". +func isDeprecated(opt serpent.Option) bool { + if len(opt.UseInstead) > 0 { + return true + } + return strings.HasPrefix(strings.ToLower(strings.TrimSpace(opt.Description)), "deprecated") +} + +// sortTree orders sections and their options. General sorts first and +// Dangerous last among top-level sections; every other section is +// alphabetical. Within a section, active options come before deprecated ones, +// each alphabetical by their original name. +func sortTree(n *node) { + slices.SortStableFunc(n.children, func(a, b *node) int { + if c := cmp.Compare(sectionRank(a.name), sectionRank(b.name)); c != 0 { return c } - return strings.Compare(a, b) + return strings.Compare(a.name, b.name) }) - - result := make([]section, 0, len(order)) - for _, key := range order { - result = append(result, *bySection[key]) + for _, c := range n.children { + slices.SortStableFunc(c.options, func(a, b option) int { + if a.deprecated != b.deprecated { + if a.deprecated { + return 1 + } + return -1 + } + return strings.Compare(a.sortKey, b.sortKey) + }) + sortTree(c) } - return result } -// sectionRank fixes the display order of sections. General comes first because -// it holds the most common first-time setup options (Postgres, cache -// directory, access URL). The Dangerous group comes last, regardless of its -// emoji prefix, so the reference does not steer operators toward risky +// sectionRank fixes the display order of top-level sections. General comes +// first because it holds the most common first-time setup options (Postgres, +// cache directory, access URL). The Dangerous group comes last, regardless of +// its emoji prefix, so the reference does not steer operators toward risky // settings. Every other section sorts alphabetically between them. -func sectionRank(title string) int { +func sectionRank(name string) int { switch { - case title == "General": + case name == generalSection: return -1 - case strings.HasSuffix(title, "Dangerous"): + case strings.HasSuffix(name, "Dangerous"): return 1 default: return 0 } } -func optionToRow(opt serpent.Option) row { - flagCell := "-" - if opt.Flag != "" { - // clidocgen renders a flag heading as "### -s, --flag" when it has a - // shorthand and "### --flag" otherwise, so the anchor must include the - // shorthand to match. - anchor := "--" + opt.Flag - if opt.FlagShorthand != "" { - anchor = "-" + opt.FlagShorthand + "---" + opt.Flag +func render(root *node) string { + var b strings.Builder + for _, sec := range root.children { + renderNode(&b, sec, 2) + } + return b.String() +} + +func renderNode(b *strings.Builder, n *node, level int) { + _, _ = fmt.Fprintf(b, "%s %s\n\n", strings.Repeat("#", level), sentenceCase(n.name)) + if n.intro != "" { + _, _ = b.WriteString(n.intro) + _, _ = b.WriteString("\n\n") + } + for _, opt := range n.options { + renderOption(b, opt, level+1) + } + for _, c := range n.children { + renderNode(b, c, level+1) + } +} + +func renderOption(b *strings.Builder, opt option, level int) { + _, _ = fmt.Fprintf(b, "%s %s\n\n", strings.Repeat("#", level), opt.title) + + desc := opt.desc + if opt.deprecated { + desc = emphasizeDeprecation(desc) + } + if desc != "" { + _, _ = b.WriteString(desc) + _, _ = b.WriteString("\n\n") + } + + if opt.env != "" { + _, _ = fmt.Fprintf(b, "- Environment variable: `%s`\n", opt.env) + } + if opt.flagName != "" { + _, _ = fmt.Fprintf(b, "- CLI flag: [`%s`](../../reference/cli/server.md#%s)\n", opt.flagName, opt.flagAnchor) + } + if opt.yaml != "" { + _, _ = fmt.Fprintf(b, "- YAML key: `%s`\n", opt.yaml) + } + if opt.defValue != "" { + _, _ = fmt.Fprintf(b, "- Default value: `%s`\n", opt.defValue) + } + _, _ = b.WriteString("\n") +} + +// emphasizeDeprecation bolds the leading "Deprecated" marker in a description +// so a deprecated option reads clearly. Trailing text is left unbolded so the +// paragraph is not a lone emphasis span (markdownlint MD036). +func emphasizeDeprecation(desc string) string { + const marker = "Deprecated" + if len(desc) >= len(marker) && strings.EqualFold(desc[:len(marker)], marker) { + if strings.TrimSpace(desc[len(marker):]) != "" { + return "**" + desc[:len(marker)] + "**" + desc[len(marker):] } - flagCell = fmt.Sprintf("[`--%s`](../../reference/cli/server.md#%s)", opt.Flag, anchor) + return desc + } + if desc == "" { + return "Deprecated." } + return "**Deprecated.** " + desc +} - def := opt.Default - if def == "" && opt.DefaultFn != nil { - // DefaultFn results depend on the host environment, so evaluating them - // here would leak host-specific values. Send the reader to the CLI - // reference for the resolved default instead. - def = "(computed at runtime)" +// shortTitle strips the redundant group prefix from an option name and returns +// it in sentence case, e.g. "AI Gateway Send Actor Headers" becomes +// "Send actor headers". +func shortTitle(opt serpent.Option) string { + name := opt.Name + if opt.Group != nil { + name = stripGroupPrefix(name, opt.Group) + } + return sentenceCase(name) +} + +// stripGroupPrefix removes the group name that many option names repeat. For +// space-prefixed names like "AI Gateway Send Actor Headers" it drops the +// longest matching ancestor chain ("AI Gateway"). For colon-prefixed names +// like "Notifications: Email TLS: StartTLS" it drops every segment up to the +// last ": " once the leading segment belongs to the top-level group. Names +// that do not repeat the group are returned unchanged. +func stripGroupPrefix(name string, g *serpent.Group) string { + anc := g.Ancestry() + if len(anc) == 0 { + return name + } + names := make([]string, len(anc)) + for i, a := range anc { + names[i] = a.Name + } + + if before, _, ok := strings.Cut(name, ": "); ok { + // Only treat the colon as a group separator when the leading segment + // belongs to the top-level group. This avoids mangling meaningful + // colons such as "Health Check Threshold: Database". + if top := normalize(names[0]); top != "" && strings.HasPrefix(normalize(before), top) { + if idx := strings.LastIndex(name, ": "); idx >= 0 { + if rest := strings.TrimSpace(name[idx+len(": "):]); rest != "" { + return rest + } + } + } } - return row{ - name: escapePipe(opt.Name), - env: codeCell(opt.Env), - flag: flagCell, - yaml: codeCell(opt.YAMLPath()), - defValue: codeCell(def), - desc: sanitizeDesc(opt.Description), + // Try the longest ancestor suffix chain first (start == 0 is the full + // path) so the most specific prefix wins. + for start := range names { + prefix := strings.Join(names[start:], " ") + " " + if rest, ok := cutFold(name, prefix); ok { + if rest = strings.TrimSpace(rest); rest != "" { + return rest + } + } } + return name +} + +// properNoun lists words that keep their capitalization in sentence case. +// They have ordinary title-case shape, so keepWord's acronym check would not +// otherwise catch them. +var properNoun = map[string]bool{ + "anthropic": true, + "bedrock": true, + "claude": true, + "coder": true, + "google": true, + "helm": true, + "honeycomb": true, + "maven": true, + "postgres": true, + "prometheus": true, + "stackdriver": true, + "tailscale": true, + "terraform": true, + "wireguard": true, } -func codeCell(s string) string { - if s == "" { - return "-" +// sentenceCase lowercases a heading's words after the first while preserving +// the first word, acronyms and mixed-case tokens (URL, TLS, OAuth2, OpenID, +// GitHub), and known proper nouns. It runs at generation time so headings need +// no manual or AI pass. +func sentenceCase(s string) string { + words := strings.Fields(s) + seenFirst := false + for i, w := range words { + if !seenFirst { + // Keep any leading symbols (e.g. an emoji) and the first real word. + if hasLetter(w) { + seenFirst = true + } + continue + } + if !keepWord(w) { + words[i] = strings.ToLower(w) + } } - return "`" + s + "`" + return strings.Join(words, " ") } -// sanitizeDesc collapses whitespace and escapes pipes so a description renders -// inside a single markdown table cell. -func sanitizeDesc(s string) string { - s = strings.TrimSpace(s) - s = strings.ReplaceAll(s, "\n", " ") - s = strings.ReplaceAll(s, "\r", " ") - for strings.Contains(s, " ") { - s = strings.ReplaceAll(s, " ", " ") +// keepWord reports whether a word must keep its capitalization: proper nouns, +// all-caps or mixed-case acronyms (URL, GitHub), and tokens with digits +// (OAuth2). +func keepWord(w string) bool { + core := strings.Trim(w, "()[]{}:;,.\"'") + if core == "" { + return true + } + if properNoun[strings.ToLower(core)] { + return true + } + for i, r := range core { + if i == 0 { + continue + } + if unicode.IsUpper(r) || unicode.IsDigit(r) { + return true + } } - s = escapePipe(s) - if s == "" { - return "-" + return false +} + +func hasLetter(s string) bool { + for _, r := range s { + if unicode.IsLetter(r) { + return true + } } - return s + return false } -// escapePipe escapes the markdown table cell delimiter so a value cannot break -// the surrounding row. -func escapePipe(s string) string { - return strings.ReplaceAll(s, "|", `\|`) +// collapse trims a string and collapses internal runs of whitespace to a +// single space so multi-line source text renders as one paragraph. +func collapse(s string) string { + return strings.Join(strings.Fields(s), " ") } -func renderSections(sections []section) string { +// normalize lowercases a string and drops everything but letters and digits, +// so prefixes can be compared regardless of spacing, case, or punctuation. +func normalize(s string) string { var b strings.Builder - for _, sec := range sections { - _, _ = fmt.Fprintf(&b, "## %s\n\n", sec.title) - _, _ = b.WriteString("| Setting | Env var | Flag | YAML | Default | Description |\n") - _, _ = b.WriteString("|---|---|---|---|---|---|\n") - for _, r := range sec.rows { - _, _ = fmt.Fprintf(&b, "| %s | %s | %s | %s | %s | %s |\n", - r.name, r.env, r.flag, r.yaml, r.defValue, r.desc) + for _, r := range s { + if unicode.IsLetter(r) || unicode.IsDigit(r) { + _, _ = b.WriteRune(unicode.ToLower(r)) } - _, _ = b.WriteString("\n") } return b.String() } + +// cutFold trims prefix from s using a case-insensitive comparison, reporting +// whether it was present. +func cutFold(s, prefix string) (string, bool) { + if len(s) >= len(prefix) && strings.EqualFold(s[:len(prefix)], prefix) { + return s[len(prefix):], true + } + return s, false +} From 3b2c0f5cb7fd0c494b0466e1f26162530ee2a7fb Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Wed, 8 Jul 2026 17:05:53 +0000 Subject: [PATCH 07/13] chore(scripts/configdocgen): rename ancestry vars to satisfy typos linter --- scripts/configdocgen/main.go | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/scripts/configdocgen/main.go b/scripts/configdocgen/main.go index 74aaf2b53ef07..a03b76145c068 100644 --- a/scripts/configdocgen/main.go +++ b/scripts/configdocgen/main.go @@ -161,13 +161,13 @@ func sectionFor(root *node, g *serpent.Group) *node { return root.child(generalSection) } cur := root - for _, anc := range g.Ancestry() { - if anc.Name == "" { + for _, ancestor := range g.Ancestry() { + if ancestor.Name == "" { return root.child(generalSection) } - cur = cur.child(anc.Name) + cur = cur.child(ancestor.Name) if cur.intro == "" { - cur.intro = collapse(anc.Description) + cur.intro = collapse(ancestor.Description) } } return cur @@ -342,12 +342,12 @@ func shortTitle(opt serpent.Option) string { // last ": " once the leading segment belongs to the top-level group. Names // that do not repeat the group are returned unchanged. func stripGroupPrefix(name string, g *serpent.Group) string { - anc := g.Ancestry() - if len(anc) == 0 { + ancestry := g.Ancestry() + if len(ancestry) == 0 { return name } - names := make([]string, len(anc)) - for i, a := range anc { + names := make([]string, len(ancestry)) + for i, a := range ancestry { names[i] = a.Name } From aeefa2e37a609c38250d35fcf5ca9d50de94519e Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Wed, 8 Jul 2026 17:17:12 +0000 Subject: [PATCH 08/13] docs: preserve feature-name casing in configuration reference Keep branded feature names (AI Gateway, AI Gateway Proxy, Template Builder) in their canonical casing while sentence case remains the default for all other headings. --- docs/admin/setup/configuration-reference.md | 8 ++-- scripts/configdocgen/main.go | 43 +++++++++++++++++++-- 2 files changed, 44 insertions(+), 7 deletions(-) diff --git a/docs/admin/setup/configuration-reference.md b/docs/admin/setup/configuration-reference.md index 76a4f052b3753..efa5093fafac8 100644 --- a/docs/admin/setup/configuration-reference.md +++ b/docs/admin/setup/configuration-reference.md @@ -206,7 +206,7 @@ Periodically check for new releases of Coder and inform the owner. The check is - YAML key: `updateCheck` - Default value: `false` -## AI gateway +## AI Gateway ### AI budget period @@ -386,7 +386,7 @@ Emit structured logs for AI Gateway interception records. Use this for exporting - Environment variable: `CODER_AI_GATEWAY_OPENAI_KEY` - CLI flag: [`--ai-gateway-openai-key`](../../reference/cli/server.md#--ai-gateway-openai-key) -## AI gateway proxy +## AI Gateway Proxy ### API dump directory @@ -1779,9 +1779,9 @@ Whether telemetry is enabled or not. Coder collects anonymized usage data to hel - YAML key: `telemetry.enable` - Default value: `true` -## Template builder +## Template Builder -### Disable template builder +### Disable Template Builder Disable the template builder feature for guided template creation. When disabled, all /api/v2/templatebuilder/* endpoints return 404. diff --git a/scripts/configdocgen/main.go b/scripts/configdocgen/main.go index a03b76145c068..821262fe0d64a 100644 --- a/scripts/configdocgen/main.go +++ b/scripts/configdocgen/main.go @@ -397,10 +397,20 @@ var properNoun = map[string]bool{ "wireguard": true, } +// featureNames are product/feature names whose exact casing is restored after +// sentence-casing, so headings like "AI Gateway" and "Template Builder" keep +// their branded form. Longer names come first so they win over shorter +// prefixes (e.g. "AI Gateway Proxy" before "AI Gateway"). +var featureNames = []string{ + "AI Gateway Proxy", + "AI Gateway", + "Template Builder", +} + // sentenceCase lowercases a heading's words after the first while preserving // the first word, acronyms and mixed-case tokens (URL, TLS, OAuth2, OpenID, -// GitHub), and known proper nouns. It runs at generation time so headings need -// no manual or AI pass. +// GitHub), known proper nouns, and the feature names above. It runs at +// generation time so headings need no manual or AI pass. func sentenceCase(s string) string { words := strings.Fields(s) seenFirst := false @@ -416,7 +426,34 @@ func sentenceCase(s string) string { words[i] = strings.ToLower(w) } } - return strings.Join(words, " ") + return restoreFeatureNames(strings.Join(words, " ")) +} + +// restoreFeatureNames rewrites any case-insensitive occurrence of a feature +// name with its canonical casing. +func restoreFeatureNames(s string) string { + for _, name := range featureNames { + s = replaceFold(s, name) + } + return s +} + +// replaceFold replaces case-insensitive occurrences of canonical in s with +// canonical's exact casing. It assumes canonical is ASCII, which holds for the +// feature names above. +func replaceFold(s, canonical string) string { + lower := strings.ToLower(canonical) + var b strings.Builder + for { + idx := strings.Index(strings.ToLower(s), lower) + if idx < 0 { + _, _ = b.WriteString(s) + return b.String() + } + _, _ = b.WriteString(s[:idx]) + _, _ = b.WriteString(canonical) + s = s[idx+len(canonical):] + } } // keepWord reports whether a word must keep its capitalization: proper nouns, From e80d7522178c697cc2cffdccea03c5b25d8d3efd Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Wed, 8 Jul 2026 17:34:51 +0000 Subject: [PATCH 09/13] test(scripts/configdocgen): add unit tests for heading transforms Cover sentenceCase, stripGroupPrefix, shortTitle, isDeprecated, emphasizeDeprecation, and collapse (addresses CRF-15). --- scripts/configdocgen/main_test.go | 131 ++++++++++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 scripts/configdocgen/main_test.go diff --git a/scripts/configdocgen/main_test.go b/scripts/configdocgen/main_test.go new file mode 100644 index 0000000000000..f6af6f989b2f7 --- /dev/null +++ b/scripts/configdocgen/main_test.go @@ -0,0 +1,131 @@ +package main + +import ( + "testing" + + "github.com/coder/serpent" +) + +func TestSentenceCase(t *testing.T) { + t.Parallel() + cases := map[string]string{ + "Send Actor Headers": "Send actor headers", + "Anthropic Base URL": "Anthropic base URL", + "Allow BYOK": "Allow BYOK", + "Email Authentication": "Email authentication", + "Trace Honeycomb API Key": "Trace Honeycomb API key", + "OpenID Connect sign in text": "OpenID connect sign in text", + "SSH Keygen Algorithm": "SSH keygen algorithm", + "pprof": "pprof", + // Feature names keep their branded casing. + "AI Gateway": "AI Gateway", + "AI Gateway Proxy": "AI Gateway Proxy", + "Template Builder": "Template Builder", + "Disable Template Builder": "Disable Template Builder", + // A leading symbol is preserved and does not count as the first word. + "⚠️ Dangerous": "⚠️ Dangerous", + } + for in, want := range cases { + if got := sentenceCase(in); got != want { + t.Errorf("sentenceCase(%q) = %q, want %q", in, got, want) + } + } +} + +func TestStripGroupPrefix(t *testing.T) { + t.Parallel() + + aiGateway := serpent.Group{Name: "AI Gateway"} + email := serpent.Group{Name: "Email"} + emailAuth := serpent.Group{Name: "Email Authentication", Parent: &email} + introspection := serpent.Group{Name: "Introspection"} + healthCheck := serpent.Group{Name: "Health Check", Parent: &introspection} + networking := serpent.Group{Name: "Networking"} + derp := serpent.Group{Name: "DERP", Parent: &networking} + oauth2 := serpent.Group{Name: "OAuth2"} + github := serpent.Group{Name: "GitHub", Parent: &oauth2} + dangerous := serpent.Group{Name: "⚠️ Dangerous"} + + cases := []struct { + name string + group *serpent.Group + want string + }{ + // Space-prefixed names drop the group path. + {"AI Gateway Send Actor Headers", &aiGateway, "Send Actor Headers"}, + {"DERP Config Path", &derp, "Config Path"}, + {"OAuth2 GitHub Allow Everyone", &github, "Allow Everyone"}, + // Colon-prefixed names drop up to the last ": ". + {"Email Auth: Identity", &emailAuth, "Identity"}, + // A meaningful colon that is not a group separator is preserved. + {"Health Check Threshold: Database", &healthCheck, "Threshold: Database"}, + // The Dangerous group's emoji name still matches its "DANGEROUS:" prefix. + {"DANGEROUS: Allow Path App Sharing", &dangerous, "Allow Path App Sharing"}, + // Names that do not repeat the group are unchanged. + {"Access URL", &networking, "Access URL"}, + } + for _, tc := range cases { + if got := stripGroupPrefix(tc.name, tc.group); got != tc.want { + t.Errorf("stripGroupPrefix(%q) = %q, want %q", tc.name, got, tc.want) + } + } +} + +func TestShortTitle(t *testing.T) { + t.Parallel() + + aiGateway := serpent.Group{Name: "AI Gateway"} + cases := []struct { + opt serpent.Option + want string + }{ + {serpent.Option{Name: "AI Gateway Send Actor Headers", Group: &aiGateway}, "Send actor headers"}, + {serpent.Option{Name: "AI Gateway Anthropic Base URL", Group: &aiGateway}, "Anthropic base URL"}, + // No group: only sentence case applies. + {serpent.Option{Name: "Cache Directory"}, "Cache directory"}, + } + for _, tc := range cases { + if got := shortTitle(tc.opt); got != tc.want { + t.Errorf("shortTitle(%q) = %q, want %q", tc.opt.Name, got, tc.want) + } + } +} + +func TestIsDeprecated(t *testing.T) { + t.Parallel() + cases := []struct { + name string + opt serpent.Option + want bool + }{ + {"description prefix", serpent.Option{Description: "Deprecated: use X instead."}, true}, + {"description sentence", serpent.Option{Description: "Deprecated and ignored."}, true}, + {"use instead", serpent.Option{UseInstead: []serpent.Option{{Name: "X"}}}, true}, + {"active", serpent.Option{Description: "A normal option."}, false}, + } + for _, tc := range cases { + if got := isDeprecated(tc.opt); got != tc.want { + t.Errorf("isDeprecated(%s) = %v, want %v", tc.name, got, tc.want) + } + } +} + +func TestEmphasizeDeprecation(t *testing.T) { + t.Parallel() + cases := map[string]string{ + "Deprecated and ignored.": "**Deprecated** and ignored.", + "Deprecated: use X.": "**Deprecated**: use X.", + } + for in, want := range cases { + if got := emphasizeDeprecation(in); got != want { + t.Errorf("emphasizeDeprecation(%q) = %q, want %q", in, got, want) + } + } +} + +func TestCollapse(t *testing.T) { + t.Parallel() + if got := collapse("a\n b\tc "); got != "a b c" { + t.Errorf("collapse() = %q, want %q", got, "a b c") + } +} From 48a12fc1b3937e45b10c6191102fce3d9cac97c1 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Wed, 8 Jul 2026 18:46:25 +0000 Subject: [PATCH 10/13] docs: fix OpenID Connect casing and refine config reference generator Address configuration reference review feedback: - Restore "OpenID Connect" casing in generated headings by adding it to the preserved-casing list. - Describe the page as a list, not a table, in index.md and manifest.json. - Add a render-pipeline test and cover the UseInstead deprecation path. - Convert the map-based tests to table-driven subtests for deterministic output. - Rename properNoun to properNouns and trim generator comments. --- docs/admin/setup/configuration-reference.md | 4 +- docs/admin/setup/index.md | 2 +- docs/manifest.json | 2 +- scripts/configdocgen/main.go | 26 ++-- scripts/configdocgen/main_test.go | 142 ++++++++++++++++---- 5 files changed, 128 insertions(+), 48 deletions(-) diff --git a/docs/admin/setup/configuration-reference.md b/docs/admin/setup/configuration-reference.md index efa5093fafac8..6d55ee9b64939 100644 --- a/docs/admin/setup/configuration-reference.md +++ b/docs/admin/setup/configuration-reference.md @@ -1637,7 +1637,7 @@ OIDC claim field to use as the username. - YAML key: `oidc.usernameField` - Default value: `preferred_username` -### OpenID connect sign in text +### OpenID Connect sign in text The text to show on the OpenID Connect sign in button. @@ -1646,7 +1646,7 @@ The text to show on the OpenID Connect sign in button. - YAML key: `oidc.signInText` - Default value: `OpenID Connect` -### OpenID connect icon URL +### OpenID Connect icon URL URL pointing to the icon to use on the OpenID Connect login button. diff --git a/docs/admin/setup/index.md b/docs/admin/setup/index.md index 41e977d0c6b56..2b5614b737f18 100644 --- a/docs/admin/setup/index.md +++ b/docs/admin/setup/index.md @@ -7,7 +7,7 @@ full list of the options, run `coder server --help` or see our > [!TIP] > Need to look up an exact environment variable, CLI flag, or YAML key for a > setting? See the [configuration reference](./configuration-reference.md) for -> a searchable table of every option. +> a searchable list of every option. ## Access URL diff --git a/docs/manifest.json b/docs/manifest.json index 033ebbd7274a9..1d20239ce8350 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -426,7 +426,7 @@ }, { "title": "Configuration Reference", - "description": "Searchable table of every Coder server setting with its environment variable, CLI flag, and YAML key", + "description": "Searchable list of every Coder server setting with its environment variable, CLI flag, and YAML key", "path": "./admin/setup/configuration-reference.md" }, { diff --git a/scripts/configdocgen/main.go b/scripts/configdocgen/main.go index 821262fe0d64a..3bfb6efdc64b4 100644 --- a/scripts/configdocgen/main.go +++ b/scripts/configdocgen/main.go @@ -242,11 +242,8 @@ func sortTree(n *node) { } } -// sectionRank fixes the display order of top-level sections. General comes -// first because it holds the most common first-time setup options (Postgres, -// cache directory, access URL). The Dangerous group comes last, regardless of -// its emoji prefix, so the reference does not steer operators toward risky -// settings. Every other section sorts alphabetically between them. +// sectionRank orders top-level sections: General first, Dangerous last +// (regardless of its emoji prefix), everything else alphabetical. func sectionRank(name string) int { switch { case name == generalSection: @@ -377,10 +374,10 @@ func stripGroupPrefix(name string, g *serpent.Group) string { return name } -// properNoun lists words that keep their capitalization in sentence case. +// properNouns lists words that keep their capitalization in sentence case. // They have ordinary title-case shape, so keepWord's acronym check would not // otherwise catch them. -var properNoun = map[string]bool{ +var properNouns = map[string]bool{ "anthropic": true, "bedrock": true, "claude": true, @@ -397,20 +394,17 @@ var properNoun = map[string]bool{ "wireguard": true, } -// featureNames are product/feature names whose exact casing is restored after -// sentence-casing, so headings like "AI Gateway" and "Template Builder" keep -// their branded form. Longer names come first so they win over shorter -// prefixes (e.g. "AI Gateway Proxy" before "AI Gateway"). +// featureNames are multi-word names whose exact casing is restored after +// sentence-casing. A name that prefixes another comes after the longer one. var featureNames = []string{ "AI Gateway Proxy", "AI Gateway", + "OpenID Connect", "Template Builder", } -// sentenceCase lowercases a heading's words after the first while preserving -// the first word, acronyms and mixed-case tokens (URL, TLS, OAuth2, OpenID, -// GitHub), known proper nouns, and the feature names above. It runs at -// generation time so headings need no manual or AI pass. +// sentenceCase lowercases a heading's words after the first, preserving the +// first word, acronyms and mixed-case tokens, proper nouns, and feature names. func sentenceCase(s string) string { words := strings.Fields(s) seenFirst := false @@ -464,7 +458,7 @@ func keepWord(w string) bool { if core == "" { return true } - if properNoun[strings.ToLower(core)] { + if properNouns[strings.ToLower(core)] { return true } for i, r := range core { diff --git a/scripts/configdocgen/main_test.go b/scripts/configdocgen/main_test.go index f6af6f989b2f7..c9a69aa49f802 100644 --- a/scripts/configdocgen/main_test.go +++ b/scripts/configdocgen/main_test.go @@ -1,6 +1,7 @@ package main import ( + "strings" "testing" "github.com/coder/serpent" @@ -8,27 +9,32 @@ import ( func TestSentenceCase(t *testing.T) { t.Parallel() - cases := map[string]string{ - "Send Actor Headers": "Send actor headers", - "Anthropic Base URL": "Anthropic base URL", - "Allow BYOK": "Allow BYOK", - "Email Authentication": "Email authentication", - "Trace Honeycomb API Key": "Trace Honeycomb API key", - "OpenID Connect sign in text": "OpenID connect sign in text", - "SSH Keygen Algorithm": "SSH keygen algorithm", - "pprof": "pprof", - // Feature names keep their branded casing. - "AI Gateway": "AI Gateway", - "AI Gateway Proxy": "AI Gateway Proxy", - "Template Builder": "Template Builder", - "Disable Template Builder": "Disable Template Builder", - // A leading symbol is preserved and does not count as the first word. - "⚠️ Dangerous": "⚠️ Dangerous", - } - for in, want := range cases { - if got := sentenceCase(in); got != want { - t.Errorf("sentenceCase(%q) = %q, want %q", in, got, want) - } + cases := []struct { + name string + in string + want string + }{ + {"lowercases trailing words", "Send Actor Headers", "Send actor headers"}, + {"keeps trailing acronym", "Anthropic Base URL", "Anthropic base URL"}, + {"keeps all-caps token", "Allow BYOK", "Allow BYOK"}, + {"lowercases ordinary word", "Email Authentication", "Email authentication"}, + {"keeps proper noun", "Trace Honeycomb API Key", "Trace Honeycomb API key"}, + {"restores OpenID Connect", "OpenID Connect sign in text", "OpenID Connect sign in text"}, + {"keeps leading mixed-case token", "SSH Keygen Algorithm", "SSH keygen algorithm"}, + {"single lowercase word", "pprof", "pprof"}, + {"feature name", "AI Gateway", "AI Gateway"}, + {"longer feature name wins", "AI Gateway Proxy", "AI Gateway Proxy"}, + {"feature name as whole title", "Template Builder", "Template Builder"}, + {"feature name after leading word", "Disable Template Builder", "Disable Template Builder"}, + {"leading symbol is not the first word", "⚠️ Dangerous", "⚠️ Dangerous"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + if got := sentenceCase(tc.in); got != tc.want { + t.Errorf("sentenceCase(%q) = %q, want %q", tc.in, got, tc.want) + } + }) } } @@ -112,14 +118,28 @@ func TestIsDeprecated(t *testing.T) { func TestEmphasizeDeprecation(t *testing.T) { t.Parallel() - cases := map[string]string{ - "Deprecated and ignored.": "**Deprecated** and ignored.", - "Deprecated: use X.": "**Deprecated**: use X.", + cases := []struct { + name string + in string + want string + }{ + // Description already starts with the marker: only the marker is bolded. + {"marker with sentence", "Deprecated and ignored.", "**Deprecated** and ignored."}, + {"marker with colon", "Deprecated: use X.", "**Deprecated**: use X."}, + // Description does not start with the marker (the UseInstead path): the + // marker is prepended. + {"no marker", "A normal description.", "**Deprecated.** A normal description."}, + {"empty description", "", "Deprecated."}, + // A bare marker with no trailing text is left unbolded (markdownlint MD036). + {"bare marker", "Deprecated", "Deprecated"}, } - for in, want := range cases { - if got := emphasizeDeprecation(in); got != want { - t.Errorf("emphasizeDeprecation(%q) = %q, want %q", in, got, want) - } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + if got := emphasizeDeprecation(tc.in); got != tc.want { + t.Errorf("emphasizeDeprecation(%q) = %q, want %q", tc.in, got, tc.want) + } + }) } } @@ -129,3 +149,69 @@ func TestCollapse(t *testing.T) { t.Errorf("collapse() = %q, want %q", got, "a b c") } } + +// TestRenderPipeline exercises buildTree and render end to end: section +// nesting and ordering, option skipping, deprecated sinking, and the per-option +// bullet list (environment variable, CLI flag anchor, YAML key, default). +func TestRenderPipeline(t *testing.T) { + t.Parallel() + + email := serpent.Group{Name: "Email", YAML: "email"} + emailAuth := serpent.Group{Name: "Email Authentication", YAML: "emailAuth", Parent: &email} + + opts := serpent.OptionSet{ + // Hidden options and options with no env/flag/YAML are skipped. + {Name: "Hidden Option", Env: "CODER_HIDDEN", Hidden: true}, + {Name: "Unsettable Option"}, + // General section (no group). + {Name: "Access URL", Env: "CODER_ACCESS_URL", Flag: "access-url", Default: "https://example.com", Description: "The access URL."}, + // Deprecated via UseInstead: description does not start with "Deprecated". + {Name: "Email From", Env: "CODER_EMAIL_FROM", Flag: "email-from", YAML: "from", Group: &email, Description: "The sender address.", UseInstead: []serpent.Option{{Name: "Notifications Email From"}}}, + // Active option with a flag shorthand. + {Name: "Email Smarthost", Env: "CODER_EMAIL_SMARTHOST", Flag: "email-smarthost", FlagShorthand: "s", YAML: "smarthost", Group: &email, Description: "The SMTP host."}, + // Nested child section. + {Name: "Email Authentication Identity", Env: "CODER_EMAIL_AUTH_IDENTITY", YAML: "identity", Group: &emailAuth, Description: "The identity."}, + } + + got := render(buildTree(opts)) + + wantContains := []string{ + "## General", + "### Access URL", + "- Environment variable: `CODER_ACCESS_URL`", + "- CLI flag: [`--access-url`](../../reference/cli/server.md#--access-url)", + "- Default value: `https://example.com`", + "## Email", + "### Smarthost", + // Flag shorthand is folded into the anchor to match the CLI reference. + "- CLI flag: [`--email-smarthost`](../../reference/cli/server.md#-s---email-smarthost)", + // YAML key is the dotted group path. + "- YAML key: `email.from`", + // Deprecated marker is prepended for the UseInstead path. + "**Deprecated.** The sender address.", + "### Email authentication", + "#### Identity", + "- YAML key: `email.emailAuth.identity`", + } + for _, w := range wantContains { + if !strings.Contains(got, w) { + t.Errorf("render() missing %q\n---\n%s", w, got) + } + } + + // General (rank -1) sorts before every other top-level section. + if i, j := strings.Index(got, "## General"), strings.Index(got, "## Email"); i < 0 || j < 0 || i > j { + t.Errorf("General should render before Email (got indexes %d, %d)", i, j) + } + // Active options sort before deprecated ones within a section. + if i, j := strings.Index(got, "### Smarthost"), strings.Index(got, "### From"); i < 0 || j < 0 || i > j { + t.Errorf("active option should render before deprecated option (got indexes %d, %d)", i, j) + } + // Hidden and unsettable options never render. + if strings.Contains(got, "Hidden") { + t.Error("hidden option should be skipped") + } + if strings.Contains(got, "Unsettable") { + t.Error("option with no env/flag/YAML should be skipped") + } +} From ecbec99b741fc2e73497fc38dff5703aa43feed8 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Wed, 8 Jul 2026 19:57:33 +0000 Subject: [PATCH 11/13] test(scripts/configdocgen): cover DefaultFn, Dangerous section, and subtests --- scripts/configdocgen/main_test.go | 40 ++++++++++++++++++++++++------- 1 file changed, 31 insertions(+), 9 deletions(-) diff --git a/scripts/configdocgen/main_test.go b/scripts/configdocgen/main_test.go index c9a69aa49f802..b2a475b49b748 100644 --- a/scripts/configdocgen/main_test.go +++ b/scripts/configdocgen/main_test.go @@ -71,9 +71,12 @@ func TestStripGroupPrefix(t *testing.T) { {"Access URL", &networking, "Access URL"}, } for _, tc := range cases { - if got := stripGroupPrefix(tc.name, tc.group); got != tc.want { - t.Errorf("stripGroupPrefix(%q) = %q, want %q", tc.name, got, tc.want) - } + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + if got := stripGroupPrefix(tc.name, tc.group); got != tc.want { + t.Errorf("stripGroupPrefix(%q) = %q, want %q", tc.name, got, tc.want) + } + }) } } @@ -91,9 +94,12 @@ func TestShortTitle(t *testing.T) { {serpent.Option{Name: "Cache Directory"}, "Cache directory"}, } for _, tc := range cases { - if got := shortTitle(tc.opt); got != tc.want { - t.Errorf("shortTitle(%q) = %q, want %q", tc.opt.Name, got, tc.want) - } + t.Run(tc.opt.Name, func(t *testing.T) { + t.Parallel() + if got := shortTitle(tc.opt); got != tc.want { + t.Errorf("shortTitle(%q) = %q, want %q", tc.opt.Name, got, tc.want) + } + }) } } @@ -110,9 +116,12 @@ func TestIsDeprecated(t *testing.T) { {"active", serpent.Option{Description: "A normal option."}, false}, } for _, tc := range cases { - if got := isDeprecated(tc.opt); got != tc.want { - t.Errorf("isDeprecated(%s) = %v, want %v", tc.name, got, tc.want) - } + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + if got := isDeprecated(tc.opt); got != tc.want { + t.Errorf("isDeprecated(%s) = %v, want %v", tc.name, got, tc.want) + } + }) } } @@ -158,6 +167,7 @@ func TestRenderPipeline(t *testing.T) { email := serpent.Group{Name: "Email", YAML: "email"} emailAuth := serpent.Group{Name: "Email Authentication", YAML: "emailAuth", Parent: &email} + dangerous := serpent.Group{Name: "⚠️ Dangerous", YAML: "dangerous"} opts := serpent.OptionSet{ // Hidden options and options with no env/flag/YAML are skipped. @@ -165,12 +175,16 @@ func TestRenderPipeline(t *testing.T) { {Name: "Unsettable Option"}, // General section (no group). {Name: "Access URL", Env: "CODER_ACCESS_URL", Flag: "access-url", Default: "https://example.com", Description: "The access URL."}, + // A DefaultFn with no static Default renders the computed-at-runtime label. + {Name: "Cache Directory", Env: "CODER_CACHE_DIRECTORY", Flag: "cache-dir", DefaultFn: func() string { return "~/.cache/coder" }, Description: "The cache directory."}, // Deprecated via UseInstead: description does not start with "Deprecated". {Name: "Email From", Env: "CODER_EMAIL_FROM", Flag: "email-from", YAML: "from", Group: &email, Description: "The sender address.", UseInstead: []serpent.Option{{Name: "Notifications Email From"}}}, // Active option with a flag shorthand. {Name: "Email Smarthost", Env: "CODER_EMAIL_SMARTHOST", Flag: "email-smarthost", FlagShorthand: "s", YAML: "smarthost", Group: &email, Description: "The SMTP host."}, // Nested child section. {Name: "Email Authentication Identity", Env: "CODER_EMAIL_AUTH_IDENTITY", YAML: "identity", Group: &emailAuth, Description: "The identity."}, + // A Dangerous group sorts last regardless of alphabetical order. + {Name: "DANGEROUS: Allow All Cors", Env: "CODER_DANGEROUS_ALLOW_ALL_CORS", Flag: "dangerous-allow-all-cors", Group: &dangerous, Description: "Allow all cross-origin requests."}, } got := render(buildTree(opts)) @@ -189,9 +203,13 @@ func TestRenderPipeline(t *testing.T) { "- YAML key: `email.from`", // Deprecated marker is prepended for the UseInstead path. "**Deprecated.** The sender address.", + // A DefaultFn with no static Default is labeled, not evaluated. + "- Default value: `(computed at runtime)`", "### Email authentication", "#### Identity", "- YAML key: `email.emailAuth.identity`", + // The Dangerous group renders as its own section. + "## ⚠️ Dangerous", } for _, w := range wantContains { if !strings.Contains(got, w) { @@ -207,6 +225,10 @@ func TestRenderPipeline(t *testing.T) { if i, j := strings.Index(got, "### Smarthost"), strings.Index(got, "### From"); i < 0 || j < 0 || i > j { t.Errorf("active option should render before deprecated option (got indexes %d, %d)", i, j) } + // The Dangerous section sorts last among top-level sections. + if i, j := strings.Index(got, "## Email"), strings.Index(got, "## ⚠️ Dangerous"); i < 0 || j < 0 || i > j { + t.Errorf("Dangerous section should render last (got indexes %d, %d)", i, j) + } // Hidden and unsettable options never render. if strings.Contains(got, "Hidden") { t.Error("hidden option should be skipped") From 93dc676979efaa783eaff4b5ca2a092ea37dc89f Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Thu, 23 Jul 2026 16:32:02 +0000 Subject: [PATCH 12/13] docs: regenerate configuration reference for current deployment values Rebasing onto main picked up the new --ai-gateway-proxy-target option and a backtick fix in the GitHub allowed-teams help text. Regenerate the page so make gen and check-docs stay clean. --- docs/admin/setup/configuration-reference.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/admin/setup/configuration-reference.md b/docs/admin/setup/configuration-reference.md index 6d55ee9b64939..3636d7cc1ed86 100644 --- a/docs/admin/setup/configuration-reference.md +++ b/docs/admin/setup/configuration-reference.md @@ -454,6 +454,14 @@ Path to the TLS private key file for the AI Gateway Proxy listener. Must be set - CLI flag: [`--ai-gateway-proxy-tls-key-file`](../../reference/cli/server.md#--ai-gateway-proxy-tls-key-file) - YAML key: `ai_gateway_proxy.tls_key_file` +### Target + +Base URL of the AI Gateway to forward intercepted requests to. Defaults to the embedded AI Gateway address at the Coder access URL plus /api/v2/ai-gateway. + +- Environment variable: `CODER_AI_GATEWAY_PROXY_TARGET` +- CLI flag: [`--ai-gateway-proxy-target`](../../reference/cli/server.md#--ai-gateway-proxy-target) +- YAML key: `ai_gateway_proxy.target` + ### Upstream proxy URL of an upstream HTTP proxy to chain tunneled (non-allowlisted) requests through. Format: http://[user:pass@]host:port or https://[user:pass@]host:port. @@ -1402,7 +1410,7 @@ Organizations the user must be a member of to Login with GitHub. #### Allowed teams -Teams inside organizations the user must be a member of to Login with GitHub. Structured as: /. +Teams inside organizations the user must be a member of to Login with GitHub. Structured as: `/`. - Environment variable: `CODER_OAUTH2_GITHUB_ALLOWED_TEAMS` - CLI flag: [`--oauth2-github-allowed-teams`](../../reference/cli/server.md#--oauth2-github-allowed-teams) From bc9b7ac894721cf9618514278ff16a73aa8ce5f8 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Thu, 23 Jul 2026 21:09:03 +0000 Subject: [PATCH 13/13] docs: make GitHub auth env-var setup delivery-agnostic Review feedback noted the demo conversion led with a systemd/coder.env assumption, but a large share of deployments run on Kubernetes. Reframe Step 2 so the environment-variable guidance does not assume a system service: a neutral lead sentence, then Helm values.yaml and /etc/coder.d/coder.env as co-equal paths (Helm first) rather than the system service as default with Helm as an afterthought. Also align the DOCS_STYLE_GUIDE env-var-first convention so it no longer singles out systemd as its only concrete example. --- .claude/docs/DOCS_STYLE_GUIDE.md | 5 +-- docs/admin/users/github-auth.md | 54 ++++++++++++++++++-------------- 2 files changed, 33 insertions(+), 26 deletions(-) diff --git a/.claude/docs/DOCS_STYLE_GUIDE.md b/.claude/docs/DOCS_STYLE_GUIDE.md index a58c63183406b..1b12fef33f240 100644 --- a/.claude/docs/DOCS_STYLE_GUIDE.md +++ b/.claude/docs/DOCS_STYLE_GUIDE.md @@ -174,8 +174,9 @@ When showing how to configure `coder server` in admin or setup documentation, lead with the environment variable form. Production Coder deployments are typically run as a system service, container, or Helm chart, all of which set configuration through environment variables (for -systemd, via `/etc/coder.d/coder.env`). Showing the CLI flag form first -forces operators to mentally translate every example. +example, Helm `values.yaml` for Kubernetes or `/etc/coder.d/coder.env` for +a system service). Showing the CLI flag form first forces operators to +mentally translate every example. Show the equivalent CLI flag only when the example is invoking `coder server` directly (for local development or one-off runs), or as a diff --git a/docs/admin/users/github-auth.md b/docs/admin/users/github-auth.md index 7ed1484898207..8735f1100807c 100644 --- a/docs/admin/users/github-auth.md +++ b/docs/admin/users/github-auth.md @@ -85,28 +85,13 @@ CODER_OAUTH2_GITHUB_DEFAULT_PROVIDER_ENABLE=false ## Step 2: Configure Coder with the OAuth credentials -Coder server reads these settings from environment variables. On a host -running Coder as a system service, add the variables to -`/etc/coder.d/coder.env`: +Coder server reads these settings from environment variables. Set them +wherever your deployment manages environment variables. For example, use +Helm `values.yaml` for Kubernetes or `/etc/coder.d/coder.env` for a system +service. -```sh -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" -``` - -Then restart Coder with `sudo service coder restart`. For GitHub Enterprise -support, also set `CODER_OAUTH2_GITHUB_ENTERPRISE_BASE_URL`. - -> [!TIP] -> To allow everyone to sign up using GitHub, set: -> -> ```shell -> CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true -> ``` - -If deploying Coder via Helm, set the same variables in `values.yaml`: +**Kubernetes (Helm):** set the variables under `coder.env` in your +`values.yaml`: ```yaml coder: @@ -125,19 +110,40 @@ coder: # value: "true" ``` -Then upgrade Coder with: +Then apply the change with `helm upgrade`: ```sh helm upgrade coder-v2/coder -n -f values.yaml ``` +**System service:** add the variables to `/etc/coder.d/coder.env`: + +```sh +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" +``` + +Then restart Coder with `sudo service coder restart`. + +> [!TIP] +> To allow everyone to sign up using GitHub, set: +> +> ```shell +> CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true +> ``` + +For GitHub Enterprise support, also set +`CODER_OAUTH2_GITHUB_ENTERPRISE_BASE_URL`. + > [!NOTE] > Every option above also has an equivalent CLI flag (for example, > `CODER_OAUTH2_GITHUB_CLIENT_ID` becomes `--oauth2-github-client-id`). > CLI flags are convenient for ad-hoc invocations of `coder server` during > local development. For production deployments, prefer environment -> variables so the configuration lives with the service unit, container, or -> Helm chart that manages Coder. See the +> variables so the configuration lives with the container, Helm chart, or +> service unit that manages Coder. See the > [configuration reference](../setup/configuration-reference.md) for the > full mapping between environment variables and flags.