mirror of
https://github.com/coder/coder.git
synced 2025-07-23 21:32:07 +00:00
chore(docs): update docs for correct use of shell and console and enforce linewidth (#9245)
This commit is contained in:
committed by
GitHub
parent
ed2b1236c0
commit
d37f6d80f7
@ -1,23 +1,26 @@
|
||||
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](../cli/server.md).
|
||||
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](../cli/server.md).
|
||||
|
||||
## Access URL
|
||||
|
||||
`CODER_ACCESS_URL` is required if you are not using the tunnel. Set this to the external URL
|
||||
that users and workspaces use to connect to Coder (e.g. <https://coder.example.com>). This
|
||||
should not be localhost.
|
||||
`CODER_ACCESS_URL` is required if you are not using the tunnel. Set this to the
|
||||
external URL that users and workspaces use to connect to Coder (e.g.
|
||||
<https://coder.example.com>). This should not be localhost.
|
||||
|
||||
> Access URL should be a external IP address or domain with DNS records pointing to Coder.
|
||||
> Access URL should be a external IP address or domain with DNS records pointing
|
||||
> to Coder.
|
||||
|
||||
### Tunnel
|
||||
|
||||
If an access URL is not specified, Coder will create
|
||||
a publicly accessible URL to reverse proxy your deployment for simple setup.
|
||||
If an access URL is not specified, Coder will create a publicly accessible URL
|
||||
to reverse proxy your deployment for simple setup.
|
||||
|
||||
## Address
|
||||
|
||||
You can change which port(s) Coder listens on.
|
||||
|
||||
```sh
|
||||
```shell
|
||||
# Listen on port 80
|
||||
export CODER_HTTP_ADDRESS=0.0.0.0:80
|
||||
|
||||
@ -34,22 +37,27 @@ coder server
|
||||
|
||||
## Wildcard access URL
|
||||
|
||||
`CODER_WILDCARD_ACCESS_URL` is necessary for [port forwarding](../networking/port-forwarding.md#dashboard)
|
||||
via the dashboard or running [coder_apps](../templates/index.md#coder-apps) on an absolute path. Set this to a wildcard
|
||||
subdomain that resolves to Coder (e.g. `*.coder.example.com`).
|
||||
`CODER_WILDCARD_ACCESS_URL` is necessary for
|
||||
[port forwarding](../networking/port-forwarding.md#dashboard) via the dashboard
|
||||
or running [coder_apps](../templates/index.md#coder-apps) on an absolute path.
|
||||
Set this to a wildcard subdomain that resolves to Coder (e.g.
|
||||
`*.coder.example.com`).
|
||||
|
||||
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 (these both take a comma separated list of files; list certificates and their respective keys in the
|
||||
same order).
|
||||
[`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
|
||||
(these both take a comma separated list of files; list certificates and their
|
||||
respective keys in the same order).
|
||||
|
||||
## TLS & Reverse Proxy
|
||||
|
||||
The Coder server can directly use TLS certificates with `CODER_TLS_ENABLE` and accompanying configuration flags. However, Coder can also run behind a reverse-proxy to terminate TLS certificates from LetsEncrypt, for example.
|
||||
The Coder server can directly use TLS certificates with `CODER_TLS_ENABLE` and
|
||||
accompanying configuration flags. However, Coder can also run behind a
|
||||
reverse-proxy to terminate TLS certificates from LetsEncrypt, for example.
|
||||
|
||||
- [Apache](https://github.com/coder/coder/tree/main/examples/web-server/apache)
|
||||
- [Caddy](https://github.com/coder/coder/tree/main/examples/web-server/caddy)
|
||||
@ -57,17 +65,19 @@ The Coder server can directly use TLS certificates with `CODER_TLS_ENABLE` and a
|
||||
|
||||
### Kubernetes TLS configuration
|
||||
|
||||
Below are the steps to configure Coder to terminate TLS when running on Kubernetes.
|
||||
You must have the certificate `.key` and `.crt` files in your working directory prior to step 1.
|
||||
Below are the steps to configure Coder to terminate TLS when running on
|
||||
Kubernetes. You must have the certificate `.key` and `.crt` files in your
|
||||
working directory prior to step 1.
|
||||
|
||||
1. Create the TLS secret in your Kubernetes cluster
|
||||
|
||||
```console
|
||||
```shell
|
||||
kubectl create secret tls coder-tls -n <coder-namespace> --key="tls.key" --cert="tls.crt"
|
||||
```
|
||||
|
||||
> You can use a single certificate for the both the access URL and wildcard access URL.
|
||||
> The certificate CN must match the wildcard domain, such as `*.example.coder.com`.
|
||||
> You can use a single certificate for the both the access URL and wildcard
|
||||
> access URL. The certificate CN must match the wildcard domain, such as
|
||||
> `*.example.coder.com`.
|
||||
|
||||
1. Reference the TLS secret in your Coder Helm chart values
|
||||
|
||||
@ -87,14 +97,16 @@ coder:
|
||||
|
||||
## PostgreSQL Database
|
||||
|
||||
Coder uses a PostgreSQL database to store users, workspace metadata, and other deployment information.
|
||||
Use `CODER_PG_CONNECTION_URL` to set the database that Coder connects to. If unset, PostgreSQL binaries will be
|
||||
downloaded from Maven (<https://repo1.maven.org/maven2>) and store all data in the config root.
|
||||
Coder uses a PostgreSQL database to store users, workspace metadata, and other
|
||||
deployment information. Use `CODER_PG_CONNECTION_URL` to set the database that
|
||||
Coder connects to. If unset, PostgreSQL binaries will be downloaded from Maven
|
||||
(<https://repo1.maven.org/maven2>) and store all data in the config root.
|
||||
|
||||
> Postgres 13 is the minimum supported version.
|
||||
|
||||
If you are using the built-in PostgreSQL deployment and need to use `psql` (aka
|
||||
the PostgreSQL interactive terminal), output the connection URL with the following command:
|
||||
the PostgreSQL interactive terminal), output the connection URL with the
|
||||
following command:
|
||||
|
||||
```console
|
||||
coder server postgres-builtin-url
|
||||
@ -103,21 +115,26 @@ psql "postgres://coder@localhost:49627/coder?sslmode=disable&password=feU...yI1"
|
||||
|
||||
### Migrating from the built-in database to an external database
|
||||
|
||||
To migrate from the built-in database to an external database, follow these steps:
|
||||
To migrate from the built-in database to an external database, follow these
|
||||
steps:
|
||||
|
||||
1. Stop your Coder deployment.
|
||||
2. Run `coder server postgres-builtin-serve` in a background terminal.
|
||||
3. Run `coder server postgres-builtin-url` and copy its output command.
|
||||
4. Run `pg_dump <built-in-connection-string> > coder.sql` to dump the internal database to a file.
|
||||
5. Restore that content to an external database with `psql <external-connection-string> < coder.sql`.
|
||||
6. Start your Coder deployment with `CODER_PG_CONNECTION_URL=<external-connection-string>`.
|
||||
4. Run `pg_dump <built-in-connection-string> > coder.sql` to dump the internal
|
||||
database to a file.
|
||||
5. Restore that content to an external database with
|
||||
`psql <external-connection-string> < coder.sql`.
|
||||
6. Start your Coder deployment with
|
||||
`CODER_PG_CONNECTION_URL=<external-connection-string>`.
|
||||
|
||||
## System packages
|
||||
|
||||
If you've installed Coder via a [system package](../install/packages.md) Coder, you can
|
||||
configure the server by setting the following variables in `/etc/coder.d/coder.env`:
|
||||
If you've installed Coder via a [system package](../install/packages.md) Coder,
|
||||
you can configure the server by setting the following variables in
|
||||
`/etc/coder.d/coder.env`:
|
||||
|
||||
```console
|
||||
```env
|
||||
# String. Specifies the external URL (HTTP/S) to access Coder.
|
||||
CODER_ACCESS_URL=https://coder.example.com
|
||||
|
||||
@ -145,7 +162,7 @@ CODER_TLS_KEY_FILE=
|
||||
|
||||
To run Coder as a system service on the host:
|
||||
|
||||
```console
|
||||
```shell
|
||||
# Use systemd to start Coder now and on reboot
|
||||
sudo systemctl enable --now coder
|
||||
|
||||
@ -155,15 +172,15 @@ journalctl -u coder.service -b
|
||||
|
||||
To restart Coder after applying system changes:
|
||||
|
||||
```console
|
||||
```shell
|
||||
sudo systemctl restart coder
|
||||
```
|
||||
|
||||
## Configuring Coder behind a proxy
|
||||
|
||||
To configure Coder behind a corporate proxy, set the environment variables `HTTP_PROXY` and
|
||||
`HTTPS_PROXY`. Be sure to restart the server. Lowercase values (e.g. `http_proxy`) are also
|
||||
respected in this case.
|
||||
To configure Coder behind a corporate proxy, set the environment variables
|
||||
`HTTP_PROXY` and `HTTPS_PROXY`. Be sure to restart the server. Lowercase values
|
||||
(e.g. `http_proxy`) are also respected in this case.
|
||||
|
||||
## Up Next
|
||||
|
||||
|
Reference in New Issue
Block a user