Set up a custom domain on a preview environment
Back to home
On this page
Preview environments in your project can’t use the custom domain set up on your production environment.
By default and for each preview environment,
Upsun automatically replaces the custom production domain
with an automatically generated URL.
If you don’t want to use these default URLs,
you can add a custom domain to each of your preview environments
(staging or development environment types).
To do so, no need to modify your routes configuration. When you add a new custom domain for a preview environment, just attach it to the custom production domain it replaces. If you have multiple custom production domains, you need to select which one you’re replacing.
Example
You have two environments, a production environment and a staging environment.
You’ve added the example.com custom domain to your production environment.
You want to add the staging.example.com custom domain to your staging environment.
To do so, you need to attach the new staging.example.com custom domain
to its corresponding custom production domain example.com.
You can then access your staging environment through staging.example.com,
and still access your production environment through example.com.
If you have multiple custom domains on your production environment, when you set up a custom domain on a preview environment, you don’t need to update your routes configuration either. Upsun automatically figures out the routing of your preview environment based on the following elements:
- The custom production domains in your existing routes configuration
- The custom domains for preview environments attached to each of those custom production domains
Before you start 
You need:
- A production environment with at least one custom domain already set up
- At least one preview (staging or development) environment
- Optional: The Upsun CLI (v4.8.0+)
To prevent abuse, by default you can add custom domains to up to 5 preview environments per project only. This limit doesn’t include the production environment, and you can increase it without charge. To do so, contact Support.
Note
If you delete a custom production domain, all of the attached custom domains for preview environments are deleted too. You need to rebuild the affected preview environments for the deletion to be complete.
Add a custom domain to a preview environment
To add a custom domain to a preview environment, follow these steps:
-
To get the target for your preview environment, run the following command:
upsun environment:info edge_hostname --environment ENVIRONMENT_NAME -
Configure your DNS provider. In particular, make sure your DNS record points to the target of your preview environment.
Note
Using the target of your production environment to configure your DNS provider is technically possible, but Upsun recommends using the target of your preview environment as a best practice.
-
Run a command similar to the following:
upsun domain:add staging.example.com --environment STAGING_ENVIRONMENT_ID --attach PRODUCTION_CUSTOM_DOMAIN_TO_ATTACH
-
Get the target for your preview environment. To do so, navigate to your preview environment and click Settings. Select the Domains tab. In the Configure your domain section, copy the content of the CNAME record field. Save it for later use at step 7.
-
Click Add domain.
-
Name the custom domain for your preview environment.
-
Attach the custom domain for your preview environment to the desired production custom domain.
-
Click Add.
-
Click Okay.
-
Configure your DNS provider. In particular, make sure your DNS record points to the target of your preview environment.
Note
Using the target of your production environment to configure your DNS provider is technically possible, but Upsun recommends using the target of your preview environment as a best practice.
Note
You can’t update a custom domain when it’s used on a preview environment. You can only delete it and create a new one as a replacement.
Example
You’ve added the mysite.com custom domain to your production environment.
You now want to add the mydev.com custom domain to a preview environment called Dev.
To do so, follow these steps:
Run the following command:
upsun domain:add mydev.com --environment Dev --attach mysite.com-
Get the target for
Dev. To do so, navigate toDevand click Settings. Select the Domains tab. In the Configure your domain section, copy the content of the CNAME record field. Save it for later use at step 7. -
Click Add domain.
-
Enter
mydev.comas a name for the custom domain you want to add toDev. -
Select
mysite.comas the production custom domain you want to attachmydev.comto. -
Click Add.
-
Click Okay.
-
Configure your DNS provider. In particular, make sure your DNS record points to
Dev’s target.
In the above example, the Dev environment needs to exist
for you to add the mydev.com custom domain successfully.
If the Dev environment is later removed,
the mydev.com custom domain is removed too.
List the custom domains of a preview environment
Run a command similar to the following:
upsun domain:list --environment STAGING_ENVIRONMENT_ID- Navigate to your preview environment and click Settings.
- Select the Domains tab. All the custom domains for your preview environment are displayed.
Get a specific custom domain used on a preview environment
Run a command similar to the following:
upsun domain:get staging.example.com --environment STAGING_ENVIRONMENT_ID- Navigate to your preview environment and click Settings.
- Select the Domains tab. All the custom domains for the selected environment are displayed.
- To see which actions you can perform on a displayed custom domain, click More next to it.
Remove a custom domain from a preview environment
Run a command similar to the following:
upsun domain:delete staging.example.com --environment STAGING_ENVIRONMENT_ID- Navigate to your preview environment and click Settings.
- Select the Domains tab. All the custom domains for the selected environment are displayed.
- Click More on the custom domain you want to delete.
- Click Delete.
- Click Yes, delete.