> ## 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
export const VariableBlock = ({name}) => {
return {name};
};
export const SettingsIcon = () => ;
export const MoreIcon = () => ;
By default, Upsun makes each [preview environment](/docs/glossary#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](/docs/domains/steps) — configure DNS, then add the domain to the environment
— with two differences:
* You don't need to update your [routes configuration](/docs/routes)
* 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](/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](/docs/core-concepts/get-support).
Deleting a production domain removes attached preview domains
If you [remove a production domain](/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:
1. Get the CNAME value for your preview environment — this is the Upsun-provided hostname your DNS record needs to point to:
```bash theme={null}
upsun environment:info edge_hostname --environment
```
2. [Configure your DNS provider](/docs/domains/steps#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:
```bash theme={null}
upsun domain:add --environment --attach
```
1. Get the CNAME value for your preview environment — this is the Upsun-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](/docs/domains/steps#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.
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:
```bash theme={null}
upsun domain:add staging.example.com --environment staging --attach example.com
```
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](/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
| Action | Command |
| ---------------------- | ---------------------------------------------------------------------------- |
| List all domains | `upsun domain:list --environment ` |
| View a specific domain | `upsun domain:get --environment ` |
| Remove a domain | `upsun domain:delete --environment ` |
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.