# Set up a custom domain on a preview environment

[Preview environments](https://fixed.docs.upsun.com/glossary.md#preview-environment) in your project can't use the custom domain [set up on your production environment](https://fixed.docs.upsun.com/domains/steps.md).
By default and for each preview environment,
Upsun Fixed 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](https://fixed.docs.upsun.com/glossary.md#environment-type)).

To do so, no need to modify your [routes configuration](https://fixed.docs.upsun.com/define-routes.md).
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](https://fixed.docs.upsun.com/define-routes.md) either.
Upsun Fixed automatically figures out the routing of your preview environment
based on the following elements:

- The custom production domains in your existing [routes configuration](https://fixed.docs.upsun.com/define-routes.md)
- The custom domains for preview environments attached to each of those custom production domains

## Before you start

You need:

- A Grid project on which you have **admin rights** <BR>

  **Note**: 

If you have a Dedicated Gen 2 project,
currently you can only add a custom domain to the dedicated environments of your project (production and staging).
To do so, [contact Support](https://console.upsun.com/-/users/~/tickets/open).

  If you use a [Managed Fastly](https://fixed.docs.upsun.com/domains/cdn/managed-fastly.md) CDN,
  it needs to be configured to operate with custom domains for preview environments.
  For more information, [contact Support](https://console.upsun.com/-/users/~/tickets/open).
- A production environment with at least one custom domain already set up
- At least one preview (staging or development) environment
- Optional: The [Upsun Fixed CLI](https://fixed.docs.upsun.com/administration/cli.md) (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](https://fixed.docs.upsun.com/learn/overview/get-support.md).

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

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

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

 - [Configure your DNS provider](https://fixed.docs.upsun.com/domains/steps.md#2-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 Fixed recommends using the target of your preview environment as a best practice.

 - Run a command similar to the following:

```bash {}
platform 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 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](https://fixed.docs.upsun.com/domains/steps.md#2-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 Fixed 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:

 - Get the target for ``Dev``. 
To do so, navigate to ``Dev`` and click **Settings 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.com`` as a name for the custom domain you want to add to ``Dev``.

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

 - Click **Add**. 

 - Click **Okay**.

 - [Configure your DNS provider](https://fixed.docs.upsun.com/domains/steps.md#2-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

 - Navigate to your preview environment and click **Settings 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

 - Navigate to your preview environment and click **Settings 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 More** next to it.

## Remove a custom domain from a preview environment

 - Navigate to your preview environment and click **Settings Settings**.
 - Select the **Domains** tab. 
All the custom domains for the selected environment are displayed.
 - Click **More More** on the custom domain you want to delete.
 - Click **Delete**.
 - Click **Yes, delete**.