Some of our e2e test suites require self-signed SSL certificates to be installed on the local machine. This short guide will walk you through the process of generating self-signed SSL certificates using mkcert.

Good news! If you've set up your local development environment for Clerk, you've already installed mkcert as part of our make deps command. If you haven't, you can install it by following the instructions here

To generate a new cert/key pair, you can simply run the following command:

mkcert -cert-file example.pem -key-file example-key.pem "example.com" "*.example.com"

The command above will create a example.pem and a example-key.pem file in the current directory. The certificate will be valid for example.com and all subdomains of example.com.

During installation, mkcert automatically adds its root CA to your machine's trust store. All certificates generated by mkcert from that point on, will you that specific root CA. This means that you can use the generated certificates in your local development environment without any additional configuration. There's an important caveat though: node does not use the system root store, so it won't accept mkcert certificates automatically. Instead, you will have to set the NODE_EXTRA_CA_CERTS environment variable.

export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem"

or provide the NODE_EXTRA_CA_CERTS when runnning your tests:

NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem" playwright test...

For more details, see here

In order to avoid install mkcert and generating self-signed certificates in our CI/CD pipeline, we have added the generated certificates and the root CA to the repository's secrets:

secrets.INTEGRATION_ROOT_CA
secrets.INTEGRATION_CERTS

During the CICD run, the certificates are loaded from the ENV and written to the ingration/certs directory.