2026-09-08 12:34:00 -04:00
---
title : Configure control plane access
---
2024-10-05 08:52:04 -07:00
2023-08-23 12:27:57 +03: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 ).
2022-08-10 18:56:21 -04:00
2026-08-03 14:33:01 -04:00
> [!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
2023-08-23 12:27:57 +03:00
`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
2025-03-10 15:58:20 -05:00
Access URL should be an external IP address or domain with DNS records pointing to Coder.
2022-09-13 10:53:41 -04:00
2022-10-07 08:05:56 -05:00
### Tunnel
2023-08-23 12:27:57 +03:00
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
2023-01-18 15:23:55 -08:00
## Address
You can change which port(s) Coder listens on.
2026-07-15 14:07:09 -04:00
```sh
2023-01-18 15:23:55 -08:00
# 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
2023-11-17 15:09:29 +04:00
export CODER_REDIRECT_TO_ACCESS_URL = true
2023-01-18 15:23:55 -08:00
# Start the Coder server
coder server
```
2022-09-26 11:56:17 -03:00
## Wildcard access URL
2025-09-12 20:34:38 +02:00
> [!TIP]
> Learn more about the [importance and benefits of wildcard access URLs](../networking/wildcard-access-url.md)
2026-07-24 17:10:19 +02:00
`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
2025-03-10 15:58:20 -05:00
> [!NOTE]
> We do not recommend using a top-level-domain for Coder wildcard access
2025-01-02 14:01:28 +04:00
> (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.
2025-01-07 15:10:16 -05:00
1. Configure multiple certificates and keys via
2026-06-22 11:39:12 -04:00
[`coder.tls.secretNames` ](../../../helm/coder/values.yaml )
2024-08-13 18:39:46 +03:00
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
2024-08-13 18:39:46 +03:00
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
2025-07-01 13:18:47 -04: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.
2023-02-16 07:50:18 +03:00
## TLS & Reverse Proxy
2022-10-19 07:20:11 -05:00
2023-08-23 12:27:57 +03:00
The Coder server can directly use TLS certificates with `CODER_TLS_ENABLE` and
accompanying configuration flags. However, Coder can also run behind a
2024-10-05 12:44:02 -05:00
reverse-proxy to terminate TLS certificates from LetsEncrypt.
2022-10-19 07:20:11 -05:00
2024-10-09 22:31:19 -07:00
- [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
2023-08-23 12:27:57 +03:00
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
2026-07-15 14:07:09 -04:00
```sh
2025-01-07 15:10:16 -05:00
kubectl create secret tls coder-tls -n <coder-namespace> --key="tls.key" --cert="tls.crt"
` ``
2023-08-09 17:00:22 -04:00
2025-01-07 15:10:16 -05: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
2025-01-07 15:10:16 -05:00
` ``yaml
coder:
tls:
2026-08-14 12:43:46 -04:00
secretNames:
2025-01-07 15:10:16 -05:00
- coder-tls
2023-08-09 17:00:22 -04:00
2025-01-07 15:10:16 -05:00
# Alternatively, if you use an Ingress controller to terminate TLS,
# set the following values:
ingress:
2026-08-14 12:43:46 -04:00
enable: true
tls:
2025-01-07 15:10:16 -05:00
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
2023-08-23 12:27:57 +03:00
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
2025-03-10 15:58:20 -05:00
> [!NOTE]
2022-10-17 19:24:49 -05:00
> Postgres 13 is the minimum supported version.
2022-11-02 18:56:24 -05:00
If you are using the built-in PostgreSQL deployment and need to use ` psql` (aka
2023-08-23 12:27:57 +03:00
the PostgreSQL interactive terminal), output the connection URL with the
following command:
2022-11-02 18:56:24 -05:00
2023-02-01 17:05:45 -03:00
` ``console
2025-01-07 15:10:16 -05:00
$ coder server postgres-builtin-url
2023-02-15 22:18:54 +03:00
psql "postgres://coder@localhost:49627/coder?sslmode=disable&password=feU...yI1"
2022-11-02 18:56:24 -05:00
` ``
2023-05-21 18:31:06 +03:00
### Migrating from the built-in database to an external database
2023-08-23 12:27:57 +03:00
To migrate from the built-in database to an external database, follow these
steps:
2023-05-21 18:31:06 +03:00
1. Stop your Coder deployment.
2025-01-07 15:10:16 -05:00
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
2023-08-23 12:27:57 +03:00
database to a file.
2025-01-07 15:10:16 -05:00
1. Restore that content to an external database with
2023-08-23 12:27:57 +03:00
` psql <external-connection-string> < coder.sql`.
2025-01-07 15:10:16 -05:00
1. Start your Coder deployment with
2023-08-23 12:27:57 +03:00
` CODER_PG_CONNECTION_URL=<external-connection-string>`.
2023-05-21 18:31:06 +03:00
2023-02-07 09:11:03 -06:00
## Configuring Coder behind a proxy
2023-08-23 12:27:57 +03:00
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.
2023-02-07 09:11:03 -06:00
2025-05-20 15:10:52 -04:00
## Continue your setup with external authentication
2024-10-05 08:52:04 -07:00
Coder supports external authentication via OAuth2.0. This allows enabling
2025-01-07 15:10:16 -05:00
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.
2025-06-16 13:18:55 -04:00
Please refer to the [external authentication ](../external-auth/index.md ) section for
2024-10-05 08:52:04 -07:00
more information.
2022-08-10 18:56:21 -04:00
## Up Next
2025-01-07 15:10:16 -05:00
- [Setup and manage templates ](../templates/index.md )
2025-04-01 22:04:31 -04:00
- [Setup external provisioners ](../provisioners/index.md )