> ## Documentation Index
> Fetch the complete documentation index at: https://ryvn.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Domains and TLS

> Use your own domains for an installation or a whole environment, with TLS certificates that Ryvn issues and renews

Every address that Ryvn serves gets a TLS certificate, with no setup. By default, the addresses are in your
environment's `ryvn.run` domain. To serve an installation on a domain you own, such as `app.example.com`, add the
domain and create two DNS records. Ryvn then issues the domain's certificate, renews it, and serves the domain over
HTTPS.

You can use your own domain in two ways:

* [Add a domain to an installation](#add-a-domain-to-an-installation), for example `app.example.com` for your web
  app.
* Set a [custom root domain](#custom-root-domain), so every installation in the environment gets an address under
  your domain, such as `web.staging.example.com`.

For what gets a certificate and where TLS ends, see [TLS certificates](#tls-certificates).

> [!NOTE]
>
> This page applies to environments that Ryvn provisions. On an [existing cluster](https://ryvn.ai/docs/provision/existing-cluster.md) that
> you connect to Ryvn, you manage domains, DNS, and TLS certificates yourself.

## Add a domain to an installation

> [tab] Server
>
> Add the domain to a port's `domains` in the installation's `spec.networking`. In the
> [Ryvn Dashboard](https://control.ryvn.app), open the installation's **Settings > Networking** tab and select
> **Add a custom domain**.
>
> ```yaml theme={null}
> # web installation
> spec:
>   networking:
>     ports:
>       - number: 3000
>         public: true
>         domains:
>           - app.example.com
> ```
>
> The domain is served on the public network when the port is public, and on the internal network otherwise.

> [tab] Helm chart
>
> Add the domain to the `domains` of a [Route](https://ryvn.ai/docs/networking/routes.md) in your chart.
>
> ```yaml theme={null}
> # templates/route.yaml
> apiVersion: networking.ryvn.app/v1alpha1
> kind: Route
> metadata:
>   name: web
> spec:
>   exposure: [public]
>   domains: [app.example.com]
>   rules:
>     - to: [{ name: web, port: http }]
> ```
>
> The domain is served on the public network when `exposure` includes `public`, and on the internal network
> otherwise.

### Create the DNS records

If you manage the domain's DNS outside Ryvn, create two CNAME records for it at your DNS provider:

| Record | Name | Value |
| - | - | - |
| Certificate | `_acme-challenge.app.example.com` | `_acme-challenge.48a1541b.production.acme-7fk2q.ryvn.run` |
| Routing | `app.example.com` | `origin.production.acme-7fk2q.ryvn.run` |

The certificate record lets Ryvn issue and renew the domain's TLS certificate. The routing record points the domain
at your environment's public load balancer. The values differ for each domain and environment, so copy them from
[the dashboard or the CLI](#check-the-dns-records).

After you create both records, Ryvn issues the certificate and serves the domain over HTTPS. This can take a few
minutes.

Keep both records for as long as you use the domain. Without the certificate record, the certificate can't renew. If
your DNS provider proxies traffic, turn that off for both records. A root domain such as `example.com` can't have a
CNAME record, so use a subdomain such as `app.example.com`.

A custom domain on the internal network needs only the certificate record. Point the domain at the environment's
internal load balancer in your own private DNS.

### Check the DNS records

In the dashboard, open the installation's **Settings > Networking** tab. A domain that still needs records shows
**Complete DNS setup**, which lists each record's type, name, value, and status.

With the CLI, describe the installation:

```bash theme={null}
ryvn describe installation web -e production
```

While a record is missing or wrong, the `Endpoints` section lists the domain's records and their status:

```text theme={null}
Endpoints:
  - https://app.example.com
    Exposure: public
    Port:     http (3000)
    State:    Pending
    Reason:   Add a CNAME record for app.example.com pointing to origin.production.acme-7fk2q.ryvn.run at your DNS provider.
    DNS records:
      CNAME app.example.com -> origin.production.acme-7fk2q.ryvn.run (Missing)
      CNAME _acme-challenge.app.example.com -> _acme-challenge.48a1541b.production.acme-7fk2q.ryvn.run (Missing)
```

| Record status | Meaning | What to do |
| - | - | - |
| `Missing` | Ryvn can't find the record in public DNS. | Create the record, then wait for it to propagate. |
| `Mismatch` | The record points to a different value. | Change the record to the value Ryvn shows. |
| `Valid` | The record is correct. | Nothing. The address turns `Active` once both are valid. |

To check a record yourself, query public DNS:

```bash theme={null}
dig +short app.example.com CNAME
```

It prints the routing record's value, `origin.production.acme-7fk2q.ryvn.run.` in this example.

## Choose your Ryvn hostname

Ryvn names a server installation's public hostname after the installation. To use another name on the same domain,
add it to the port's domains, for example `app.production.acme-7fk2q.ryvn.run` instead of
`web.production.acme-7fk2q.ryvn.run`:

```yaml theme={null}
# web installation
spec:
  networking:
    ports:
      - number: 3000
        public: true
        domains:
          - app.production.acme-7fk2q.ryvn.run
```

The new name replaces the generated one, and the old address stops working. Pick a name that isn't already in use.
Ryvn creates the DNS record and the certificate, so there are no records for you to add. Your own domains keep
working next to it.

In a Helm chart, a [Route](https://ryvn.ai/docs/networking/routes.md) serves the names you list in its `domains`, so you choose the hostname
there.

## Custom root domain

By default, Ryvn environments use `ryvn.run` subdomains for public addresses. You can replace this with your own
domain, so that every installation in the environment is reachable under it: `web.staging.example.com` instead of
`web.staging.acme-7fk2q.ryvn.run`.

A common pattern is one subdomain per environment, like `staging.example.com` or `production.example.com`. Each
environment's addresses stay under their own name, and the rest of `example.com` stays with your existing DNS
provider.

This is an environment-wide setting. You delegate the domain to Ryvn once, in the steps below. Every installation
then gets its DNS record and TLS certificate with no setup for each one. Helm charts that use
`{{ .ryvn.env.state.public_domain.name }}` resolve to your domain with no config changes.

**1. Set the domain in your environment config**

1. Go to your environment's **Settings** > **Infrastructure**
2. Add `public_root_domain` to your environment config:

```yaml theme={null}
public_root_domain: staging.example.com
```

3. Save and provision the environment

**2. Get the nameservers**

After provisioning completes, the assigned nameservers appear in **Settings** > **Infrastructure** under the
**Domain Setup** section, as a list of NS records to create.

**3. Delegate your domain**

At your DNS provider, create NS records that point your subdomain to the nameservers from the previous step:

1. Log in to your DNS provider, such as Cloudflare, Namecheap, GoDaddy, or Route 53
2. Add an NS record for your subdomain, such as `staging`, for each nameserver Ryvn provided

This delegates only the subdomain to Ryvn. The rest of your domain stays with your existing DNS provider.

**4. Verify**

Check the delegation:

```bash theme={null}
dig staging.example.com NS
```

The response lists the nameservers from the dashboard. Once it does, your installations are reachable under the
new domain.

> [!NOTE]
>
> You can also delegate a full domain, such as `example.com`, by changing its nameservers to the ones Ryvn provides.
> This moves DNS control for the entire domain to Ryvn, so coordinate with the Ryvn team if the domain has existing
> records.

After setup, new installations get addresses under your domain with TLS certificates. You can still
[add a domain to an installation](#add-a-domain-to-an-installation) that needs a different domain entirely.

## TLS certificates

Ryvn issues a certificate for each address it serves, with Let's Encrypt, and renews it before it expires. Ryvn also
redirects HTTP requests to HTTPS.

| Address | Example | Certificate |
| - | - | - |
| [Public](https://ryvn.ai/docs/networking/overview.md#public-the-internet) address | `web.production.acme-7fk2q.ryvn.run` | Issued when you expose the port. |
| [Internal](https://ryvn.ai/docs/networking/overview.md#internal-your-vpc-and-connected-networks) address | `web.internal.production.acme-7fk2q.ryvn.run` | Issued when you expose the port. |
| Custom domain | `app.example.com` | Issued when the domain's [certificate DNS record](#create-the-dns-records) resolves. |
| [TLS passthrough](https://ryvn.ai/docs/networking/overview.md#tls-passthrough) domain | `api.example.com` | None. Your app serves its own certificate. |

To see whether an address is ready, run `ryvn describe installation web -e production` and check the address's
`State` in the `Endpoints` section. An address is `Active` once its certificate is issued.

TLS ends inside the environment, at Ryvn's gateway. To also encrypt connections between installations inside the
environment, enable [traffic encryption (mTLS)](https://ryvn.ai/docs/networking/traffic-encryption.md).

## Next steps

* [Networking](https://ryvn.ai/docs/networking/overview.md): how the private, internal, and public networks fit together.
* [Routes](https://ryvn.ai/docs/networking/routes.md): path-based routing and TLS passthrough for a domain.
