OrbitsDocs
esc
    Open Orbits
    DomainsCustom domains

    Add a custom domain

    Point a domain you own at a project with one DNS record or with Orbits DNS. Orbits verifies it, issues and renews its certificate, and tells you when something needs attention.

    You can add a domain from a project's Domains page or from the team's Domains and DNS page. From the project, it's linked to that project at once; from the team page, choosing a project is optional.

    1. Add the domain

    Press Add domain and type the address you want visitors to use, such as shop.example.com. Orbits tidies what you type: a scheme, a path or a trailing dot comes off, and it's lower-cased.

    Then choose what it serves (production, a preview branch, or a redirect; see what a domain can serve) and how its DNS is set up:

    • Add one record: keep your DNS provider and add a single record there.
    • Use Orbits DNS: hand the domain's DNS to Orbits. See Orbits DNS.

    As you type, the dialog's note says what adding the name will do before anything is saved: the record it needs, the Orbits DNS zone it falls in if your team has one, or the nameservers to set. A name inside a zone your team already runs on Orbits DNS is on Orbits DNS too, and Orbits creates its record for you: there's nothing to add.

    If your team already has the domain and it serves nothing yet, adding it from a project links it to that project.

    2. Add the record

    With Add one record, the next step shows the one record to add at your DNS provider.

    DomainRecordNameValue
    A subdomain, such as shop.example.comCNAMEshopcname.theorbits.app
    An apex, such as example.comA@The address the domain's page shows

    A CNAME can't sit at an apex, so an apex gets an A record. Copy the value from the domain's page rather than from these docs.

    A subdomain also counts as pointing here if your provider flattens the CNAME into A records with Orbits' address alone.

    There's no TXT record to add: DNS pointing at Orbits is the proof that the domain is yours.

    3. Verification

    Orbits looks for the record:

    • as soon as you add the domain;
    • every minute while it waits (every 15 minutes once it has waited a day);
    • every 10 minutes once it's valid, so a record that changes later is noticed;
    • at once when anyone presses Check now (a domain checked in the last 10 seconds isn't looked up again).

    Orbits asks your domain's own nameservers, so a record you just added is seen straight away rather than after a cached "no such name" expires. Your visitors' own resolvers may still need a little time.

    The domain page shows the state, the record it needs and what the last check found, with Last checked:

    StateWhat to do
    Waiting for DNSNothing was found yet. Add the record, then press Check now.
    ValidDone: the certificate follows.
    MisconfiguredSomething is there, but it points elsewhere ("We found CNAME old-host.example.net where Orbits expects cname.theorbits.app"). Change the record at your provider.

    A failed lookup on Orbits' side changes nothing: a valid domain stays valid.

    4. The certificate

    Orbits issues a certificate for each hostname on its own, from Let's Encrypt (an HTTP-01 challenge), once the domain points here and serves a project. You don't upload anything.

    CertificateMeaning
    Nothing to secure yetThe domain isn't pointing here, or isn't in use.
    Waiting for DNSDNS points here and the certificate is being issued. Orbits waits until public DNS answers for the name before asking for it, which can take a few minutes for a new domain.
    ActiveIssued, with its dates. The domain is now served.
    FailedThe last try failed. Orbits tries again 5, 15, 30 and then 60 minutes after each failure.

    The domain only starts serving once its certificate is there. A certificate renews by itself about 30 days before it expires.

    A certificate can fail when the domain stops pointing here before it is issued. If your domain has CAA records, they must allow Let's Encrypt.

    Emails about your domain

    • DNS needed: an hour after you add a domain, if its record still isn't there, the person who added it gets one email with the record to add.
    • Domain live: when its certificate arrives, the person who added it gets one email.
    • A domain or certificate needs attention: when a domain's DNS moves away from Orbits (misconfigured), when a certificate can't be issued, or when one is within 14 days of expiring and hasn't renewed. This goes to everyone who can deploy, and to Slack, Microsoft Teams and webhooks, when the team's notification switch for it is on. See notifications.

    Turning the team's domain notification switch off stops all of them.

    Change what a domain serves

    On the domain's page, the hostname card shows what it serves. Change points it at another project, a branch, production again, a redirect, or nothing. The name and its DNS mode can't change: remove the domain and add it again.

    Remove a domain

    Remove domain on the domain's page, after the confirmation. The project stops answering on it within a minute and its certificate is deleted. The record at your DNS provider stays until you delete it there.

    Troubleshooting

    It stays Waiting for DNS. Check the record's name and value exactly, at the provider that actually hosts the domain's DNS (the one its nameservers point to). Some providers want the name without the domain (shop), others the full name. Then press Check now.

    It's Misconfigured. Look at what the domain page says it found. An old CNAME, an AAAA record, or an A record to another host are the usual causes.

    The certificate failed. Make sure the domain still points here and nothing else at the name answers. Orbits retries on its own.

    The API for domains is in domains.

    Was this page helpful?

    Updated