Upsun User Documentation
Edit page

Set up a custom domain on a preview environment

Back to home

On this page

Try Upsun for 15 days
After that, enjoy the same, game-changing Upsun features for less with the First Project Incentive!¹ A monthly $19 perk!
¹Terms and conditions apply
Activate your 15-day trial

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.

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 Anchor to this heading

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.

Add a custom domain to a preview environment Anchor to this heading

To add a custom domain to a preview environment, follow these steps:

  1. To get the target for your preview environment, run the following command:

    upsun environment:info edge_hostname --environment ENVIRONMENT_NAME

  2. Configure your DNS provider. In particular, make sure your DNS record points to the target of your preview environment.

  1. Run a command similar to the following:

    upsun domain:add staging.example.com --environment STAGING_ENVIRONMENT_ID --attach PRODUCTION_CUSTOM_DOMAIN_TO_ATTACH

  1. 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.

  2. Click Add domain.

  3. Name the custom domain for your preview environment.

  4. Attach the custom domain for your preview environment to the desired production custom domain.

  5. Click Add.

  6. Click Okay.

  7. Configure your DNS provider.
    In particular, make sure your DNS record points to the target of your preview environment.

Example Anchor to this heading

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

  1. Get the target for Dev.
    To do so, navigate to Dev 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.

  2. Click Add domain.

  3. Enter mydev.com as a name for the custom domain you want to add to Dev.

  4. Select mysite.com as the production custom domain you want to attach mydev.com to.

  5. Click Add.

  6. Click Okay.

  7. 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 Anchor to this heading

Run a command similar to the following:

upsun domain:list --environment STAGING_ENVIRONMENT_ID
  1. Navigate to your preview environment and click Settings.
  2. Select the Domains tab.
    All the custom domains for your preview environment are displayed.

Get a specific custom domain used on a preview environment Anchor to this heading

Run a command similar to the following:

upsun domain:get staging.example.com --environment STAGING_ENVIRONMENT_ID
  1. Navigate to your preview environment and click Settings.
  2. Select the Domains tab.
    All the custom domains for the selected environment are displayed.
  3. 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 Anchor to this heading

Run a command similar to the following:

upsun domain:delete staging.example.com --environment STAGING_ENVIRONMENT_ID
  1. Navigate to your preview environment and click Settings.
  2. Select the Domains tab.
    All the custom domains for the selected environment are displayed.
  3. Click More on the custom domain you want to delete.
  4. Click Delete.
  5. Click Yes, delete.

Is this page helpful?