# Changing domains

An environment that deploys under a [domain](/user-guide/settings/workspace-settings/domains) can move
to another one: Productmind prepares the new domain beside the one in use and moves the environment once
it points there. A domain no environment uses any more is kept, with its zone, until you remove it.

<Availability rollout permission="Owners and Admins, signed in to Productmind themselves, change an environment's domain, cancel a change and remove a domain. Anyone who can open the application sees where its environments' domains move." />

## Key concepts

**The domain in use.** The domain the environment deploys under now. It keeps serving the app while a
change is prepared, until the environment moves.

**The domain a change prepares.** The new domain, under **Moving to** on the environment's row. A new
domain you own gets a DNS zone and a check of its own, as an attach's domain does.

**A kept domain.** A domain the environment no longer uses keeps its zone, so the environment can move
back to it, until you remove it under **Domains you own**.

## Changing or removing a domain

<Screenshot id="settings-domains-change" alt="Development's row under Cloud accounts: it deploys under Productmind's address, and under Moving to, app.example.org shows Waiting for your DNS, no name servers found for app.example.org yet, with DNS records and Cancel change buttons" />

An environment that deploys can move to another domain. The new domain is prepared beside the one in
use, which keeps serving the app until the move: nothing changes until the new domain points at the
environment.

### To change an environment's domain

1. Open the application, then the **Source code** tab. Under **Cloud accounts**, open the environment's
   menu and choose **Change domain**.
2. Choose **A domain you own** and type it, or **Productmind's address** to move back to the
   environment's own address.
3. Choose **Continue**. Read when it moves, what moves at the next deploy and what stops working then,
   then choose **Change domain**. A new change replaces one being prepared: remove the NS records you
   added for that one.
4. Under **Moving to** on the row, open **DNS records** and point the new domain at its zone's name
   servers, as for a new attach (see [Pointing your domain at the zone](/user-guide/settings/workspace-settings/domains#pointing-your-domain-at-the-zone)).

Once public DNS points the new domain at its zone, the environment moves to it at Productmind's next
check, or within a minute after you choose **Check again** under **DNS records**. Productmind checks
every 2 minutes for the first 30 minutes, every 10 minutes until 6 hours, then every hour, and stops
after seven days until you choose **Check again**. A change sends no reminder emails, except while a
whole domain's records wait to be copied on an account Productmind manages: then the person who asked
for it gets one a day and six days in. Its row says where it stands. Productmind then writes the new
domain to the environment's deploy settings, while the row says so and offers no **Deploy now**, which
comes back once they are written. The hosts move at the next deploy after that: merge a pull request
into its branch, or choose **Deploy now**. Until that deploy, the app keeps serving under the old
domain.

**At the next deploy.** The app, API, websocket and docs hosts move to the new domain, and the old
domain stops serving them. Everyone signed in to the app signs in again, and sign-in links already sent
by email, such as invitations and password resets, stop working. The app sends no mail until the new
domain's mail identity is verified, usually within minutes.

**These stop working at that deploy until you update them:** the redirect URLs registered with sign-in
providers, OAuth clients that send people to the app's hosts, webhooks that call its API, links to files
it stored that are kept elsewhere, installed copies of the app, which people install again from the new
address, and your repository's own configuration that names the old domain: change it with the domain.
Where a service takes several addresses, add the new ones before the deploy, and remove the old ones
once it has run.

**A sender address in your repository's own configuration.** While it sets the app's sender address at
the old domain (`webapp:mail.from`), the deploy that moves the hosts fails, and nothing moves. Change it
in the pull request you merge as that deploy, once the row says the hosts move at the next deploy:
changed before then, it fails every deploy until then. With no sender address set, the app sends from
the new domain by itself.

**Moving back to Productmind's address** works on an account Productmind manages while the
environment's own address is still set up in that account, which it stays after a move to a domain you
own. It is ready at once: the environment moves within a minute. **Moving back to a domain the
environment used before** checks first that it still points at its zone, so it moves at the next check.

Under **Moving to**, the row shows one of:

| Badge | What it means |
| --- | --- |
| **Making its DNS zone** | Productmind is making the new domain's zone in the account. For a whole domain on an account Productmind manages, you then copy and confirm its records before its name servers show |
| **Copy your DNS records** | A whole domain on an account Productmind manages: copy and confirm its records under **DNS records** first |
| **Waiting for your DNS** | Point the new domain at its zone's name servers, under **DNS records**. A domain the environment used before shows it too once its check finds it no longer points at its zone |
| **Checking** | Productmind's own check is next: confirming that no other environment still uses the new domain, waiting for its zone to answer, or, for a domain the environment used before, checking again that it still points at its zone |
| **Setting up its DNS** | The domain above the new one is on an account Productmind manages, and Productmind is adding the new domain's NS records to its zone: nothing to do. Resolvers can take up to 15 minutes to see them |
| **Moving now** | The new domain points here: the environment moves within a minute |
| **Domain change pending** | The new domain points here and moves once the environment's attachment is active again. Anyone who can't see the account's details sees this while the change is prepared |
| **Stopped** | Productmind stopped checking it, after seven days or at a failure: the row says why and what to do, then choose **Check again**, or cancel the change |

### To cancel a change

On the row, under **Moving to**, choose **Cancel change**. The environment stays under its domain.
Productmind deletes the zone it made for a new domain once nothing points at it: remove its NS records
if you already added them. A domain the environment used before stays kept, with its zone, until you
remove it. A change that has already moved can't be cancelled: change the domain again instead.
Detaching the environment cancels its change too.

### To remove a domain

A domain the environment no longer uses is kept, with its zone, so you can move back to it. To remove
it, open **Settings**, then **Cloud accounts**, and open its account: **Domains you own** lists each
domain the account holds and what it is to its environment, naming its application to those who can
open applications. Choose **Remove** beside one no environment uses or prepares, type its name, then
choose **Remove**. Productmind deletes the zone it made for it once nothing points at it, or stops using
a zone of yours, and the domain can be used again. This is also how you free the domain of an
environment or application you deleted.

If you keep [DNS records](/user-guide/settings/workspace-settings/dns-records) for the domain in
Productmind, export them first, from its **DNS records** or from **Remove** itself: the zone and every
record in it are deleted once nothing points at it, and the domain's page goes with it.

If Productmind keeps NS records in the domain's zone for your other domains under it, **Remove** names
them: add them where the domain's DNS moves (its export lists them), or those domains stop resolving when
the zone is deleted. If the domain itself sits under another of your domains on an account Productmind
manages, Productmind first removes its NS records from that domain's zone.

A domain the environment moved away from can be removed once the environment has deployed under its
new domain: until then the environment may still run under it, its zone holding the app's records, and
the list says so.

A detached environment keeps its domain and its zone: the app that already runs keeps serving under it,
and the list says so. Removing that domain takes the app offline there once its NS records go.

A domain is checked every day while it is kept. If an environment's domain, or a detached environment's,
stops pointing at its zone, your Owners and Admins get an email. For a detached environment's domain,
even once the environment is attached to another account, it says that the app left running in the
account can no longer be reached at the domain, and to remove the domain if you no longer need it. A
domain no environment uses any more sends none: the account's list shows it.

:::caution
When Productmind tells you it deletes a domain's zone, or that the zone is gone, remove the NS records
that point at its name servers at once, and never add those name servers back. A delegation to name
servers that no longer serve your zone could let someone else's zone answer for your domain.
:::

## Permissions

| To | You need |
| --- | --- |
| Change an environment's domain, or cancel the change | The **Owner** or **Admin** role, signed in to Productmind yourself |
| See an account's **Domains you own** | The **Owner** or **Admin** role |
| Remove a domain | The **Owner** or **Admin** role, signed in to Productmind yourself |

## Limits

- An environment holds two domains you own at most, at an attach as at a change: the one it deploys
  under and the one a change prepares. A domain it no longer uses counts until you remove it.
- An environment can change its domain while it deploys, **Active** or **Paused**, not while it is set
  up, changes branch, failed or is being detached.

## Troubleshooting

### "Development already holds 2 domains you own, the most an environment holds"

The environment's domain in use and another it kept count against its two. Remove the one it no longer
uses in **Settings > Cloud accounts**, as the message names, or cancel the change it prepares, then
change the domain or attach it again.

### "... can move back to Productmind's address only while its own address is still set up in this AWS account"

The environment's Productmind address isn't set up in its account any more, so only an attach can set
one up. Choose a domain you own, or detach the environment and attach it again with Productmind's
address.

### "... is moving to ... now, which already points here"

The new domain points at the environment already, and Productmind is moving it: wait a minute, then
change the domain again if you need to.

### "... has no domain change waiting"

The change was cancelled already, or the environment moved to its new domain. Reload the page to see
where it stands.

### "The development environment deploys under shop.example.com. Move it to another domain first"

**Remove** takes only a domain no environment uses or prepares. Change that environment's domain, or
cancel the change that prepares it, first.

### "The development environment may still run under before.example.com until its next deploy"

The environment moved to a new domain and hasn't deployed since, so it may still run under the old
domain, whose zone holds the app's records. Deploy it, by merging a pull request into its branch or
choosing **Deploy now**, then remove the domain.

### "This environment's new domain is still being written to its deploy settings"

Productmind is still writing the environment's new domain to its deploy settings. **Deploy now** comes
back on the row once they are written: choose it then.

### "Productmind couldn't set up the DNS zone for app.example.org in the AWS account"

Choose **Check again** on the row to try once more; if it fails again, contact Productmind support.

### "Productmind can't reach the AWS account to set up the DNS zone for app.example.org"

Open the account in **Settings > Cloud accounts** and check that it is ready, and for your own AWS
account that its connection still works, then choose **Check again** on the row.

### "Productmind could not use the role in the AWS account for app.example.org's DNS zone"

The role in your own AWS account refused Productmind: its stack isn't in place with the connection's
ExternalId, or a resource control policy refuses Productmind's worker. Fix it as [Cloud
accounts](/user-guide/settings/workspace-settings/cloud-accounts#productmind-could-not-use-the-role-in-aws-account-111122223333)
says, then choose **Check again** on the row.

### "Productmind couldn't check public DNS for app.example.org"

Choose **Check again** in a few minutes; if it fails again, contact Productmind support.

### "Productmind's address ... can't be used for this environment any more"

Cancel the change, then change the domain to one you own, or contact Productmind support.

### "Productmind stopped checking app.example.org after seven days"

A change's new domain didn't point at its zone within seven days. Point it at the name servers under
**DNS records**, then choose **Check again** on the row, which checks for seven more days.

## Related topics

- [Domains](/user-guide/settings/workspace-settings/domains)
- [Whole domains](/user-guide/settings/workspace-settings/whole-domains)
- [DNS records](/user-guide/settings/workspace-settings/dns-records)
- [Cloud accounts](/user-guide/settings/workspace-settings/cloud-accounts)
- [Deploys](/user-guide/settings/workspace-settings/deploys)
