Deploy your Clerk app to production

Before you begin:

1. You will need to have a domain you own.
2. You will need to be able to add DNS records on your domain.
3. You will need social sign-in (OAuth) credentials for any providers that you would like to use in production. Each OAuth provider has a dedicated guide on how to set up OAuth credentials for Clerk production apps.

Create your production instance

1. Navigate to the Clerk Dashboard.
2. At the top of the Dashboard, select the Development button to reveal the instance selection dropdown. Select Create production instance.
3. You will be prompted with a modal to either clone your development instance settings to your production instance or create your production instance with Clerk's default settings.
4. The homepage of the dashboard will show you what is still required to deploy your production instance.

API keys and environment variables

A common mistake when deploying to production is forgetting to change your API keys to your production instances keys. The best way to set this up is to make use of environment variables. All modern hosting providers, such as Vercel, AWS, GCP, Heroku, and Render, make it easy to add these values. Locally, you should use an .env file. This way, these values are being set dynamically depending on your environment. Here's a list of Clerk variables you'll need to change:

1. Publishable Key: Formatted as pk_test_ in development and pk_live_ in production. This is passed to the <ClerkProvider> during initialization.

2. Secret Key: Formatted as sk_test_ in development and sk_live_ in production. These values are used to access Clerk's Backend API.

OAuth credentials

In development, for most social providers, Clerk provides you with a set of shared OAuth credentials.

In production, these are not secure and you will need to provide your own. Each OAuth provider has a dedicated guide on how to set up OAuth credentials for Clerk production apps.

DNS records

Clerk uses DNS records to provide session management and emails verified from your domain.

To see what DNS records you need to add:

1. Navigate to the Clerk Dashboard.
2. In the navigation sidebar, select Domains.

Authentication across subdomains

When you set a root domain for your production deployment, Clerk's authentication will work across all subdomains. User sessions will also be shared across the subdomains.

Examples

• example-site.com and dashboard.example-site.com
• dashboard.example-site.com and accounts.example-site.com

To share sessions and authentication across two different domains with the same Clerk application, see the Authentication across different domains guide.

Deploy certificates

The Clerk Dashboard home page will tell you what steps are still required to deploy your production instance. Once you have completed all of the necessary steps, a Deploy certificates button will appear. Selecting this button will deploy your production instance.

Troubleshooting

DNS records not propagating with Cloudflare

Clerk uses a DNS check to validate this CNAME record. If this subdomain is reverse proxied behind a service that points to generic hostnames, such as Cloudflare, the DNS check will fail. Set the DNS record for this subdomain to a "DNS only" mode on your host to prevent proxying.

Deployment stuck in certificate issuance

If your instance is stuck during TLS certificate issuance for longer than a few minutes, this might be caused due to certain CAA DNS records set on your primary domain.

CAA are DNS records you may set to denote which certificate authorities (CA) are permitted to issue certificates for your domain, as a security measure against certain attacks. When you deploy your application, Clerk attempts to provision certificates using either the LetsEncrypt or Google Trust Services certificate authorities.

Ensure that your primary domain (e.g., example.com) does not have any CAA records that prevent either LetsEncrypt or Google Trust Services from issuing certificates for your domain. To check this, run the following command in your terminal, replacing example.com with your app’s domain:

dig example.com +short CAA

If the command returns an empty response, your domain is correctly configured. If it returns any text, you need to remove the CAA records from your primary domain to avoid potential downtime during certificate renewal.

Incorrect domain

If you accidentally set the wrong domain, you can change it through the Clerk Dashboard or the Backend API. For more information, see the dedicated guide.