Platform.sh User Documentation

Tier availability

This feature is available for Elite and Enterprise customers. Compare the Platform.sh tiers on our pricing page, or contact our sales team for more information.

Edit page

Set up a custom domain on a preview environment

Back to home

On this page

Sign up for Upsun

Get your free trial by clicking the link below.

Get your Upsun free 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, Platform.sh 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. Platform.sh 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 Grid or Dedicated Gen 3 project on which you have admin rights

    If you use a Managed Fastly CDN, it needs to be configured to operate with custom domains for preview environments. For more information, contact Support.

  • A production environment with at least one custom domain already set up

  • At least one preview (staging or development) environment

  • Optional: The Platform.sh 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.

If you downgrade from an Elite or Enterprise plan to a Professional plan, all of the custom domains set up on preview environments are automatically removed. Downgrading your plan doesn’t affect custom domains set up on your production environments.

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:

    platform 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:

    platform 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:

platform 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:

platform 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:

platform 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:

platform 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?