Skip to main content
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: For what gets a certificate and where TLS ends, see TLS certificates.
This page applies to environments that Ryvn provisions. On an existing cluster that you connect to Ryvn, you manage domains, DNS, and TLS certificates yourself.

Add a domain to an installation

Add the domain to a port’s domains in the installation’s spec.networking. In the Ryvn Dashboard, open the installation’s Settings > Networking tab and select Add a custom domain.
The domain is served on the public network when the port is 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: 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. 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:
While a record is missing or wrong, the Endpoints section lists the domain’s records and their status:
To check a record yourself, query public DNS:
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:
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 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:
  1. 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:
The response lists the nameservers from the dashboard. Once it does, your installations are reachable under the new domain.
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 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. 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).

Next steps

  • Networking: how the private, internal, and public networks fit together.
  • Routes: path-based routing and TLS passthrough for a domain.