Files
coder/docs/admin/setup/index.md
T

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

171 lines
6.2 KiB
Markdown
Raw Normal View History

---
title: Configure control plane access
---
2024-10-05 08:52:04 -07:00
Coder server's primary configuration is done via environment variables. For a
full list of the options, run `coder server --help` or see our
2024-10-05 08:52:04 -07:00
[CLI documentation](../../reference/cli/server.md).
> [!TIP]
> Need to look up an exact environment variable, CLI flag, or YAML key for a
> setting? See the [configuration reference](./configuration-reference.md) for
> a searchable list of every option.
2022-09-08 15:41:00 -04:00
## 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.
2022-09-08 15:41:00 -04:00
Access URL should be an external IP address or domain with DNS records pointing to Coder.
2022-10-07 08:05:56 -05:00
### Tunnel
If an access URL is not specified, Coder will create a publicly accessible URL
to reverse proxy your deployment for simple setup.
2022-10-07 08:05:56 -05:00
## Address
You can change which port(s) Coder listens on.
```sh
# Listen on port 80
export CODER_HTTP_ADDRESS=0.0.0.0:80
# Enable TLS and listen on port 443)
export CODER_TLS_ENABLE=true
export CODER_TLS_ADDRESS=0.0.0.0:443
## Redirect from HTTP to HTTPS
export CODER_REDIRECT_TO_ACCESS_URL=true
# Start the Coder server
coder server
```
2022-09-26 11:56:17 -03:00
## Wildcard access URL
> [!TIP]
> Learn more about the [importance and benefits of wildcard access URLs](../networking/wildcard-access-url.md)
`CODER_WILDCARD_ACCESS_URL` is necessary for [port forwarding](../networking/port-forwarding.md#dashboard) via the dashboard or running [coder_apps](../templates/index.md) on an absolute path.
Set it to a wildcard hostname that resolves to Coder, such as `*.coder.example.com` or `*-coder.example.com`.
The suffix form creates application hostnames such as `8080--main--myworkspace--john-coder.example.com`.
It requires a DNS record and TLS certificate for `*.example.com`.
2022-09-26 11:56:17 -03:00
> [!NOTE]
> We do not recommend using a top-level-domain for Coder wildcard access
> (for example `*.workspaces`), even on private networks with split-DNS. Some
> browsers consider these "public" domains and will refuse Coder's cookies,
> which are vital to the proper operation of this feature.
2023-05-31 10:10:30 +04:00
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.
1. Configure multiple certificates and keys via
[`coder.tls.secretNames`](../../../helm/coder/values.yaml)
in the Helm Chart, or
2024-10-05 08:52:04 -07:00
[`--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).
2022-09-26 11:56:17 -03:00
After you enable the wildcard access URL, you should [disable path-based apps](../../tutorials/best-practices/security-best-practices.md#disable-path-based-apps) for security.
## 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.
- [Apache](../../tutorials/reverse-proxy-apache.md)
- [Caddy](../../tutorials/reverse-proxy-caddy.md)
- [NGINX](../../tutorials/reverse-proxy-nginx.md)
2023-08-09 17:00:22 -04:00
### 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.
2023-08-09 17:00:22 -04:00
1. Create the TLS secret in your Kubernetes cluster
```sh
kubectl create secret tls coder-tls -n <coder-namespace> --key="tls.key" --cert="tls.crt"
```
2023-08-09 17:00:22 -04:00
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`.
2023-08-09 17:00:22 -04:00
1. Reference the TLS secret in your Coder Helm chart values
```yaml
coder:
tls:
secretNames:
- coder-tls
2023-08-09 17:00:22 -04:00
# Alternatively, if you use an Ingress controller to terminate TLS,
# set the following values:
ingress:
enable: true
tls:
enable: true
secretName: coder-tls
wildcardSecretName: coder-tls
```
2023-08-09 17:00:22 -04:00
2022-09-08 15:41:00 -04:00
## 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.
2022-09-08 15:41:00 -04:00
> [!NOTE]
2022-10-17 19:24:49 -05:00
> 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:
```console
$ coder server postgres-builtin-url
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:
1. Stop your Coder deployment.
1. Run `coder server postgres-builtin-serve` in a background terminal.
1. Run `coder server postgres-builtin-url` and copy its output command.
1. Run `pg_dump <built-in-connection-string> > coder.sql` to dump the internal
database to a file.
1. Restore that content to an external database with
`psql <external-connection-string> < coder.sql`.
1. Start your Coder deployment with
`CODER_PG_CONNECTION_URL=<external-connection-string>`.
## 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.
## Continue your setup with external authentication
2024-10-05 08:52:04 -07:00
Coder supports external authentication via OAuth2.0. This allows enabling
integrations with Git providers, such as GitHub, GitLab, and Bitbucket.
2024-10-05 08:52:04 -07:00
External authentication can also be used to integrate with external services
like JFrog Artifactory and others.
Please refer to the [external authentication](../external-auth/index.md) section for
2024-10-05 08:52:04 -07:00
more information.
## Up Next
- [Setup and manage templates](../templates/index.md)
- [Setup external provisioners](../provisioners/index.md)