Serving an app at your own domain

osyrin app domain list|add <hostname> [--env <slug>]|check <hostname>|primary <hostname>|remove <hostname> [--yes] --app <slug> [--server <url>] [--json]

A custom domain serves one of an app's environments at a name you own, like app.example.com. `osyrin app domain add` points the name at an environment and prints the two DNS records to publish — a TXT that proves the name is yours and a CNAME that routes it. It serves nothing until a check finds both; then the platform issues its certificate.

Summary#

osyrin app domain add app.example.com --env prod --app billing-acme answers the two records to publish at your DNS provider. Once they are there, osyrin app domain check app.example.com --app billing-acme reads DNS and says what it found; the platform also checks on its own and issues the certificate.

Signature#

osyrin app domain list --app <slug> [--server <url>] [--json]
osyrin app domain add <hostname> [--env <slug>] --app <slug> [--server <url>] [--json]
osyrin app domain check <hostname> --app <slug> [--server <url>] [--json]
osyrin app domain primary <hostname> --app <slug> [--server <url>] [--json]
osyrin app domain remove <hostname> [--yes] --app <slug> [--server <url>] [--json]

Description#

Two records, then a certificate. add creates the domain unverified and prints:

record	name	value	what it is for
TXT	`txtName`	`txtValue`	proves the name is yours
CNAME	`routeName`	`routeTarget`	routes the name to the platform

A name that cannot take a CNAME (the apex of a zone, example.com) takes an A record to the addresses list shows once a check has read them. Once both records are right the platform asks for a certificate for the name, proved by the name pointing here — usually a few minutes, at most an hour. No third record is needed for it.

A check says what it found. check reads DNS now and answers whether the TXT and the route were found, with the values it read beside the ones it wants. The platform also checks every domain on its own until it verifies, and gives up after a while; list says so.

It serves one environment. --env names the environment the domain serves; left out, the app's only environment is used, and with several the command names them and asks. primary makes a verified domain the app's main name.

What changes once its certificate is issued#

The platform address sends visitors to your domain. Once the domain the environment is known by — its primary domain, or its one verified domain — has its certificate, a browser opening the platform address (billing-acme.osyrin.app/orders/7) is redirected to the same page on your domain (app.example.com/orders/7), so the name people bookmark and search engines index is yours. Old links keep working: they arrive at the platform address and are sent on. Until the certificate is issued both names serve the page, because a redirect to a name with no certificate would be a security warning.

Only page visits move. A webhook your app receives, an API call from a script or another service, and anything that is not a browser opening a page are served at the platform address exactly as before, so nothing you registered elsewhere needs changing. The redirect is temporary (307), so removing the domain later sends no visitor's browser to a name that no longer serves.

Its mail is no longer held to a daily number. An app whose production is served on its own domain sends mail that links to that domain, not the platform's, so the plan's daily mail limit stops refusing its sends. The platform still counts them, and its operators are told when an app sends more than 50,000 in a day. An app whose mail was withheld stays withheld.

Removing one stops it at once. remove asks first; --yes answers for you, and with --json (or no terminal) it is refused without it.

Deleting the app releases its domains. Each stops being served, its certificate is let go, and the name is free for anyone to add. If the app is later restored, its domains are added back unverified, with the same DNS records as before. A domain whose records are still published serves again within a minute, and you do not need to change anything. A name that someone else added in the meantime stays with them; the app's Settings page lists each released domain and whether it came back.

The platform's own names are not yours to claim, and a plan may limit how many custom domains an app has — the refusal says so.

Who may manage an app's domains: an Owner or Admin of its organization, or a member of the app who is not only a developer.

--json — list and add print each domain as {id, hostname, environment, verified, primary, stateLabel, txtName, txtValue, routeName, routeTarget, routeAddresses, certificateLabel, checkDetail, lastCheckedAt} (plus redirectNote, the sentence saying that the platform address sends visitors here, once it does); check prints {txtOk, routeOk, detail}.

Examples#

osyrin app domain add app.example.com --env prod --app billing-acme --server https://osyrin.app
osyrin app domain check app.example.com --app billing-acme --server https://osyrin.app
osyrin app domain primary app.example.com --app billing-acme --server https://osyrin.app
osyrin app domain list --app billing-acme --server https://osyrin.app --json