Addresses, DNS and HTTPS

The two domains

In the portal: Setup wizard, step 1, or Admin, Settings, Addresses

Domain is the address colleagues open, for example apps.example.com. Every link cyantula writes (in a mail, in Slack, in a sign-in callback) is built from it.

Every app gets a name under that same domain: crm.apps.example.com. So you need two DNS records pointing at the server, or at the Cloudflare tunnel in front of it:

• apps.example.com
• *.apps.example.com (a wildcard record)

With a Cloudflare API token cyantula creates these records itself. Only fill in Apps domain (under Advanced) when apps should live on a different domain than the portal.

Names apps may not take lists the names your company already uses on that domain (ftp, webmail, vpn, autodiscover). An app's name becomes its address, so cyantula refuses those for new apps.

How traffic reaches the server

Pick one. The form only shows the settings of the mode you pick.

• Through Cloudflare. A Cloudflare tunnel in front handles HTTPS and forwards to port 8080 on the server. No ports have to be open to the internet. The easiest choice when your domain is already on Cloudflare.
• Straight to this server. The DNS records point at the server, which answers on ports 80 and 443 itself, with certificates you upload or that Let's Encrypt issues.

Cloudflare API token

With this token cyantula creates the tunnel, runs it on the server, and adds a DNS record for the portal and for every new app. Without it you set up the tunnel and the hostnames by hand.

1. Open My Profile, API Tokens in the Cloudflare dashboard and click Create Token, then Create Custom Token.
2. Give it these permissions:
   • Zone, DNS, Edit
   • Zone, SSL and Certificates, Edit
   • Account, Cloudflare Tunnel, Edit
3. Under Zone Resources, include only the zone of your apps domain. Under Account Resources, your account.
4. Create the token, copy it, and paste it in Cloudflare API token. Fill in Cloudflare zone only when it differs from the apps domain, for example example.com when apps live under apps.example.com.

Straight to the server: certificates

Ports 80 and 443 must be open on the server. The installer opens them when they are free; later you can run:

cyantula configure --ports direct

Then choose how the server gets its certificates:

• Upload them. A certificate for the portal address and a wildcard certificate for *.apps.example.com, each with its private key, in PEM format and without a passphrase. Include the intermediate certificates. The wildcard does not cover the portal address itself, so the portal needs its own.
• Let's Encrypt. Fill in Email for automatic certificates and the server requests a certificate for the portal over port 80. A wildcard cannot be issued this way, so you still upload the wildcard for apps.

Trying it out first? Point ACME directory URL (under Advanced) at the Let's Encrypt staging directory so a test does not use up the production limits.

Check that it works

The setup wizard asks your browser to reach the portal over HTTPS before it finishes, and warns you when nothing answers, when the certificate is refused, or when another server answers. You can finish anyway while DNS is still on its way.

Later, the card at the top of the Addresses page checks that every published app has its DNS record and every custom domain its certificate. Added the Cloudflare token after apps were already published? Fix creates the records those deploys skipped.