Skip to content

docs: move api and cli docs routes to reference/ #14241

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 16 commits into from
Aug 13, 2024
Merged

docs: move api and cli docs routes to reference/ #14241

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
0626843
docs: move api and cli docs under reference
matifali Aug 12, 2024
b9ee217
fix manifest
matifali Aug 12, 2024
e3638a4
fixup!
matifali Aug 12, 2024
2cfff89
rebase
matifali Aug 13, 2024
ebd6a59
fixup Links
matifali Aug 13, 2024
0e07655
`make fmt`
matifali Aug 13, 2024
cc226a8
more fixing
matifali Aug 13, 2024
a358cc3
more links
matifali Aug 13, 2024
e4c7fa6
api docgen fixes
matifali Aug 13, 2024
212d428
fix cli subcommand paths
matifali Aug 13, 2024
8bc175e
fmt
matifali Aug 13, 2024
8450415
fix more links
matifali Aug 13, 2024
219d1ae
fmt
matifali Aug 13, 2024
9d87ecb
docs: move api and cli docs under reference
matifali Aug 12, 2024
a0efc99
fix links
matifali Aug 12, 2024
4f098d0
`fmt` & `gen`
matifali Aug 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
fixup Links
  • Loading branch information
@matifali
matifali committed Aug 13, 2024
commit ebd6a5982eb13a00b02806dd6d61f68bc7d10d98
4 changes: 2 additions & 2 deletions docs/admin/audit-logs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ information about this in our
Audit trails are also dispatched as service logs and can be captured and
categorized using any log management tool such as [Splunk](https://splunk.com).

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

```json
{
Expand Down Expand Up @@ -112,7 +112,7 @@ Example of a [JSON formatted](../cli/server.md#--log-json) audit log entry:
}
```

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

```console
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=""
Expand Down
2 changes: 1 addition & 1 deletion docs/admin/auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ First,
GitHub will ask you for the following Coder parameters:

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

Expand Down
2 changes: 1 addition & 1 deletion docs/admin/automation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ curl https://coder.example.com/api/v2/workspaces?q=owner:me \
## Documentation

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

## Use cases
Expand Down
4 changes: 2 additions & 2 deletions docs/admin/configure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,8 @@ If you are providing TLS certificates directly to the Coder server, either
1. Use a single certificate and key for both the root and wildcard domains.
2. Configure multiple certificates and keys via
[`coder.tls.secretNames`](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
in the Helm Chart, or [`--tls-cert-file`](../cli/server.md#--tls-cert-file)
and [`--tls-key-file`](../cli/server.md#--tls-key-file) command line options
in the Helm Chart, or [`--tls-cert-file`](../reference/cli/server.md#--tls-cert-file)
and [`--tls-key-file`](../reference/cli/server.md#--tls-key-file) command line options
(these both take a comma separated list of files; list certificates and their
respective keys in the same order).

Expand Down
8 changes: 4 additions & 4 deletions docs/admin/encryption.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ preventing attackers with database access from using them to impersonate users.
## How it works

Coder allows administrators to specify
[external token encryption keys](../cli/server.md#external-token-encryption-keys).
[external token encryption keys](../reference/cli/server.md#external-token-encryption-keys).
If configured, Coder will use these keys to encrypt external user tokens before
storing them in the database. The encryption algorithm used is AES-256-GCM with
a 32-byte key length.
Expand Down Expand Up @@ -90,7 +90,7 @@ if you need to rotate keys, you can perform the following procedure:
- Generate a new encryption key following the same procedure as above.

- Add the above key to the list of
[external token encryption keys](../cli/server.md#--external-token-encryption-keys).
[external token encryption keys](../reference/cli/server.md#--external-token-encryption-keys).
**The new key must appear first in the list**. For example, in the Kubernetes
secret created above:

Expand Down Expand Up @@ -142,7 +142,7 @@ To disable encryption, perform the following actions:
> to help prevent accidentally decrypting data.

- Remove all
[external token encryption keys](../cli/server.md#--external-token-encryption-keys)
[external token encryption keys](../reference/cli/server.md#--external-token-encryption-keys)
from Coder's configuration.

- Start coderd. You can now safely delete the encryption keys from your secret
Expand All @@ -164,7 +164,7 @@ To delete all encrypted data from your database, perform the following actions:
keys.

- Remove all
[external token encryption keys](../cli/server.md#--external-token-encryption-keys)
[external token encryption keys](../reference/cli/server.md#--external-token-encryption-keys)
from Coder's configuration.

- Start coderd. You can now safely delete the encryption keys from your secret
Expand Down
14 changes: 7 additions & 7 deletions docs/admin/healthcheck.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ query fails.
_Database Latency High_

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

**Solution:** Investigate the sizing of the configured database with regard to
Expand All @@ -117,17 +117,17 @@ configured threshold to a higher value (this will not address the root cause).
> [!TIP]
>
> - You can enable
> [detailed database metrics](../cli/server.md#--prometheus-collect-db-metrics)
> [detailed database metrics](../reference/cli/server.md#--prometheus-collect-db-metrics)
> in Coder's Prometheus endpoint.
> - If you have [tracing enabled](../cli/server.md#--trace), these traces may
> - If you have [tracing enabled](../reference/cli/server.md#--trace), these traces may
> also contain useful information regarding Coder's database activity.

## DERP

Coder workspace agents may use
[DERP (Designated Encrypted Relay for Packets)](https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp)
to communicate with Coder. This requires connectivity to a number of configured
[DERP servers](../cli/server.md#--derp-config-path) which are used to relay
[DERP servers](../reference/cli/server.md#--derp-config-path) which are used to relay
traffic between Coder and workspace agents. Coder periodically queries the
health of its configured DERP servers and may return one or more of the
following:
Expand All @@ -146,7 +146,7 @@ misconfigured reverse HTTP proxy. Additionally, while workspace users should
still be able to reach their workspaces, connection performance may be degraded.

> **Note:** This may also be shown if you have
> [forced websocket connections for DERP](../cli/server.md#--derp-force-websockets).
> [forced websocket connections for DERP](../reference/cli/server.md#--derp-force-websockets).

**Solution:** ensure that any proxies you use allow connection upgrade with the
`Upgrade: derp` header.
Expand Down Expand Up @@ -179,7 +179,7 @@ to establish [direct connections](../networking/stun.md). Without at least one
working STUN server, direct connections may not be possible.

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

Expand Down Expand Up @@ -292,7 +292,7 @@ be built until there is at least one provisioner daemon running.
If you are using
[External Provisioner Daemons](./provisioners.md#external-provisioners), ensure
that they are able to successfully connect to Coder. Otherwise, ensure
[`--provisioner-daemons`](../cli/server.md#provisioner-daemons) is set to a
[`--provisioner-daemons`](../reference/cli/server.md#provisioner-daemons) is set to a
value greater than 0.

> Note: This may be a transient issue if you are currently in the process of
Expand Down
20 changes: 10 additions & 10 deletions docs/admin/provisioners.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# External provisioners

By default, the Coder server runs
[built-in provisioner daemons](../cli/server.md#provisioner-daemons), which
execute `terraform` during workspace and template builds. However, there are
sometimes benefits to running external provisioner daemons:
[built-in provisioner daemons](../reference/cli/server.md#provisioner-daemons),
which execute `terraform` during workspace and template builds. However, there
are sometimes benefits to running external provisioner daemons:

- **Secure build environments:** Run build jobs in isolated containers,
preventing malicious templates from gaining shell access to the Coder host.
Expand Down Expand Up @@ -33,7 +33,7 @@ Provisioners are started with the
The provisioner daemon must authenticate with your Coder deployment.

Set a
[provisioner daemon pre-shared key (PSK)](../cli/server.md#--provisioner-daemon-psk)
[provisioner daemon pre-shared key (PSK)](../reference/cli/server.md#--provisioner-daemon-psk)
on the Coder server and start the provisioner with
`coder provisionerd start --psk <your-psk>`. If you are
[installing with Helm](../install/kubernetes.md#install-coder-with-helm), see
Expand All @@ -49,17 +49,17 @@ the [Helm example](#example-running-an-external-provisioner-with-helm) below.

Provisioners can broadly be categorized by scope: `organization` or `user`. The
scope of a provisioner can be specified with
[`-tag=scope=<scope>`](../cli/provisionerd_start.md#t---tag) when starting the
provisioner daemon. Only users with at least the
[`-tag=scope=<scope>`](../reference/cli/provisionerd_start.md#t---tag) when
starting the provisioner daemon. Only users with at least the
[Template Admin](../admin/users.md#roles) role or higher may create
organization-scoped provisioner daemons.

There are two exceptions:

- [Built-in provisioners](../cli/server.md#provisioner-daemons) are always
organization-scoped.
- [Built-in provisioners](../reference/cli/server.md#provisioner-daemons) are
always organization-scoped.
- External provisioners started using a
[pre-shared key (PSK)](../cli/provisionerd_start.md#psk) are always
[pre-shared key (PSK)](../reference/cli/provisionerd_start.md#psk) are always
organization-scoped.

### Organization-Scoped Provisioners
Expand Down Expand Up @@ -270,7 +270,7 @@ docker run --rm -it \

As mentioned above, the Coder server will run built-in provisioners by default.
This can be disabled with a server-wide
[flag or environment variable](../cli/server.md#provisioner-daemons).
[flag or environment variable](../reference/cli/server.md#provisioner-daemons).

```shell
coder server --provisioner-daemons=0
Expand Down
56 changes: 28 additions & 28 deletions docs/guides/support-bundle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,32 +34,32 @@ A brief overview of all files contained in the bundle is provided below:
> Note: detailed descriptions of all the information available in the bundle is
> out of scope, as support bundles are primarily intended for internal use.

| Filename | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------ |
| `agent/agent.json` | The agent used to connect to the workspace with environment variables stripped. |
| `agent/agent_magicsock.html` | The contents of the HTTP debug endpoint of the agent's Tailscale connection. |
| `agent/client_magicsock.html` | The contents of the HTTP debug endpoint of the client's Tailscale connection. |
| `agent/listening_ports.json` | The listening ports detected by the selected agent running in the workspace. |
| `agent/logs.txt` | The logs of the selected agent running in the workspace. |
| `agent/manifest.json` | The manifest of the selected agent with environment variables stripped. |
| `agent/startup_logs.txt` | Startup logs of the workspace agent. |
| `agent/prometheus.txt` | The contents of the agent's Prometheus endpoint. |
| `cli_logs.txt` | Logs from running the `coder support bundle` command. |
| `deployment/buildinfo.json` | Coder version and build information. |
| `deployment/config.json` | Deployment [configuration](../api/general.md#get-deployment-config), with secret values removed. |
| `deployment/experiments.json` | Any [experiments](../cli/server.md#experiments) currently enabled for the deployment. |
| `deployment/health.json` | A snapshot of the [health status](../admin/healthcheck.md) of the deployment. |
| `logs.txt` | Logs from the `codersdk.Client` used to generate the bundle. |
| `network/connection_info.json` | Information used by workspace agents used to connect to Coder (DERP map etc.) |
| `network/coordinator_debug.html` | Peers currently connected to each Coder instance and the tunnels established between peers. |
| `network/netcheck.json` | Results of running `coder netcheck` locally. |
| `network/tailnet_debug.html` | Tailnet coordinators, their heartbeat ages, connected peers, and tunnels. |
| `workspace/build_logs.txt` | Build logs of the selected workspace. |
| `workspace/workspace.json` | Details of the selected workspace. |
| `workspace/parameters.json` | Build parameters of the selected workspace. |
| `workspace/template.json` | The template currently in use by the selected workspace. |
| `workspace/template_file.zip` | The source code of the template currently in use by the selected workspace. |
| `workspace/template_version.json` | The template version currently in use by the selected workspace. |
| Filename | Description |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `agent/agent.json` | The agent used to connect to the workspace with environment variables stripped. |
| `agent/agent_magicsock.html` | The contents of the HTTP debug endpoint of the agent's Tailscale connection. |
| `agent/client_magicsock.html` | The contents of the HTTP debug endpoint of the client's Tailscale connection. |
| `agent/listening_ports.json` | The listening ports detected by the selected agent running in the workspace. |
| `agent/logs.txt` | The logs of the selected agent running in the workspace. |
| `agent/manifest.json` | The manifest of the selected agent with environment variables stripped. |
| `agent/startup_logs.txt` | Startup logs of the workspace agent. |
| `agent/prometheus.txt` | The contents of the agent's Prometheus endpoint. |
| `cli_logs.txt` | Logs from running the `coder support bundle` command. |
| `deployment/buildinfo.json` | Coder version and build information. |
| `deployment/config.json` | Deployment [configuration](../reference/api/general.md#get-deployment-config), with secret values removed. |
| `deployment/experiments.json` | Any [experiments](../reference/cli/server.md#experiments) currently enabled for the deployment. |
| `deployment/health.json` | A snapshot of the [health status](../admin/healthcheck.md) of the deployment. |
| `logs.txt` | Logs from the `codersdk.Client` used to generate the bundle. |
| `network/connection_info.json` | Information used by workspace agents used to connect to Coder (DERP map etc.) |
| `network/coordinator_debug.html` | Peers currently connected to each Coder instance and the tunnels established between peers. |
| `network/netcheck.json` | Results of running `coder netcheck` locally. |
| `network/tailnet_debug.html` | Tailnet coordinators, their heartbeat ages, connected peers, and tunnels. |
| `workspace/build_logs.txt` | Build logs of the selected workspace. |
| `workspace/workspace.json` | Details of the selected workspace. |
| `workspace/parameters.json` | Build parameters of the selected workspace. |
| `workspace/template.json` | The template currently in use by the selected workspace. |
| `workspace/template_file.zip` | The source code of the template currently in use by the selected workspace. |
| `workspace/template_version.json` | The template version currently in use by the selected workspace. |

## How do I generate a Support Bundle?

Expand All @@ -72,8 +72,8 @@ A brief overview of all files contained in the bundle is provided below:
> Note: It is recommended to generate a support bundle from a location
> experiencing workspace connectivity issues.

3. Ensure you are [logged in](../cli/login.md#login) to your Coder deployment as
a user with the Owner privilege.
3. Ensure you are [logged in](../reference/cli/login.md#login) to your Coder
deployment as a user with the Owner privilege.

4. Run `coder support bundle [owner/workspace]`, and respond `yes` to the
prompt. The support bundle will be generated in the current directory with
Expand Down
Loading