# Configure control plane access

The control plane's primary configuration is done via environment variables.
For a full list of the options, run `coder server --help` or see our [CLI documentation](/beta-docs/@main/reference/cli/server/).

<Callout type="success" title="Tip">
  Need to look up an exact environment variable, CLI flag, or YAML key for a setting?
  See the [configuration reference](/beta-docs/@main/admin/setup/configuration-reference/) for a searchable list of every option.
</Callout>

## Access URL [#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](https://coder.example.com)).
This should not be localhost.

Access URL should be an external IP address or domain with DNS records pointing to Coder.

### Tunnel [#tunnel]

If an access URL is not specified, Coder will create a publicly accessible URL to reverse proxy your deployment for simple setup.

## Address [#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 control plane
coder server
```

## Wildcard access URL [#wildcard-access-url]

<Callout type="success" title="Tip">
  Learn more about the [importance and benefits of wildcard access URLs](/beta-docs/@main/admin/networking/wildcard-access-url/)
</Callout>

`CODER_WILDCARD_ACCESS_URL` is necessary for [port forwarding](/beta-docs/@main/admin/networking/port-forwarding/#dashboard) via the dashboard or running [coder\_apps](/beta-docs/@main/admin/templates/) 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`.

<Callout type="info" title="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.
</Callout>

If you are providing TLS certificates directly to the control plane, 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`](/beta-docs/@main/reference/cli/server/#--tls-cert-file) and [`--tls-key-file`](/beta-docs/@main/reference/cli/server/#--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).

After you enable the wildcard access URL, you should [disable path-based apps](/beta-docs/@main/tutorials/best-practices/security-best-practices/#disable-path-based-apps) for security.

## TLS & Reverse Proxy [#tls--reverse-proxy]

The control plane 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](/beta-docs/@main/tutorials/reverse-proxy-apache/)
* [Caddy](/beta-docs/@main/tutorials/reverse-proxy-caddy/)
* [NGINX](/beta-docs/@main/tutorials/reverse-proxy-nginx/)

### Kubernetes TLS configuration [#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.

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"
   ```

   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`.

2. Reference the TLS secret in your Coder Helm chart values

   ```yaml
   coder:
     tls:
       secretNames:
         - coder-tls

     # 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
   ```

## PostgreSQL Database [#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](https://repo1.maven.org/maven2)) and store all data in the config root.

<Callout type="info" title="Note">
  Postgres 13 is the minimum supported version.
</Callout>

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"
```

<a id="migrating-from-the-built-in-database-to-an-external-database"></a>

### Migrate from the built-in database to an external database [#migrate-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.
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>`.

<a id="configuring-coder-behind-a-proxy"></a>

## Configure Coder behind a proxy [#configure-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 control plane.
Lowercase values (e.g. `http_proxy`) are also respected in this case.

## Continue your setup with external authentication [#continue-your-setup-with-external-authentication]

Coder supports external authentication via OAuth2.0.
This allows enabling integrations with Git providers, such as GitHub, GitLab, and Bitbucket.

External authentication can also be used to integrate with external services like JFrog Artifactory and others.

Please refer to the [external authentication](/beta-docs/@main/admin/external-auth/) section for more information.

## Up Next [#up-next]

* [Setup and manage templates](/beta-docs/@main/admin/templates/)
* [Setup external provisioners](/beta-docs/@main/install/operate/provisioners/)