Convivy Builder

Your own Cloudflare account

Builder shares an app with a few people you name, through Cloudflare Access, from a Cloudflare account and a domain that belong to you. This page takes you from having no Cloudflare account to a domain Cloudflare serves, ready to share from. Like a bead, it describes Builder as it is designed to work.

How sharing works

A shared app has its own address on your domain, such as plans.example.com, and Cloudflare stands in front of it. A viewer opens the link and enters their email address. If the app's list allows that address, Cloudflare emails them a one-time code, which expires after ten minutes. Nobody needs a password or an account to see the app. You can let one person in or out without affecting anyone else, and Cloudflare records every login.

Builder's sharing command sets this up for each app. It creates the app's address, creates the Access application in front of it, and keeps the lists of people allowed in. Several apps can share one list, such as a client's staff.

Why the account is yours

The people you share with join your account's list of users and nobody else's.

Access counts seats per account. The free plan covers 50 people. A person takes one seat the first time they log in, however many of your apps they can reach. Sharing with a client's staff spends your seats, so count them before you share with a large client.

1. Create the account

Sign up at dash.cloudflare.com with an email address you intend to keep. The free plan covers everything on this page. Turn on two-factor authentication, because this account decides who can see every app you share.

2. Add your domain

Cloudflare serves your domain once the domain's registrar points it at Cloudflare's nameservers. Add the domain in the dashboard, and Cloudflare will scan your current DNS records and copy them. Compare its list with the records at your current DNS provider before you go further. A record the scan missed stops working when the nameservers change.

Turn off DNSSEC before you switch

If DNSSEC is on at your registrar, turn it off first, and wait for the change to reach the registry before you touch the nameservers. With DNSSEC on, the registry holds a DS record vouching for your old provider's signing keys. Cloudflare signs with different keys, so every resolver that checks DNSSEC rejects Cloudflare's answers, and the whole domain stops resolving, website and email alike.

After you turn DNSSEC off at the registrar, the DS record can take up to 24 hours to clear. Check it with:

dig +short DS example.com

When that prints nothing, you can switch. Once the domain is active on Cloudflare, turn DNSSEC back on from the domain's DNS settings, so the domain regains the protection it had. Cloudflare gives you a new DS record, which you add at your registrar.

Switch the nameservers

Cloudflare gives you two nameservers. At your registrar, replace the domain's nameservers with those two. Cloudflare marks the domain Active once it sees the change, and emails you.

Move your email forwarding

If your registrar forwards mail sent to your domain on to another inbox, that forwarding stops when the nameservers change. Cloudflare Email Routing replaces it. Set it up as soon as the domain is active:

  1. In the domain's DNS records, delete the MX records Cloudflare copied from your registrar. Email Routing refuses to onboard a domain while they remain.
  2. Open Email Routing at the account level: Compute → Email Service → Email Routing → Onboard Domain. The Email menu inside the domain is a different page.
  3. Add the address mail should go to. Cloudflare sends it a verification link, and the address shows as Verified once you follow it.
  4. Create a rule for each address you receive mail at, or one catch-all rule. Set its action to Send to an email, and make sure it is Active.

For a few minutes after the switch, some senders still deliver to your old mail servers, because their resolvers keep the old MX records for that long.

If a message bounces with 550 5.1.1 Address does not exist from a server named route*.mx.cloudflare.net, the mail reached Cloudflare and no rule forwarded it. Check that the destination shows Verified, and that a rule matching the address, or the catch-all, is Active with the action Send to an email.

Set GitHub Pages records to DNS only

If any record points at a site hosted on GitHub Pages, set that record to DNS only, which shows as a grey cloud. Left Proxied, it can stop GitHub renewing the site's certificate.

3. One certificate per domain for cloudflared

An app served from your own machine reaches its viewers through a Cloudflare Tunnel, which the cloudflared program runs. The app itself listens only on your machine, so the tunnel is the only way in.

cloudflared tunnel login asks you to choose one domain, and writes a certificate for that domain alone to ~/.cloudflared/cert.pem. cloudflared uses that certificate whenever it creates a DNS record. Given a hostname in another domain, cloudflared tunnel route dns reports no error. It creates the record inside the certificate's domain instead, so asking for app.example.org with a certificate for example.com creates app.example.org.example.com.

Whoever holds one of these certificates can change DNS records in its domain, so keep the files private, as you would a password.

If you have more than one domain, keep a certificate for each. After each login, rename cert.pem after its domain, then log in again for the next one:

cloudflared tunnel login
mv ~/.cloudflared/cert.pem ~/.cloudflared/example-com-cert.pem

Pass the matching certificate every time cloudflared creates a record. The --origincert option goes after tunnel and before the command, and cloudflared rejects it anywhere else:

cloudflared tunnel --origincert ~/.cloudflared/example-com-cert.pem route dns my-tunnel app.example.com

Setting TUNNEL_ORIGIN_CERT to the certificate's path does the same.

4. The API token

Builder's sharing command works on your account through an API token you create, limited to your account's domains and to Access. Create it under My Profile → API Tokens → Create Token, as a custom token covering your account and the domains you share from. It needs permission to edit DNS records, Cloudflare Tunnels, and Access applications and policies.

Use a token rather than your Global API Key. The key can do anything your login can, in every account you belong to, and a token can do only what you gave it.

Handle the token as a password. Keep it out of repositories, chats and shared documents, and if it is ever exposed, revoke it on the API Tokens page and create a new one.