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(opens in a new tab).
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 AWS, GCP, Vercel, 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.

3. OAuth credentials: In development, for most OAuth providers, Clerk provides you with a set of shared OAuth credentials. These are not secure in production 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(opens in a new tab).
2. In the navigation sidebar, select Domains.

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. Please 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(opens in a new tab) 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(opens in a new tab) or Google Trust Services(opens in a new tab) certificate authorities.

Therefore, ensure that you don't have any CAA records on your primary domain (e.g. example.com) that prohibit both LetsEncrypt and Google Trust Services to issue certificates for your domain.

Incorrect domain

If you accidently set the wrong domain, you can change it through the Clerk Dashboard or Clerk's backend API. For more information, see the dedicated guide.

Last updated on April 18, 2024