Custom domain on preview env - Add example and best practice when using www for the production URL

[nicogommen]

Where on docs.platform.sh should be changed?

https://docs.platform.sh/domains/steps/custom-domains-preview-environments.html

What exactly should be updated?

We have received several feedback or support tickets from users confused about how to configure a preview environment domain when the objective is to have the following result:

• Production URL => www.example.com
• Preview environment URL => staging.example.com

Configuration usually tried

The configuration usually tried to achieve this is the following:

Domain added on the production environment of the project:

• example.com (default)

Domain added on the staging environment of the project:

• staging.example.com (attached to example.com)

Routes.yaml:

"https://www.{default}/":
    type: upstream
    upstream: "drupal:http"

"https://{default}/":
    type: redirect
    to: "https://www.{default}/"

But the issue with that configuration is that the staging URL ends up being www.staging.example.com instead of staging.example.com.

Workaround

To workaround this issue, users have to also add the domain www.example.com on the production environment of the project, and attach the staging environment domain to it, as follows:

Domain added on the production environment of the project:

• example.com (default)
• www.example.com

Domain added on the staging environment of the project:

• staging.example.com (attached to www.example.com)

It works, but it's not ideal to have to add the 2 production domains, and it might lead to issues when using placeholders and multiple domains.

Recommended configuration

Our recommended configuration is to use the short URL as the main route serving the application, and have the www URL redirects to it, as follows:

Domain added on the production environment of the project:

• example.com (default)

Domain added on the staging environment of the project:

• staging.example.com (attached to example.com)

Routes.yaml:

"https://{default}/":
    type: upstream
    upstream: "app:http"

"https://www.{default}/":
    type: redirect
    to: "https://{default}/"

This works better for all use cases, but it doesn't exactly meet the initial objective described above, because the production URL ends up being example.com instead of www.example.com.

Documentation

We would like to document this use case as an example, explaining both the workaround and the recommended solution. Hopefully this will help users to do this configuration on their own, or if not, it will at least give our support team a quick link to share when a ticket is opened.

Additional context

No response