Files
coder/docs/reference/cli/workspace-proxy/server.md
T
Nick Vigilante 6e51c66a97 docs: give every table header cell text and fail lint on empty ones (#30879)
## Summary

axe reports `empty-table-header` on 116 generated CLI reference pages
and several hand-written pages: a header cell with no text is announced
by screen readers as an unnamed column. This PR gives every table header
cell in `docs/` text, and adds a lint check so empty header cells can't
come back.

## How to review this PR

- `docs/reference/cli/`: 116 files, these all generate identically, so I
would only spot check 2-3 of them and skip the rest
- `docs/*` outside of `docs/reference/cli/`: 6 files, normal review of
these
- `scripts`: 5 files, code review of the Bash and Go files to make sure
we're properly inserting headers into each table

## What changed

**Generator.** `scripts/clidocgen` wrote an empty header row (`| | |`)
over each option's metadata table (Type, Environment, YAML, Default). It
now writes `| Property | Value |`. Subcommand tables already had `Name |
Purpose` and are unchanged. Regenerated with `make
docs/reference/cli/index.md`: 116 files under `docs/reference/cli/`
change. The header rows change, and the body rows of each option table
are re-padded to the wider first column; the content is otherwise
identical. Every option on those 116 pages now shows a visible `Property
| Value` header row above Type, Environment, YAML, and Default, so this
is a visual change on the docs site as well as a screen reader one. The
CLI's own `--help` output doesn't use this template, so it's unchanged.

**Audit logs.** `docs/admin/security/audit-logs.md` already has `Field |
Tracked` headers on `main` (the generator writes them), so there was
nothing to change there; the live-site finding predates that.

**Hand-written tables.**
- `docs/admin/networking/port-forwarding.md`: the CORS matrix had three
empty spanning corner cells. The corner now reads `From user` and `From
workspace` (spanning the three row-header columns, beside the Alice/Bob
and Workspace rows) and `To user`, `To workspace`, `To app` (over the
three row-header columns). The grid is still 3 header rows by 7 columns.
The From cells have `scope="row"` and the other header-row cells
`scope="col"`, so the From labels don't become column headers for the
body's label columns; the body's user, workspace, and app labels are
`<th scope="row">`; and a `<caption>` says columns are the origin and
rows the destination.
- `groups-roles.md`, `airgap.md`, `scale-testing.md`,
`workspace-tags.md`: these four corner cells are already filled by
#30873. The new check would fail CI without them, so this PR carries the
same four lines, byte-identical to #30873 (`Permission`, `Component`,
`Scenario`, `Input`), so whichever PR merges second rebases without
conflict. If #30873 merges first, these hunks drop out.

**New check.** `scripts/docshtmlcheck` (`make lint/docs-html`, part of
`make lint`) now also reports `empty-table-header`. I put it there
because that checker already parses every Markdown file under `docs/`,
generated pages included, with goldmark and tokenizes raw HTML with
`golang.org/x/net/html`, and it already runs in CI. A markdownlint
custom rule would have needed a new JS rule and HTML parsing there.
- Markdown pipe tables: the header row, via goldmark's GFM table
extension.
- Raw HTML tables: every `<th>`, tracked across HTML blocks, with
entities decoded and whitespace trimmed, so `<th></th>`,
`<th>&nbsp;</th>`, and `<th><br></th>` are all reported. Markdown
between the HTML blocks of an open `<th>` counts as its text. Tables in
code blocks are ignored.
- Output: `docs/x.md:29: empty-table-header: header cell 1 has no text
(table's first header "Auditor")`, plus a summary footer.
- The tokenizer loop moved out of `scanNode` into a shared
`tokenizeSegments` helper so both checks use it; `scanNode`'s behavior
is unchanged.
- The style guide's checks table gets one row; the README for the
checker describes the rule.

## Testing

- Tests first: `TestCheckTables` (now 22 cases) and
`TestRunEmptyTableHeader` failed against a stub, then pass. The existing
`docshtmlcheck` tests pass unchanged.
- `go run ./scripts/docshtmlcheck` on `main` reports 1,561 empty header
cells (116 CLI pages, port-forwarding, and the four #30873 tables); on
this branch it reports none.
- `go test ./scripts/docshtmlcheck/ ./scripts/clidocgen/
./scripts/docgenenv/`, golangci-lint on the changed packages, `make
lint/docs-html lint/docs-manifest lint/docs-gen-filter lint/emdash`,
`pnpm run check-docs`, and Vale on the changed hand-written pages all
pass.
- `make gen` couldn't run to completion locally (no `protoc-gen-go`);
CI's gen check covers it. The CLI pages were regenerated with the repo's
own target.

Review feedback applied in cfd29a2160 (entities decoded in Markdown
text, image alt text and autolinks count as text), 709a58f603 (per-kind
counts, finding order, CLI generator note), 8e61ff3afa (CORS matrix
scopes and caption), and b807bcbbc7 and 2871f89bdf (style guide rule
section, `make lint/docs-html` in the checks table, coverage counts).

Linear: DOCS-1308

---

🤖 Built with AI assistance.
2026-10-21 10:58:04 -07:00

19 KiB
Generated

title, description
title description
`coder workspace-proxy server` Start a workspace proxy server.

Start a workspace proxy server

Usage

coder workspace-proxy server [flags]

Options

--access-url

Property Value
Type url
Environment $CODER_ACCESS_URL
YAML networking.accessURL

The URL that users will use to access the Coder deployment.

--wildcard-access-url

Property Value
Type string
Environment $CODER_WILDCARD_ACCESS_URL
YAML networking.wildcardAccessURL

Specifies the wildcard hostname to use for workspace applications in the form "*.example.com".

--docs-url

Property Value
Type url
Environment $CODER_DOCS_URL
YAML networking.docsURL
Default https://coder.com/docs

Specifies the custom docs URL.

--http-address

Property Value
Type string
Environment $CODER_HTTP_ADDRESS
YAML networking.http.httpAddress
Default 127.0.0.1:3000

HTTP bind address of the server. Unset to disable the HTTP endpoint.

--tls-address

Property Value
Type host:port
Environment $CODER_TLS_ADDRESS
YAML networking.tls.address
Default 127.0.0.1:3443

HTTPS bind address of the server.

--tls-enable

Property Value
Type bool
Environment $CODER_TLS_ENABLE
YAML networking.tls.enable

Whether TLS will be enabled.

--tls-cert-file

Property Value
Type string-array
Environment $CODER_TLS_CERT_FILE
YAML 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-client-ca-file

Property Value
Type string
Environment $CODER_TLS_CLIENT_CA_FILE
YAML networking.tls.clientCAFile

PEM-encoded Certificate Authority file used for checking the authenticity of client.

--tls-client-auth

Property Value
Type string
Environment $CODER_TLS_CLIENT_AUTH
YAML networking.tls.clientAuth
Default 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-key-file

Property Value
Type string-array
Environment $CODER_TLS_KEY_FILE
YAML networking.tls.keyFiles

Paths to the private keys for each of the certificates. It requires a PEM-encoded file.

--tls-min-version

Property Value
Type string
Environment $CODER_TLS_MIN_VERSION
YAML networking.tls.minVersion
Default tls12

Minimum supported version of TLS. Accepted values are "tls10", "tls11", "tls12" or "tls13".

--tls-client-cert-file

Property Value
Type string
Environment $CODER_TLS_CLIENT_CERT_FILE
YAML networking.tls.clientCertFile

Path to certificate for client TLS authentication. It requires a PEM-encoded file.

--tls-client-key-file

Property Value
Type string
Environment $CODER_TLS_CLIENT_KEY_FILE
YAML networking.tls.clientKeyFile

Path to key for client TLS authentication. It requires a PEM-encoded file.

--tls-ciphers

Property Value
Type string-array
Environment $CODER_TLS_CIPHERS
YAML 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-allow-insecure-ciphers

Property Value
Type bool
Environment $CODER_TLS_ALLOW_INSECURE_CIPHERS
YAML networking.tls.tlsAllowInsecureCiphers
Default 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.

--derp-server-enable

Property Value
Type bool
Environment $CODER_DERP_SERVER_ENABLE
YAML networking.derp.enable
Default true

Whether to enable or disable the embedded DERP relay server.

--derp-server-relay-url

Property Value
Type url
Environment $CODER_DERP_SERVER_RELAY_URL
YAML networking.derp.relayURL

An HTTP URL that is accessible by other replicas to relay DERP traffic. Required for high availability.

--block-direct-connections

Property Value
Type bool
Environment $CODER_BLOCK_DIRECT
YAML 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.

--prometheus-enable

Property Value
Type bool
Environment $CODER_PROMETHEUS_ENABLE
YAML introspection.prometheus.enable

Serve prometheus metrics on the address defined by prometheus address.

--prometheus-address

Property Value
Type host:port
Environment $CODER_PROMETHEUS_ADDRESS
YAML introspection.prometheus.address
Default 127.0.0.1:2112

The bind address to serve prometheus metrics.

--pprof-enable

Property Value
Type bool
Environment $CODER_PPROF_ENABLE
YAML introspection.pprof.enable

Serve pprof metrics on the address defined by pprof address.

--pprof-address

Property Value
Type host:port
Environment $CODER_PPROF_ADDRESS
YAML introspection.pprof.address
Default 127.0.0.1:6060

The bind address to serve pprof.

--trace

Property Value
Type bool
Environment $CODER_TRACE_ENABLE
YAML 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

Property Value
Type string
Environment $CODER_TRACE_HONEYCOMB_API_KEY

Enables trace exporting to Honeycomb.io using the provided API Key.

--trace-logs

Property Value
Type bool
Environment $CODER_TRACE_LOGS
YAML 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.

--log-human

Property Value
Type string
Environment $CODER_LOGGING_HUMAN
YAML introspection.logging.humanPath
Default /dev/stderr

Output human-readable logs to a given file.

--log-json

Property Value
Type string
Environment $CODER_LOGGING_JSON
YAML introspection.logging.jsonPath

Output JSON logs to a given file.

--log-stackdriver

Property Value
Type string
Environment $CODER_LOGGING_STACKDRIVER
YAML introspection.logging.stackdriverPath

Output Stackdriver compatible logs to a given file.

--experiments

Property Value
Type string-array
Environment $CODER_EXPERIMENTS
YAML 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.

--proxy-trusted-headers

Property Value
Type string-array
Environment $CODER_PROXY_TRUSTED_HEADERS
YAML networking.proxyTrustedHeaders

Headers to trust for forwarding IP addresses. e.g. Cf-Connecting-Ip, True-Client-Ip, X-Forwarded-For.

--proxy-trusted-origins

Property Value
Type string-array
Environment $CODER_PROXY_TRUSTED_ORIGINS
YAML networking.proxyTrustedOrigins

Origin addresses to respect "proxy-trusted-headers" and X-Forwarded-Host for subdomain app routing. e.g. 192.168.1.0/24.

Property Value
Type bool
Environment $CODER_SECURE_AUTH_COOKIE
YAML networking.secureAuthCookie

Controls if the 'Secure' property is set on browser session cookies.

Property Value
Type lax|none
Environment $CODER_SAMESITE_AUTH_COOKIE
YAML networking.sameSiteAuthCookie
Default lax

Controls the 'SameSite' property is set on browser session cookies.

Property Value
Type bool
Environment $CODER_HOST_PREFIX_COOKIE
YAML networking.hostPrefixCookie
Default 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.

--strict-transport-security

Property Value
Type int
Environment $CODER_STRICT_TRANSPORT_SECURITY
YAML networking.tls.strictTransportSecurity
Default 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

Property Value
Type string-array
Environment $CODER_STRICT_TRANSPORT_SECURITY_OPTIONS
YAML 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.

--disable-path-apps

Property Value
Type bool
Environment $CODER_DISABLE_PATH_APPS
YAML 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-owner-workspace-access

Property Value
Type bool
Environment $CODER_DISABLE_OWNER_WORKSPACE_ACCESS
YAML 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.

--write-config

Property Value
Type bool


Write out the current server config as YAML to stdout.

--proxy-session-token

Property Value
Type string
Environment $CODER_PROXY_SESSION_TOKEN
YAML externalWorkspaceProxy.proxySessionToken

Authentication token for the workspace proxy to communicate with coderd.

--primary-access-url

Property Value
Type url
Environment $CODER_PRIMARY_ACCESS_URL
YAML externalWorkspaceProxy.primaryAccessURL

URL to communicate with coderd. This should match the access URL of the Coder deployment.

--derp-only

Property Value
Type bool
Environment $CODER_PROXY_DERP_ONLY
YAML externalWorkspaceProxy.derpOnly

Run a proxy server that only supports DERP connections and does not proxy workspace app/terminal traffic.