# Domains

This guide shows how to deploy an app and link it to a domain you own (for example, `mydomain.com`).

:::note
Unikraft Cloud can take a few seconds before issuing the certificate.
If there are misconfigurations or DNS changes that your external DNS provider hasn't propagated yet, this can take much longer.
You can check the validation status of the certificate with the CLI (more on this below).
The controller retries at these intervals: [1,5,10,30] minutes, then [1,6,12,24] hours, then it fails.
:::

The setup is complete.
Test the deployment with `curl`.


## Configuring your external DNS provider

Before Unikraft Cloud can launch an app, you need to ensure that you have configured things correctly with your DNS provider:

ALIAS (apex alias) and ANAME (authoritative alias) are DNS record types some providers support.

* For a subdomain you own such as docs.mydomain.com, a CNAME is enough.
  In this case, you can just add a `CNAME` record with your sub-domain (`docs`) as the host and point the record to Unikraft Cloud's metro (for example, `fra.unikraft.app`).

* For an apex domain (for example, mydomain.com), add one of: ALIAS, ANAME, or a flattened CNAME record.
  Depending on your provider, leave the host field empty or enter @.
  Point the record to the metro (for example, `fra.unikraft.app`).
  If the provider doesn't support these record types, add an A record pointing to the metro IP address.

:::tip
You can find information about the Unikraft Cloud metros available to you, as well as their IP addresses, via the CLI.

<CodeTabs syncKey="cli-tool">

```bash title="unikraft"
unikraft metros list
```

```bash title="kraft"
kraft cloud metro ls
```

</CodeTabs>
:::

:::note
You can have many domains for the same service.
Unikraft Cloud also supports wildcard domains.
See the [certificates API](/api/platform/v1/certificates) for details.
:::

## Launching your app

Assume the goal is to use NGINX as an app:

```bash title=""
git clone https://github.com/unikraft-cloud/examples
cd examples/nginx
```

Log into Unikraft Cloud and select a [metro](/platform/metros) close to you.
This guide uses `fra` (Frankfurt, 🇩🇪).
Set the following:

<CodeTabs syncKey="cli-tool">

```bash title="unikraft"
unikraft login
```

```bash title="kraft"
# Set Unikraft Cloud access token
export UKC_TOKEN=token
# Set metro to Frankfurt, DE
export UKC_METRO=fra
```

</CodeTabs>

The `UKC_TOKEN` and `UKC_METRO` environment variables are only supported by the legacy CLI.

With this in place, use the CLI to create an instance of the web server and link it to a custom name.
Unikraft Cloud does this through the domain flag:

<CodeTabs syncKey="cli-tool">

```bash title="unikraft"
unikraft build . --output <my-org>/nginx:latest
unikraft run --metro=fra -p 443:8080/http+tls --domain mydomain.com --image=<my-org>/nginx:latest
```

```bash title="kraft"
kraft cloud deploy -p 443:8080 -d mydomain.com .
```

</CodeTabs>

The resulting output of the `deploy` command should be like:

```ansi title=""
[●] Deployed successfully!
 │
 ├────────── name: nginx-67zbu
 ├────────── uuid: 269019de-f7dc-4077-9568-012ad594ca87
 ├───────── state: running
 ├─────────── url: https://mydomain.com
 ├───────── image: nginx@sha256:6abb4f2ba4501068a84885d7b8b127adaf3d83c25fd43e79d5a142f6d8703c93
 ├───── boot time: 11.13ms
 ├──────── memory: 1024 MiB
 ├─────── service: wispy-moon-dpg6d54i
 ├── private fqdn: nginx-67zbu.internal
 ├──── private ip: 172.16.6.5
 └────────── args: /usr/bin/nginx -c /etc/nginx/nginx.conf
```

When you issue the domain flag, Unikraft Cloud requests a
new certificate from the public certificate authority.

:::note
Issuing the certificate can take a few seconds.
If there are misconfigurations or pending DNS changes, it can take longer.
Check the validation status with the CLI (more on this command below).
The Unikraft Cloud controller retries at these intervals: [1,5,10,30] minutes, then [1,6,12,24] hours, then it fails.
:::

The setup is complete.
Test the deployment with `curl`:

```bash
curl https://mydomain.com
```

## Learn more

* The [CLI reference](/docs/cli/unikraft) and the [legacy CLI reference](/docs/cli/kraft/overview).
* Unikraft Cloud's [REST API reference](/api/platform/v1), in particular the sections on [instances](/api/platform/v1/instances) and [service groups](/api/platform/v1/service-groups).