Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Staging guides: support subdomains over buying separate domains #1535

Merged
merged 1 commit into from
Sep 16, 2024
+14 −14
Merged

Update Staging guides: support subdomains over buying separate domains #1535

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions docs/deployments/set-up-staging.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,27 +3,27 @@ title: Set up a staging environment with Clerk
description: Learn how to set up a staging environment with Clerk authentication.
---

Staging environments enable you to internally test and demo changes to your application or website before deploying them to production. Currently, Clerk only offers **Development** and **Production** instances. Official support for **Staging** instances is still on [Clerk's roadmap](https://feedback.clerk.com/roadmap/de417dd1-fa2e-4997-868f-4c9248027e7d). However, you can set up a "staging environment" by creating a separate Clerk application with a separate domain.
Staging environments enable you to internally test and demo changes to your application or website before deploying them to production. Currently, Clerk only offers **Development** and **Production** instances. Official support for **Staging** instances is still on [Clerk's roadmap](https://feedback.clerk.com/roadmap/de417dd1-fa2e-4997-868f-4c9248027e7d). However, you can set up a "staging environment" by creating a subdomain for a separate Clerk application.
Copy link
Member

@nikosdouvlis nikosdouvlis Sep 18, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey!
I noticed that the feedback.clerk.com link simply open our productlane page but does not show a specific entry - I guess that the entry with id de417dd1-fa2e-4997-868f-4c9248027e7d got deleted at some point.

Does anyone remember what that product lane was about? We still don't have support for staging instances so there should be an entry for it but I can't find it.

cc'ing the experts here: @alexisintech , @royanger , maybe Kyle?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm pretty sure this was for multiple instances, but I don't have anything regarding it in my browser history. @kylemac or @jescalan might know more here. I don't see anything in Product Lane's public facing side for multiple instances/staging instances.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah this is a bit of a mystery we should figure out. we linked to the same "staging instances" item in the changelog too - but its been removed from productlane somehow

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got this re-added!


Creating a separate Clerk application will prevent you from using live production environment data in your staging environment. And if you are on a Pro, Enterprise, or Startup plan, **Clerk will fully upgrade your staging application for free.**
Creating a separate Clerk application will prevent you from using live production environment data in your staging environment. If you are on a Pro, Enterprise, or Startup plan, **Clerk will fully upgrade your staging application for free.**

It is important to note that when you use a separate Clerk application for your staging environment, changes to this application will not be automatically mirrored in your main application for your production environment. You must manually make these changes yourself if you want them to be reflected in both applications.

## Set up a staging Clerk application

The following steps will help you set up a new Clerk application with a staging-specific domain:

1. **Acquire a separate domain** - This domain will be used for your staging environment. _This cannot be a subdomain_ of the domain used in your production environment. For example, if your production domain is `my-site.com`, you could use `my-site-staging.com`. If you do not want to use a new domain, see [the instructions for using a subdomain](/docs/deployments/staging-alternatives).
1. **Create a new Clerk app** - Your staging environment will connect to this app instead of your main Clerk application. See [the Clerk quickstart guide](/docs/quickstarts/setup-clerk) to learn how to create a Clerk app.
1. **Set up a subdomain** - This will be your staging domain. For example, if your domain is `my-site.com`, you could use `staging.my-site.com`.
1. **Create a new Clerk app** - Your staging environment will connect to this app instead of your main one. See [the Clerk quickstart guide](/docs/quickstarts/setup-clerk) to learn how to create a Clerk app.
1. **Deploy and configure your staging app's production instance** - Using production API keys will make your staging app more secure. Follow the [Deploy to production](/docs/deployments/overview) guide to do so.
1. **Contact Clerk support to upgrade your staging app for free** - If you are on a Pro, Enterprise, or Startup plan, Clerk will fully upgrade your staging app for free.

## Alternatives to using a separate domain
## Alternatives

### Preview environments

While staging environments are typically long-lived, preview environments are typically generated on-demand for specific pull requests. See [the guide on using Clerk in a preview environment](/docs/deployments/set-up-preview-environment) to learn about your options.

### Shared production credentials

If you do not want to purchase a separate domain, or if you would like to share settings and data between your production and staging environments, see the [Staging alternatives](/docs/deployments/staging-alternatives) guide. This is not recommended because you will be sharing a user table between your production and staging environments.
If you would like to share settings and data between your production and staging environments, see [the dedicated guide](/docs/deployments/staging-alternatives). This is not recommended because you will be sharing a user table between your production and staging environments.
16 changes: 8 additions & 8 deletions docs/deployments/staging-alternatives.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,25 +6,25 @@ description:
## Shared production credentials

> [!CAUTION]
> This is not recommended. Instead, you should either [set up a staging environment with a separate domain](/docs/deployments/set-up-staging) or [use a preview deployment](/docs/deployments/set-up-preview-environment).
> This is not recommended. Instead, you should either [set up a staging environment with a subdomain and separate Clerk app](/docs/deployments/set-up-staging) or [use a preview deployment](/docs/deployments/set-up-preview-environment).

If you do not want to purchase a separate domain, or if you would like to share settings and data between your production and staging environments, you can use a subdomain of your production domain to set up a staging environment.
If you would like to share settings and data between your production and staging environments, you can use a subdomain of your production domain to set up a staging environment.

### Limitations of using a subdomain
### Limitations of shared production credentials

The limitations of using a subdomain to set up a staging environment with Clerk include:
The limitations of using shared production credentials to set up a staging environment with Clerk include:

- You will be combining staging data with live production data.
- When you enable Clerk features to test in staging, they will be enabled in your Production environment as well.

### Set up staging with a subdomain
### Set up staging with shared production credentials

1. **Add your subdomain to your hosting provider** - Ensure that your subdomain is associated with your staging branch so that it will point to new staging deployments. This process will vary based on your provider. The following are some guides from popular hosting providers:
- [Vercel](https://vercel.com/guides/set-up-a-staging-environment-on-vercel)
- [Netlify](https://docs.netlify.com/domains-https/netlify-dns/delegate-a-subdomain-to-netlify-dns/)
- [Cloudflare](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-subdomain/)
1. **Add your CNAME record to your domain provider** - Depending on the provider, the verification process for this can take hours or days.
1. **Add your production instance API keys to your staging deployment** - In your staging deployment's environment variables, add your Clerk app's production instance API keys. Visit the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) section in the Clerk Dashboard to find them, and ensure that the instance at the top of the Dashboard is set to **Production**. The following are environment variable guides from some popular providers:
1. **Add your CNAME record to your domain provider** - Depending on the provider, the verification process can take hours or days.
1. **Add your production instance's API keys to your staging deployment** - In your staging deployment's environment variables, add your production instance's API keys. To find them, visit the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard and ensure that the instance at the top of the Dashboard is set to **Production**. The following are environment variable guides from some popular providers:
- [Vercel](https://vercel.com/docs/projects/environment-variables#declare-an-environment-variable)
- [Netlify](https://docs.netlify.com/environment-variables/get-started/#create-environment-variables)
- [Cloudflare](https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-the-dashboar)
- [Cloudflare](https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-the-dashboard)
Loading