Skip to main content
By default, Upsun makes each preview environment available at an automatically generated URL — for example, something like staging-abc123-yourproject.eu.platformsh.site. This is true even if you’ve already added a custom domain to your production environment; preview environments don’t automatically inherit it. If you want preview environments accessible at meaningful, predictable URLs, you can add a custom domain to each one — but you must have at least one custom domain set up on your production environment first. You then follow the same basic steps as setting up a production custom domain — configure DNS, then add the domain to the environment — with two differences:
  • You don’t need to update your routes configuration
  • You must attach the preview domain to its corresponding production domain — that is, tell Upsun which production domain’s routing rules the preview domain should follow.
If you have multiple custom domains on your production environment, select which one to attach the preview domain to. Upsun derives the routing automatically.

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.

​
Before you start

You need:
  • A production environment with at least one custom domain configured
  • At least one preview (staging or development) environment
  • Optional: The Upsun CLI (v4.8.0+)
By default, you can add custom domains to up to 5 preview environments per project. You can increase this limit without charge by contacting Support.

Deleting a production domain removes attached preview domains

If you remove a production domain, all preview domains attached to it are also deleted.

​
Add a custom domain to a preview environment

To add a custom domain to a preview environment, follow these steps:
  1. Get the CNAME value for your preview environment — this is the Upsun-provided hostname your DNS record needs to point to: 
    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.
    Use your preview environment’s CNAME value rather than your production environment’s. Upsun recommends this to ensure correct routing for your preview environment.
  3. Run a command similar to the following: 
    upsun domain:add <YOUR_PREVIEW_DOMAIN> --environment <STAGING_ENVIRONMENT_ID> --attach <PRODUCTION_CUSTOM_DOMAIN_TO_ATTACH>

Preview domains cannot be edited

To change a preview environment’s custom domain, delete it and add a new one.

​
Example

You’ve added the example.com custom domain to your production environment. You now want to add the staging.example.com custom domain to a preview environment called staging. To do so, follow these steps:
Run the following command:
upsun domain:add staging.example.com --environment staging --attach example.com
In the above example, the staging environment needs to exist for you to add the staging.example.com custom domain successfully. If the staging environment is later removed, the staging.example.com custom domain is removed too.

​
Manage custom domains on a preview environment

ActionCommand
List all domainsupsun domain:list --environment <ENVIRONMENT_NAME>
View a specific domainupsun domain:get <YOUR_PREVIEW_DOMAIN> --environment <ENVIRONMENT_NAME>
Remove a domainupsun domain:delete <YOUR_PREVIEW_DOMAIN> --environment <ENVIRONMENT_NAME>
Last modified on May 28, 2026