Skip to content

Commit 48f29a1

Browse files
matifalimatifali
authored
docs: move api and cli docs routes to reference/ (coder#14241)
1 parent 6f9b1a3 commit 48f29a1

File tree

145 files changed

+4129
-3456
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

145 files changed

+4129
-3456
lines changed

‎.gitattributes

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Generated files
22
coderd/apidoc/docs.go linguist-generated=true
3-
docs/api/*.md linguist-generated=true
4-
docs/cli/*.md linguist-generated=true
3+
docs/reference/api/*.md linguist-generated=true
4+
docs/reference/cli/*.md linguist-generated=true
55
coderd/apidoc/swagger.json linguist-generated=true
66
coderd/database/dump.sql linguist-generated=true
77
peerbroker/proto/*.go linguist-generated=true

‎.prettierrc.yaml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,8 @@ tabWidth: 2
99
overrides:
1010
- files:
1111
- README.md
12-
- docs/api/**/*.md
13-
- docs/cli/**/*.md
12+
- docs/reference/api/**/*.md
13+
- docs/reference/cli/**/*.md
1414
- docs/changelogs/*.md
1515
- .github/**/*.{yaml,yml,toml}
1616
- scripts/**/*.{yaml,yml,toml}

‎.vscode/settings.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -196,7 +196,8 @@
196196
"**/*.gen.json": true,
197197
"**/testdata/*": true,
198198
"coderd/apidoc/**": true,
199-
"docs/api/*.md": true,
199+
"docs/reference/api/*.md": true,
200+
"docs/reference/cli/*.md": true,
200201
"docs/templates/*.md": true,
201202
"LICENSE": true,
202203
"scripts/metricsdocgen/metrics": true,

‎Makefile

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -489,7 +489,7 @@ gen: \
489489
codersdk/rbacresources_gen.go \
490490
site/src/api/rbacresources_gen.ts \
491491
docs/admin/prometheus.md \
492-
docs/cli.md \
492+
docs/reference/cli/README.md \
493493
docs/admin/audit-logs.md \
494494
coderd/apidoc/swagger.json \
495495
.prettierignore.include \
@@ -521,7 +521,7 @@ gen/mark-fresh:
521521
codersdk/rbacresources_gen.go \
522522
site/src/api/rbacresources_gen.ts \
523523
docs/admin/prometheus.md \
524-
docs/cli.md \
524+
docs/reference/cli/README.md \
525525
docs/admin/audit-logs.md \
526526
coderd/apidoc/swagger.json \
527527
.prettierignore.include \
@@ -633,10 +633,10 @@ docs/admin/prometheus.md: scripts/metricsdocgen/main.go scripts/metricsdocgen/me
633633
./scripts/pnpm_install.sh
634634
pnpm exec prettier --write ./docs/admin/prometheus.md
635635

636-
docs/cli.md: scripts/clidocgen/main.go examples/examples.gen.json $(GO_SRC_FILES)
636+
docs/reference/cli/README.md: scripts/clidocgen/main.go examples/examples.gen.json $(GO_SRC_FILES)
637637
CI=true BASE_PATH="." go run ./scripts/clidocgen
638638
./scripts/pnpm_install.sh
639-
pnpm exec prettier --write ./docs/cli.md ./docs/cli/*.md ./docs/manifest.json
639+
pnpm exec prettier --write ./docs/reference/cli/README.md ./docs/reference/cli/*.md ./docs/manifest.json
640640

641641
docs/admin/audit-logs.md: coderd/database/querier.go scripts/auditdocgen/main.go enterprise/audit/table.go coderd/rbac/object_gen.go
642642
go run scripts/auditdocgen/main.go
@@ -646,7 +646,7 @@ docs/admin/audit-logs.md: coderd/database/querier.go scripts/auditdocgen/main.go
646646
coderd/apidoc/swagger.json: $(shell find ./scripts/apidocgen $(FIND_EXCLUSIONS) -type f) $(wildcard coderd/*.go) $(wildcard enterprise/coderd/*.go) $(wildcard codersdk/*.go) $(wildcard enterprise/wsproxy/wsproxysdk/*.go) $(DB_GEN_FILES) .swaggo docs/manifest.json coderd/rbac/object_gen.go
647647
./scripts/apidocgen/generate.sh
648648
./scripts/pnpm_install.sh
649-
pnpm exec prettier --write ./docs/api ./docs/manifest.json ./coderd/apidoc/swagger.json
649+
pnpm exec prettier --write ./docs/reference/api ./docs/manifest.json ./coderd/apidoc/swagger.json
650650

651651
update-golden-files: \
652652
cli/testdata/.gen-golden \

‎docs/admin/audit-logs.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -70,14 +70,15 @@ audit trails.
7070

7171
Audit logs can be accessed through our REST API. You can find detailed
7272
information about this in our
73-
[endpoint documentation](../api/audit.md#get-audit-logs).
73+
[endpoint documentation](../reference/api/audit.md#get-audit-logs).
7474

7575
## Service Logs
7676

7777
Audit trails are also dispatched as service logs and can be captured and
7878
categorized using any log management tool such as [Splunk](https://splunk.com).
7979

80-
Example of a [JSON formatted](../cli/server.md#--log-json) audit log entry:
80+
Example of a [JSON formatted](../reference/cli/server.md#--log-json) audit log
81+
entry:
8182

8283
```json
8384
{
@@ -112,7 +113,8 @@ Example of a [JSON formatted](../cli/server.md#--log-json) audit log entry:
112113
}
113114
```
114115

115-
Example of a [human readable](../cli/server.md#--log-human) audit log entry:
116+
Example of a [human readable](../reference/cli/server.md#--log-human) audit log
117+
entry:
116118

117119
```console
118120
2023-06-13 03:43:29.233 [info] coderd: audit_log ID=95f7c392-da3e-480c-a579-8909f145fbe2 Time="2023-06-13T03:43:29.230422Z" UserID=6c405053-27e3-484a-9ad7-bcb64e7bfde6 OrganizationID=00000000-0000-0000-0000-000000000000 Ip=<nil> UserAgent=<nil> ResourceType=workspace_build ResourceID=988ae133-5b73-41e3-a55e-e1e9d3ef0b66 ResourceTarget="" Action=start Diff="{}" StatusCode=200 AdditionalFields="{\"workspace_name\":\"linux-container\",\"build_number\":\"7\",\"build_reason\":\"initiator\",\"workspace_owner\":\"\"}" RequestID=9682b1b5-7b9f-4bf2-9a39-9463f8e41cd6 ResourceIcon=""

‎docs/admin/auth.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ First,
1919
GitHub will ask you for the following Coder parameters:
2020

2121
- **Homepage URL**: Set to your Coder deployments
22-
[`CODER_ACCESS_URL`](../cli/server.md#--access-url) (e.g.
22+
[`CODER_ACCESS_URL`](../reference/cli/server.md#--access-url) (e.g.
2323
`https://coder.domain.com`)
2424
- **User Authorization Callback URL**: Set to `https://coder.domain.com`
2525

‎docs/admin/automation.md

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@ All actions possible through the Coder dashboard can also be automated as it
44
utilizes the same public REST API. There are several ways to extend/automate
55
Coder:
66

7-
- [CLI](../cli.md)
8-
- [REST API](../api/)
7+
- [CLI](../reference/cli/README.md)
8+
- [REST API](../reference/api/README.md)
99
- [Coder SDK](https://pkg.go.dev/github.com/coder/coder/v2/codersdk)
1010

1111
## Quickstart
@@ -32,9 +32,10 @@ curl https://coder.example.com/api/v2/workspaces?q=owner:me \
3232

3333
## Documentation
3434

35-
We publish an [API reference](../api/index.md) in our documentation. You can
36-
also enable a [Swagger endpoint](../cli/server.md#--swagger-enable) on your
37-
Coder deployment.
35+
We publish an [API reference](../reference/api/README.md) in our documentation.
36+
You can also enable a
37+
[Swagger endpoint](../reference/cli/server.md#--swagger-enable) on your Coder
38+
deployment.
3839

3940
## Use cases
4041

@@ -52,8 +53,8 @@ payloads, we recommend checking the CLI and API documentation.
5253
Workspace agents have a special token that can send logs, metrics, and workspace
5354
activity.
5455

55-
- [Custom workspace logs](../api/agents.md#patch-workspace-agent-logs): Expose
56-
messages prior to the Coder init script running (e.g. pulling image, VM
56+
- [Custom workspace logs](../reference/api/agents.md#patch-workspace-agent-logs):
57+
Expose messages prior to the Coder init script running (e.g. pulling image, VM
5758
starting, restoring snapshot).
5859
[coder-logstream-kube](https://github.com/coder/coder-logstream-kube) uses
5960
this to show Kubernetes events, such as image pulls or ResourceQuota
@@ -73,7 +74,7 @@ activity.
7374
}"
7475
```
7576

76-
- [Manually send workspace activity](../api/agents.md#submit-workspace-agent-stats):
77+
- [Manually send workspace activity](../reference/api/agents.md#submit-workspace-agent-stats):
7778
Keep a workspace "active," even if there is not an open connection (e.g. for a
7879
long-running machine learning job).
7980

‎docs/admin/configure.md

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
Coder server's primary configuration is done via environment variables. For a
22
full list of the options, run `coder server --help` or see our
3-
[CLI documentation](../cli/server.md).
3+
[CLI documentation](../reference/cli/server.md).
44

55
## Access URL
66

@@ -48,10 +48,11 @@ If you are providing TLS certificates directly to the Coder server, either
4848
1. Use a single certificate and key for both the root and wildcard domains.
4949
2. Configure multiple certificates and keys via
5050
[`coder.tls.secretNames`](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
51-
in the Helm Chart, or [`--tls-cert-file`](../cli/server.md#--tls-cert-file)
52-
and [`--tls-key-file`](../cli/server.md#--tls-key-file) command line options
53-
(these both take a comma separated list of files; list certificates and their
54-
respective keys in the same order).
51+
in the Helm Chart, or
52+
[`--tls-cert-file`](../reference/cli/server.md#--tls-cert-file) and
53+
[`--tls-key-file`](../reference/cli/server.md#--tls-key-file) command line
54+
options (these both take a comma separated list of files; list certificates
55+
and their respective keys in the same order).
5556

5657
## TLS & Reverse Proxy
5758

‎docs/admin/encryption.md

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ preventing attackers with database access from using them to impersonate users.
77
## How it works
88

99
Coder allows administrators to specify
10-
[external token encryption keys](../cli/server.md#external-token-encryption-keys).
10+
[external token encryption keys](../reference/cli/server.md#external-token-encryption-keys).
1111
If configured, Coder will use these keys to encrypt external user tokens before
1212
storing them in the database. The encryption algorithm used is AES-256-GCM with
1313
a 32-byte key length.
@@ -47,7 +47,7 @@ Additional database fields may be encrypted in the future.
4747
4848
- Ensure you have a valid backup of your database. **Do not skip this step.** If
4949
you are using the built-in PostgreSQL database, you can run
50-
[`coder server postgres-builtin-url`](../cli/server_postgres-builtin-url.md)
50+
[`coder server postgres-builtin-url`](../reference/cli/server_postgres-builtin-url.md)
5151
to get the connection URL.
5252

5353
- Generate a 32-byte random key and base64-encode it. For example:
@@ -90,7 +90,7 @@ if you need to rotate keys, you can perform the following procedure:
9090
- Generate a new encryption key following the same procedure as above.
9191
9292
- Add the above key to the list of
93-
[external token encryption keys](../cli/server.md#--external-token-encryption-keys).
93+
[external token encryption keys](../reference/cli/server.md#--external-token-encryption-keys).
9494
**The new key must appear first in the list**. For example, in the Kubernetes
9595
secret created above:
9696
@@ -110,13 +110,13 @@ data:
110110
encrypted with the old key(s).
111111
112112
- To re-encrypt all encrypted database fields with the new key, run
113-
[`coder server dbcrypt rotate`](../cli/server_dbcrypt_rotate.md). This command
114-
will re-encrypt all tokens with the specified new encryption key. We recommend
115-
performing this action during a maintenance window.
113+
[`coder server dbcrypt rotate`](../reference/cli/server_dbcrypt_rotate.md).
114+
This command will re-encrypt all tokens with the specified new encryption key.
115+
We recommend performing this action during a maintenance window.
116116

117117
> Note: this command requires direct access to the database. If you are using
118118
> the built-in PostgreSQL database, you can run
119-
> [`coder server postgres-builtin-url`](../cli/server_postgres-builtin-url.md)
119+
> [`coder server postgres-builtin-url`](../reference/cli/server_postgres-builtin-url.md)
120120
> to get the connection URL.
121121

122122
- Once the above command completes successfully, remove the old encryption key
@@ -132,8 +132,9 @@ To disable encryption, perform the following actions:
132132
- Stop all active coderd instances. This will prevent new encrypted data from
133133
being written, which may cause the next step to fail.
134134

135-
- Run [`coder server dbcrypt decrypt`](../cli/server_dbcrypt_decrypt.md). This
136-
command will decrypt all encrypted user tokens and revoke all active
135+
- Run
136+
[`coder server dbcrypt decrypt`](../reference/cli/server_dbcrypt_decrypt.md).
137+
This command will decrypt all encrypted user tokens and revoke all active
137138
encryption keys.
138139

139140
> Note: for `decrypt` command, the equivalent environment variable for
@@ -142,7 +143,7 @@ To disable encryption, perform the following actions:
142143
> to help prevent accidentally decrypting data.
143144

144145
- Remove all
145-
[external token encryption keys](../cli/server.md#--external-token-encryption-keys)
146+
[external token encryption keys](../reference/cli/server.md#--external-token-encryption-keys)
146147
from Coder's configuration.
147148

148149
- Start coderd. You can now safely delete the encryption keys from your secret
@@ -159,12 +160,13 @@ To delete all encrypted data from your database, perform the following actions:
159160
- Stop all active coderd instances. This will prevent new encrypted data from
160161
being written.
161162

162-
- Run [`coder server dbcrypt delete`](../cli/server_dbcrypt_delete.md). This
163-
command will delete all encrypted user tokens and revoke all active encryption
164-
keys.
163+
- Run
164+
[`coder server dbcrypt delete`](../reference/cli/server_dbcrypt_delete.md).
165+
This command will delete all encrypted user tokens and revoke all active
166+
encryption keys.
165167

166168
- Remove all
167-
[external token encryption keys](../cli/server.md#--external-token-encryption-keys)
169+
[external token encryption keys](../reference/cli/server.md#--external-token-encryption-keys)
168170
from Coder's configuration.
169171

170172
- Start coderd. You can now safely delete the encryption keys from your secret

‎docs/admin/healthcheck.md

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ Coder includes an operator-friendly deployment health page that provides a
44
number of details about the health of your Coder deployment.
55

66
You can view it at `https://${CODER_URL}/health`, or you can alternatively view
7-
the [JSON response directly](../api/debug.md#debug-info-deployment-health).
7+
the
8+
[JSON response directly](../reference/api/debug.md#debug-info-deployment-health).
89

910
The deployment health page is broken up into the following sections:
1011

@@ -106,8 +107,8 @@ query fails.
106107
_Database Latency High_
107108

108109
**Problem:** This code is returned if the median latency is higher than the
109-
[configured threshold](../cli/server.md#--health-check-threshold-database). This
110-
may not be an error as such, but is an indication of a potential issue.
110+
[configured threshold](../reference/cli/server.md#--health-check-threshold-database).
111+
This may not be an error as such, but is an indication of a potential issue.
111112

112113
**Solution:** Investigate the sizing of the configured database with regard to
113114
Coder's current activity and usage. It may be necessary to increase the
@@ -117,18 +118,19 @@ configured threshold to a higher value (this will not address the root cause).
117118
> [!TIP]
118119
>
119120
> - You can enable
120-
> [detailed database metrics](../cli/server.md#--prometheus-collect-db-metrics)
121+
> [detailed database metrics](../reference/cli/server.md#--prometheus-collect-db-metrics)
121122
> in Coder's Prometheus endpoint.
122-
> - If you have [tracing enabled](../cli/server.md#--trace), these traces may
123-
> also contain useful information regarding Coder's database activity.
123+
> - If you have [tracing enabled](../reference/cli/server.md#--trace), these
124+
> traces may also contain useful information regarding Coder's database
125+
> activity.
124126
125127
## DERP
126128

127129
Coder workspace agents may use
128130
[DERP (Designated Encrypted Relay for Packets)](https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp)
129131
to communicate with Coder. This requires connectivity to a number of configured
130-
[DERP servers](../cli/server.md#--derp-config-path) which are used to relay
131-
traffic between Coder and workspace agents. Coder periodically queries the
132+
[DERP servers](../reference/cli/server.md#--derp-config-path) which are used to
133+
relay traffic between Coder and workspace agents. Coder periodically queries the
132134
health of its configured DERP servers and may return one or more of the
133135
following:
134136

@@ -146,7 +148,7 @@ misconfigured reverse HTTP proxy. Additionally, while workspace users should
146148
still be able to reach their workspaces, connection performance may be degraded.
147149

148150
> **Note:** This may also be shown if you have
149-
> [forced websocket connections for DERP](../cli/server.md#--derp-force-websockets).
151+
> [forced websocket connections for DERP](../reference/cli/server.md#--derp-force-websockets).
150152
151153
**Solution:** ensure that any proxies you use allow connection upgrade with the
152154
`Upgrade: derp` header.
@@ -179,9 +181,9 @@ to establish [direct connections](../networking/stun.md). Without at least one
179181
working STUN server, direct connections may not be possible.
180182

181183
**Solution:** Ensure that the
182-
[configured STUN severs](../cli/server.md#derp-server-stun-addresses) are
183-
reachable from Coder and that UDP traffic can be sent/received on the configured
184-
port.
184+
[configured STUN severs](../reference/cli/server.md#derp-server-stun-addresses)
185+
are reachable from Coder and that UDP traffic can be sent/received on the
186+
configured port.
185187

186188
### ESTUN02
187189

@@ -292,8 +294,8 @@ be built until there is at least one provisioner daemon running.
292294
If you are using
293295
[External Provisioner Daemons](./provisioners.md#external-provisioners), ensure
294296
that they are able to successfully connect to Coder. Otherwise, ensure
295-
[`--provisioner-daemons`](../cli/server.md#provisioner-daemons) is set to a
296-
value greater than 0.
297+
[`--provisioner-daemons`](../reference/cli/server.md#provisioner-daemons) is set
298+
to a value greater than 0.
297299

298300
> Note: This may be a transient issue if you are currently in the process of
299301
> updating your deployment.

0 commit comments

Comments
 (0)