Custom domains and TLS

Every app answers on https://<app>.rytiv.app with a certificate from the start. A custom domain is added to an app, proven by a DNS record, pointed at Rytiv, and gets its own certificate. Wildcards are not accepted for a single domain; a whole zone can be proven once instead.

1. Add the domain

CLI

ry domains add web www.example.com

curl

curl -X POST "https://api.rytiv.app/v1/apps/web/domains" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "www.example.com"}'

TypeScript

const res = await fetch("https://api.rytiv.app/v1/apps/web/domains", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.RYTIV_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ domain: "www.example.com" }),
});
const { status, dns } = await res.json(); // dns.txt and dns.point: the records to set

Python

import os, requests

domain = requests.post(
    "https://api.rytiv.app/v1/apps/web/domains",
    headers={"Authorization": f"Bearer {os.environ['RYTIV_TOKEN']}"},
    json={"domain": "www.example.com"},
).json()
print(domain["status"], domain["dns"])

The answer is the domain in state pending_dns with the records to set.

2. Set the DNS records

Two things have to be true: you own the domain, and it points at Rytiv.

Record	Name	Value	Proves
TXT	_rytiv.www.example.com	rytiv-verify-<token> from the answer	ownership
CNAME	www.example.com	<slug>.rytivdns.com (or web.rytiv.app)	ownership and traffic
A	example.com	the ingress addresses from the answer	ownership and traffic, for an apex

A subdomain needs the CNAME (the TXT record is offered as well); an apex such as example.com cannot carry a CNAME and gets A records instead. The exact names and values are in the answer of ry domains add and of GET /v1/apps/:name/domains; copy them from there.

3. Wait, or check now

Rytiv checks the records every 30 seconds at first, then with a growing gap up to an hour. ry domains check web www.example.com asks for a check right away.

Status	Meaning
pending_dns	Waiting for the records.
verified	Ownership is proven; the certificate is being ordered.
cert_issued	The certificate exists.
active	The certificate exists and a machine of the app is ready to answer.
error	The certificate could not be issued; error says why. A missing DNS record never leads here, it keeps the domain pending_dns.

ry domains list web

The list shows the status, the days left on the certificate and the records still missing.

Certificates

Rytiv orders the certificate over ACME with an HTTP challenge that the edge answers, as soon as ownership is proven. It is renewed when fewer than 30 days remain. The default address https://<app>.rytiv.app is covered by the platform’s own certificate. Port 80 answers a redirect to HTTPS.

Redirect one domain to another

ry domains redirect web example.com www.example.com
ry domains redirect web example.com --off

The first domain then answers 308 to the second, keeping path and query. The target must be another domain of the same app or its default address; a target cannot itself redirect, and a domain others point at cannot start redirecting, so there are no chains and no loops.

Prove a whole zone once

ry domains zones add example.com

The answer names two CNAME records: _acme-challenge.example.com to a challenge name Rytiv gives you, and *.example.com to Rytiv’s ingress. Once they resolve, every name directly below the zone (app.example.com, api.example.com) is yours without a record of its own and is covered by one wildcard certificate; ry domains add web app.example.com then needs no DNS change. Only one level below the zone is covered.

Remove

ry domains remove web www.example.com

The CLI asks you to type the name; pass --yes in scripts. The certificate is not revoked, the domain simply stops routing.

Errors you will meet

Status	Code	When
400	bad-request	The name is not a domain: a wildcard, an IP, a single label, a platform domain. The sentence says which.
409	shadows-default-address	The domain is the default address of an app.
409	mail-domain	The name is a sending domain of a zone and cannot become an app domain.
409	conflict	The domain is already claimed by someone.