How to assign a domain to a Beach instance

Overview

You will need the following before starting with this tutorial:

• a Beach production instance with a Neos website or Flow application
• access to a domain which you registered with a third-party registrar
• access to the DNS configuration for your domain

In this tutorial we will set up two domains for an instance:

• www.example.com is the main domain visitors of the website will be using
• example.com will redirect visitors automatically to www.example.com

Switch DNS to Beach

When your instance looks fine and is ready to go live, you can set up DNS of your domain(s) so that traffic will end up in Beach. The exact steps depend on your actual registrar / DNS provider, but most should look very similar to the following example.

Domains with a subdomain (for example www.example.com) can be configured as a regular CNAME record. The "canonical" domain will be ingress.h9acc4.flownative.cloud. Here's an example for a correct CNAME record:

Zone apex / root domain

Domains without a subdomain (for example example.com) are a bit special. They are called "zone apex" or "root domain" and are not allowed to CNAME to another domain. The domain name system requires them to have an "A" or "AAAA" record instead, which points to an IP address instead of a domain name.

If you want to use a root domain, you need a DNS provider which supports emulating a CNAME for root domains (they will in fact create an A or AAAA record, but make sure that it automatically and always points to the IP adress of the domain you specified). These special CNAMEs are called a bit differently depending on the provider – here are some examples:

• Cloudflare calls it "ACNAME"
• dnsimple calls it "ALIAS"
• dnsmadeeasy calls it "ANAME"

That means: you will need a DNS service which supports these kinds of special CNAMEs in order to point example.com to Beach. You should avoid creating an A or AAAA record and use the IP address of ingress.h9acc4.flownative.cloud directly, because that IP address may change in the future!

The correct ingress

We used ingress.h9acc4.flownative.cloud above. If your project is in it's own cluster, you have to use the matching ingress. On the overview of your domain in Beach you'll find a list of those.

Get an SSL certificate for your domain

As soon as the DNS changes are active for your domains, Beach will automatically obtain SSL certificates. Beach uses "Let's Encrypt" as a certificate provider. Therefore, in order to obtain a certificate, the HTTP-traffic for a given domain must end up in Beach, so that Beach can prove that it is responsible for that domain.

Adding multiple domains

If you want to add multiple domains to an instance, it is cumbersome to do this individually. There is a better way.

Log in to the Beach user interface and navigate to the "Domains" section of your organisation. Then click on the "Add many domains" button. In the following dialogue, you can then add one domain per line. And with a little trick, you can even set up redirects and instance assignments right away.

To do this, simply add a colon after the domain name, followed by

• a domain name to create a redirect or
• an instance UUID to make an assignment.

Here's an example:

Solving typical problems

Especially if you are using a DNS service which acts as a proxy (for example Cloudflare), there the are a couple of settings which can break the automatic retrieval of certificates. If Beach can't obtain a certificate for your domain, read on to understand how this process works under the hood.

In order to get a new certificate from the Let's Encrypt certificate authority, Beach must prove that it is authorized to do so. This is realized by a "challenge": Let's Encrypt tells Beach to respond with a specific token when it tries to access the domain through a special URL. This URL will be requested via HTTP (not HTTPS, because – well – there's no certificate yet for a secure connection) and it looks something like this:

http://www.example.com/.well-known/acme-challenge/www.example.com

Therefore it is important that any request to your domain using HTTP and this special path can reach the Beach certificate manager. It's also important that this URL stays working in the future, because Let's Encrypt certificates are only valid for about 3 months and need to be renewed.

Turn off HTTP to HTTPS redirects

One feature provided by most proxy services will break the certificate automation: if the service redirects all HTTP requests to HTTPS right away, there is no way for Let's Encrypt to access the ".well-known" URL via HTTP.

You need to switch such a feature off for certificates to work.

If in doubt, try calling the Challenge-URL in your browser (see above). It should return a 404 Not Found error or the current challenge token. It should not redirect you to HTTPS or return anything else.