Guides related to Beach

How to assign a domain to a Beach instance

This guide contains all information about assigning a custom domain to your instance, obtaining an SSL certificate and setting up DNS to go live with your website.

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

Set up the domain in Beach

Log in to the Beach user interface and navigate to the "Domains" tab of your organization. Then click the "Add Domain" button in order to configure a new domain.

First add the main domain of your website, in this case www.example.com.

Next, add the domain you want to redirect, in this case example.com.

Don't try to obtain an SSL certificate yet.

Redirect the secondary domain

Now that Beach knows about both of your domains, you can either start using them or redirect one domain to another.

Click the redirect / arrow icon next to the example.com domain. In the dialog enter www.example.com as the domain Beach should redirect to.

Assign the main domain to your instance

Navigate to your instance in the Beach user interface. Click the "Assign Domain" button and choose your primary domain for the instance (in our case www.example.com).

Your instance will now accept traffic for this domain. But for the time being it will only accept http requests, because it does not have an SSL certificate yet.

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 euw1.flownative.cloud. Here's an example for a correct CNAME record:

www.example.com. CNAME euw1.flownative.cloud.

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" 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 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:

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 record and use the IP address of euw1.flownative.cloud directly, because that IP address may change in the future!

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.

Once Beach has successfully obtained a certificate for your domain, it will automatically make sure to keep it updated and obtain a new certificate before the old one expires.

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.