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
make fmt
  • Loading branch information
@matifali
matifali committed Aug 13, 2024
commit 0e076557ac868a444cd1f88b76254fa57e8c2346
6 changes: 4 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,8 @@ 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](../reference/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 +113,8 @@ Example of a [JSON formatted](../reference/cli/server.md#--log-json) audit log e
}
```

Example of a [human readable](../reference/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
4 changes: 2 additions & 2 deletions docs/admin/automation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ 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](../reference/cli/server.md#--swagger-enable) on your
Coder deployment.
also enable a [Swagger endpoint](../reference/cli/server.md#--swagger-enable) on
your Coder deployment.

## Use cases

Expand Down
9 changes: 5 additions & 4 deletions docs/admin/configure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,10 +48,11 @@ 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`](../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).
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).

## TLS & Reverse Proxy

Expand Down
23 changes: 12 additions & 11 deletions docs/admin/healthcheck.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,8 +106,8 @@ query fails.
_Database Latency High_

**Problem:** This code is returned if the median latency is higher than the
[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.
[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
Coder's current activity and usage. It may be necessary to increase the
Expand All @@ -119,16 +119,17 @@ configured threshold to a higher value (this will not address the root cause).
> - You can enable
> [detailed database metrics](../reference/cli/server.md#--prometheus-collect-db-metrics)
> in Coder's Prometheus endpoint.
> - If you have [tracing enabled](../reference/cli/server.md#--trace), these traces may
> also contain useful information regarding Coder's database activity.
> - 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](../reference/cli/server.md#--derp-config-path) which are used to relay
traffic between Coder and workspace agents. Coder periodically queries the
[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 Down Expand Up @@ -179,9 +180,9 @@ 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](../reference/cli/server.md#derp-server-stun-addresses) are
reachable from Coder and that UDP traffic can be sent/received on the configured
port.
[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.

### ESTUN02

Expand Down Expand Up @@ -292,8 +293,8 @@ 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`](../reference/cli/server.md#provisioner-daemons) is set to a
value greater than 0.
[`--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
> updating your deployment.
Expand Down
22 changes: 11 additions & 11 deletions docs/install/offline.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,15 @@ environments. However, some changes to your configuration are necessary.
> This is a general comparison. Keep reading for a full tutorial running Coder
> offline with Kubernetes or Docker.

| | Public deployments | Offline deployments |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Terraform binary | By default, Coder downloads Terraform binary from [releases.hashicorp.com](https://releases.hashicorp.com) | Terraform binary must be included in `PATH` for the VM or container image. [Supported versions](https://github.com/coder/coder/blob/main/provisioner/terraform/install.go#L23-L24) |
| Terraform registry | Coder templates will attempt to download providers from [registry.terraform.io](https://registry.terraform.io) or [custom source addresses](https://developer.hashicorp.com/terraform/language/providers/requirements#source-addresses) specified in each template | [Custom source addresses](https://developer.hashicorp.com/terraform/language/providers/requirements#source-addresses) can be specified in each Coder template, or a custom registry/mirror can be used. More details below |
| | Public deployments | Offline deployments |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Terraform binary | By default, Coder downloads Terraform binary from [releases.hashicorp.com](https://releases.hashicorp.com) | Terraform binary must be included in `PATH` for the VM or container image. [Supported versions](https://github.com/coder/coder/blob/main/provisioner/terraform/install.go#L23-L24) |
| Terraform registry | Coder templates will attempt to download providers from [registry.terraform.io](https://registry.terraform.io) or [custom source addresses](https://developer.hashicorp.com/terraform/language/providers/requirements#source-addresses) specified in each template | [Custom source addresses](https://developer.hashicorp.com/terraform/language/providers/requirements#source-addresses) can be specified in each Coder template, or a custom registry/mirror can be used. More details below |
| STUN | By default, Coder uses Google's public STUN server for direct workspace connections | STUN can be safely [disabled](../reference/ users can still connect via [relayed connections](../networking/index.md#-geo-distribution). Alternatively, you can set a [custom DERP server](../reference/cli/server.md#--derp-server-stun-addresses) |
| DERP | By default, Coder's built-in DERP relay can be used, or [Tailscale's public relays](../networking/index.md#relayed-connections). | By default, Coder's built-in DERP relay can be used, or [custom relays](../networking/index.md#custom-relays). |
| PostgreSQL | If no [PostgreSQL connection URL](../reference/cli/server.md#--postgres-url) is specified, Coder will download Postgres from [repo1.maven.org](https://repo1.maven.org) | An external database is required, you must specify a [PostgreSQL connection URL](../reference/cli/server.md#--postgres-url) |
| Telemetry | Telemetry is on by default, and [can be disabled](../reference/cli/server.md#--telemetry) | Telemetry [can be disabled](../reference/cli/server.md#--telemetry) |
| Update check | By default, Coder checks for updates from [GitHub releases](https:/github.com/coder/coder/releases) | Update checks [can be disabled](../reference/cli/server.md#--update-check) |
| DERP | By default, Coder's built-in DERP relay can be used, or [Tailscale's public relays](../networking/index.md#relayed-connections). | By default, Coder's built-in DERP relay can be used, or [custom relays](../networking/index.md#custom-relays). |
| PostgreSQL | If no [PostgreSQL connection URL](../reference/cli/server.md#--postgres-url) is specified, Coder will download Postgres from [repo1.maven.org](https://repo1.maven.org) | An external database is required, you must specify a [PostgreSQL connection URL](../reference/cli/server.md#--postgres-url) |
| Telemetry | Telemetry is on by default, and [can be disabled](../reference/cli/server.md#--telemetry) | Telemetry [can be disabled](../reference/cli/server.md#--telemetry) |
| Update check | By default, Coder checks for updates from [GitHub releases](https:/github.com/coder/coder/releases) | Update checks [can be disabled](../reference/cli/server.md#--update-check) |

## Offline container images

Expand Down Expand Up @@ -223,9 +223,9 @@ server, as demonstrated in the example below:
3. Extract the file and move its contents to your server folder.
4. If you are using NodeJS, you can execute the following command:
`cd docs && npx http-server .`
5. Set the [CODER_DOCS_URL](../reference/cli/server.md#--docs-url) environment variable to
use the URL of your hosted docs. This way, the Coder UI will reference the
documentation from your specified URL.
5. Set the [CODER_DOCS_URL](../reference/cli/server.md#--docs-url) environment
variable to use the URL of your hosted docs. This way, the Coder UI will
reference the documentation from your specified URL.

With these steps, you'll have the Coder documentation hosted on your server and
accessible for your team to use.
Expand Down