> ## Documentation Index
> Fetch the complete documentation index at: https://developer.upsun.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up a custom domain on a preview environment

> Learn how to set up custom domains on your preview environments

By default, Upsun Cloud makes each [preview environment](https://developer.upsun.com/docs/glossary.md#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](https://developer.upsun.com/docs/domains/steps) — configure DNS, then add the domain to the environment
— with two differences:

* You don't need to update your [routes configuration](https://developer.upsun.com/docs/routes)
* You must attach the preview domain to its corresponding production domain — that is, tell Upsun Cloud 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 Cloud derives the routing automatically.

> [!NOTE]
>
> 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 Cloud CLI](https://developer.upsun.com/cli.md) (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](https://developer.upsun.com/docs/core-concepts/get-support.md).

> [!WARNING]
>
> Deleting a production domain removes attached preview domains
> If you [remove a production domain](https://developer.upsun.com/docs/domains/steps#remove-a-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:

> [tab] Using the CLI
>
> 1. Get the CNAME value for your preview environment — this is the Upsun Cloud-provided hostname your DNS record needs to point to:
>
>    ```bash theme={null}
>    upsun environment:info edge_hostname --environment <ENVIRONMENT_NAME>
>    ```
>
> 2. [Configure your DNS provider](https://developer.upsun.com/docs/domains/steps#2-configure-your-dns-provider).
>    In particular, make sure your DNS record points to the target of your preview environment.
>
>    > [!NOTE]
>    >
>    > 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:
>
>    ```bash theme={null}
>    upsun domain:add <YOUR_PREVIEW_DOMAIN> --environment <STAGING_ENVIRONMENT_ID> --attach <PRODUCTION_CUSTOM_DOMAIN_TO_ATTACH>
>    ```

> [tab] In the Console
>
> 1. Get the CNAME value for your preview environment — this is the Upsun Cloud-provided hostname your DNS record needs to point to.\\
>
>    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](https://developer.upsun.com/docs/domains/steps#2-configure-your-dns-provider).\\
>
>    In particular, make sure your DNS record points to the target of your preview environment.
>
> > [!NOTE]
> >
> > Use your preview environment's CNAME value rather than your production environment's. Upsun recommends this to ensure correct routing for your preview environment.

> [!NOTE]
>
> 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:

> [tab] Using the CLI
>
> Run the following command:
>
> ```bash theme={null}
> upsun domain:add staging.example.com --environment staging --attach example.com
> ```

> [tab] In the Console
>
> 1. Get the CNAME value for `staging`.\\
>
>    To do so, navigate to `staging` 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 `staging.example.com` as the custom domain you want to add to `staging`.
>
> 4. Select `example.com` as the production custom domain you want to attach `staging.example.com` to.
>
> 5. Click **Add**.\\
>
> 6. Click **Okay**.
>
> 7. [Configure your DNS provider](https://developer.upsun.com/docs/domains/steps#2-configure-your-dns-provider).\\
>
>    In particular, make sure your DNS record points to `staging`'s CNAME value.

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

> [tab] Using the CLI
>
> | Action | Command |
> | - | - |
> | List all domains | `upsun domain:list --environment <ENVIRONMENT_NAME>` |
> | View a specific domain | `upsun domain:get <YOUR_PREVIEW_DOMAIN> --environment <ENVIRONMENT_NAME>` |
> | Remove a domain | `upsun domain:delete <YOUR_PREVIEW_DOMAIN> --environment <ENVIRONMENT_NAME>` |

> [tab] In the Console
>
> 1. Navigate to your preview environment and click \*\* Settings\*\*.
> 2. Select the **Domains** tab.\\
>
>    All the custom domains for your preview environment are displayed.
> 3. To act on a domain, click \*\* More\*\* next to it:
>    * To view details, select the domain from the list.
>    * To delete a domain, click **Delete**, then confirm.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.