# Domains

Every app gets a free address that keeps working. For your own name, like `app.yourcompany.com`, buy a domain with <Term id="credits">credits</Term>, connect one you own, or add a name under a domain your <Term id="workspace">workspace</Term> already uses. HTTPS turns on by itself.

## Before you start [#before-you-start]

<Callout type="warn" title="Domain purchases are not refunded">
  Buying, and renewing, take [credits](/docs/workspace/credits) at once. Check the name and ending before you buy.
</Callout>

- The <Term id="project">project</Term> should be deployed, or about to be: a domain opens the live version.
- You need to be able to change the project.
- Buying costs credits. Connecting a domain you own, or reusing a connected one, is free.

## Where domains live [#where-domains-live]

- **A project's domains**: open the project on <AppLink to="deploy" />, find **Domains** and select **Manage** to list every address it answers at.
- **All your workspace's addresses**: <AppLink to="settings.domains" /> lists every address for every project. Search by address or project, and filter by **Free address**, **Connected**, **Bought** or **Not used by a project**.

<Screenshot src="/docs/_media/settings-domains-list-of-all-domains.png" alt="The Domains page listing every domain in the workspace" />

## Add a domain [#add-a-domain]

Select **Add domain** and choose **Buy a new domain**, **Connect an external domain** or **Use a connected domain**.

<Screenshot src="/docs/_media/deploy-projects-domains-add-domain.png" alt="The Add a domain page with its three ways to add a domain" />

### Buy a new domain [#buy-a-new-domain]

Pay with credits, and Klarety sets up its records for you.

<Steps>
<Step>
### Find a name [#find-a-name]
Under **Find a name**, type the name you want (for example `yourcompany`), then **Pick an ending**. Each shows its yearly price in credits, or **Taken**. Select **Continue**.
</Step>
<Step>
<Screenshot src="/docs/_media/deploy-projects-domains-buy-domain-search-page.png" alt="Searching for a domain name, with prices per ending" />

### Say who owns it [#say-who-owns-it]
Under **Who owns it**, fill in the owner's name, email, phone and address; the registry records them as owner. The email cannot be changed after you buy, and receives a confirmation link.
</Step>
<Step>
<Screenshot src="/docs/_media/deploy-projects-domains-buy-domain-owner.png" alt="The Owner step when buying a domain" />

### Review and buy [#review-and-buy]
**Review order** shows the domain, the owner, the price for one year, that it **Renews yearly**, and your **Balance after**. Agree to the Terms of Service and select **Buy for X credits**.
</Step>
<Step>
### Confirm the owner's email [#confirm-the-owners-email]

<Callout type="error" title="Confirm within 15 days">
  Without the confirmation, the domain stops working 15 days after purchase.
</Callout>

Click the confirmation link sent to the owner's email.
</Step>
</Steps>

<Screenshot src="/docs/_media/deploy-projects-domains-buy-domain-owner.png" alt="The Review order step when buying a domain, with price and Balance after" />

The domain goes live by itself in a few minutes, HTTPS included.

### Connect an external domain [#connect-an-external-domain]

Free, for a domain you own elsewhere. You add two DNS records where you manage it.

<ForEveryone>

<Steps>
<Step>
### Type the domain [#type-the-domain]
Choose **Connect an external domain**, type the address (for example `app.yourcompany.com`) and select **Connect**.
</Step>
<Step>
### Add the records [#add-the-records]
The page shows two records, each with **Type**, **Name** and **Value**. Add both where you manage this domain's DNS. Some providers want only the part before your domain in **Name**.
</Step>
<Step>
### Wait for it to go live [#wait-for-it-to-go-live]
Klarety checks every few seconds; you can leave the page. The domain moves from **Add the records below** to **Turning on HTTPS** to **Live**, usually within minutes. Keep the records in place while the certificate is issued.
</Step>
</Steps>

<Screenshot src="/docs/_media/deploy-projects-domains-add-domain.png" alt="The two DNS records shown when connecting an external domain" />

</ForEveryone>

<ForDevelopers>

```python
from klarety import Nexus

nx = Nexus.connect()
added = nx.projects.add_domain("PROJECT_ID", "app.yourcompany.com")
print(added)

for domain in nx.projects.domains("PROJECT_ID"):
    print(domain)
```

`add_domain` returns the two records to add at your DNS. The domain goes live once they are found.

</ForDevelopers>

<Callout type="warn" title="Root domains">
  For a root domain like `yourcompany.com`, your DNS provider must allow a CNAME record at the root. If it does not, use `www.yourcompany.com`.
</Callout>

### Use a connected domain [#use-a-connected-domain]

Free. Add a new name under a domain already on Klarety, for example `api.yourcompany.com` under `yourcompany.com`.

Choose **Use a connected domain**, pick one of **Your domains**, type a **Name** (for example `api`) and select **Add**. Leave it empty to use the domain itself, if no other app uses it. The app answers there at once.

## Choose what a domain opens [#choose-what-a-domain-opens]

When an app has several parts, each domain opens one. **Answered by** shows which (by default, the main part). To change it, select **Change what it opens**, pick the part and select **Save**.

<ForDevelopers>

```python
nx.projects.point_domain("PROJECT_ID", "api.yourcompany.com", service="api")
```

`service=None` points it back at the app's main part.

</ForDevelopers>

## Renewal of a bought domain [#renewal-of-a-bought-domain]

A bought domain shows when it **Renews from credits**, or when it **Expires** if renewal is off.

- **Renewal on**: in its last 30 days, the domain renews for a year from your credits. If there are not enough credits, Klarety tries again each day until it expires.
- **Turn off renewal**: it will not renew. When it expires, your app stops answering there, and someone else may buy it.
- **Renew a year now**: renews for one more year straight away, paid from credits now and not refunded.

## Move a domain to another registrar [#move-a-domain-to-another-registrar]

Select **Move to another registrar** and confirm. Klarety unlocks it and shows a **Transfer code** for your new registrar. It stops renewing here. A domain bought in the last 60 days cannot move yet.

## Remove or release a domain [#remove-or-release-a-domain]

- **Remove** takes a domain off a project; the app stops answering there at once. You can add it again later.
- When a project is deleted, its domains show **Not used by any project**. Select **Use for this project** to give one to another project, or **Release** to let it go: its certificate is dropped and anyone who owns it can add it again. A domain bought here stays bought and keeps its renewal.

## If something goes wrong [#if-something-goes-wrong]

- **The domain stays on Add the records below**: check both records match exactly, including **Name** as your provider expects. Some providers are slow to publish changes.
- **"That does not look like a domain"**: use letters, digits, dashes and dots, like `app.yourcompany.com`.
- **"Not enough credits for this domain"**: select **Add credits**, then buy.
- **A bought domain stopped working**: check that the owner clicked the confirmation link within 15 days.
- **"Only people who can change this project can add a domain"**: ask the project's owner or an admin.

## Where to go next [#where-to-go-next]

- [Deploy an app](/docs/deploy/deploy-an-app)
- [Credits](/docs/workspace/credits)
- [Logs](/docs/deploy/logs)