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

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.

Always disable HTTP to HTTPS redirection in proxy services like Cloudflare