coder/docs/admin/setup/index.md

title

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

Tip

Need to look up an exact environment variable, CLI flag, or YAML key for a setting? See the configuration reference for a searchable list of every option.

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.

Access URL should be an 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.

Address

You can change which port(s) Coder listens on.

# 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

Tip

Learn more about the importance and benefits of wildcard access URLs

CODER_WILDCARD_ACCESS_URL is necessary for port forwarding via the dashboard or running coder_apps 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.

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.

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 in the Helm Chart, or --tls-cert-file and --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 for security.

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
• Caddy
• NGINX

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

   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

   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

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.

Note

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:

$ coder server postgres-builtin-url
psql "postgres://coder@localhost:49627/coder?sslmode=disable&password=feU...yI1"

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

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

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 section for more information.

Up Next

• Setup and manage templates
• Setup external provisioners