diff --git a/sites/friday/config/_default/config.yaml b/sites/friday/config/_default/config.yaml index 0ab28f4678..feeb07a8a2 100644 --- a/sites/friday/config/_default/config.yaml +++ b/sites/friday/config/_default/config.yaml @@ -63,6 +63,7 @@ module: - "increase-observability/metrics/dedicated-generation-3.md" - "domains/cdn/managed-fastly.md" - "domains/security/web-application-firewall/fastly.md" + - "domains/steps/custom-domains-preview-environments.md" - "dedicated-gen-2/*" - "dedicated-gen-3/*" - "guides/*" diff --git a/sites/friday/src/domains/steps/custom-domains-preview-environments.md b/sites/friday/src/domains/steps/custom-domains-preview-environments.md new file mode 100644 index 0000000000..6f2a244da2 --- /dev/null +++ b/sites/friday/src/domains/steps/custom-domains-preview-environments.md @@ -0,0 +1,287 @@ +--- +title: Set up a custom domain on a preview environment +sidebarTitle: Preview environments +weight: 3 +description: Learn how to set up custom domains on your preview environments +--- + +{{% version/specific %}} +{{< partial "progressive-rollout/body.md" >}} +<---> +{{% /version/specific %}} + +[Preview environments](/glossary.md#preview-environment) in your project can't use the custom domain [set up on your production environment](../steps/_index.md).
+By default and for each preview environment, +{{< vendor/name >}} automatically replaces the custom production domain +with an automatically generated URL. + +If you don't want to use these default URLs, +you can add a custom domain to each of your preview environments +(`staging` or `development` [environment types](/glossary.md#environment-type)). + +To do so, no need to modify your [routes configuration](../../define-routes/_index.md). +When you add a new custom domain for a preview environment, +just attach it to the custom production domain it replaces. +If you have multiple custom production domains, +you need to select which one you're replacing. + +{{< note title="Example" >}} + +You have two environments, a production environment and a staging environment. +You've added the `example.com` custom domain to your production environment. + +You want to add the `staging.example.com` custom domain to your staging environment. +To do so, you need to attach the new `staging.example.com` custom domain +to its corresponding custom production domain `example.com`. + +You can then access your staging environment through `staging.example.com`, +and still access your production environment through `example.com`. + +{{< /note >}} + +If you have multiple custom domains on your production environment, +when you set up a custom domain on a preview environment, +you don't need to update your [routes configuration](../../define-routes/_index.md) either. +{{< vendor/name >}} automatically figures out the routing of your preview environment +based on the following elements: + +- The custom production domains in your existing [routes configuration](../../define-routes/_index.md) +- The custom domains for preview environments attached to each of those custom production domains + +## Before you start + +You need: + +{{% version/specific %}} +- A Grid or {{% names/dedicated-gen-3 %}} project on which you have **admin rights**
+ + {{< note theme="warning" >}} + + If you have a {{% names/dedicated-gen-2 %}} project, + currently you can only add a custom domain to the dedicated environments of your project (production and staging). + To do so, [contact Support](https://console.platform.sh/-/users/~/tickets/open). + + {{< /note >}} + + If you use a [Managed Fastly](../cdn/managed-fastly.md) CDN, + it needs to be configured to operate with custom domains for preview environments. + For more information, [contact Support](https://console.platform.sh/-/users/~/tickets/open). +{{% /version/specific %}} +- A production environment with at least one custom domain already set up +- At least one preview (staging or development) environment +- Optional: The [{{< vendor/name >}} CLI](../../administration/cli/_index.md) (v4.8.0+) + +To prevent abuse, by default you can add custom domains to up to 5 preview environments per project only. +This limit doesn't include the production environment, +and you can increase it without charge. +To do so, [contact Support](/learn/overview/get-support.md). + +{{< note >}} +If you delete a custom production domain, +all of the attached custom domains for preview environments are deleted too. +You need to rebuild the affected preview environments for the deletion to be complete. +{{< /note >}} + +{{% version/specific %}} +If you downgrade from an Elite or Enterprise plan to a Professional plan, +all of the custom domains set up on preview environments are automatically removed. +Downgrading your plan doesn't affect custom domains set up on your production environments. +{{% /version/specific %}} + +## Add a custom domain to a preview environment + +To add a custom domain to a preview environment, follow these steps: + +{{< codetabs >}} ++++ +title=Using the CLI ++++ + +1. To get the target for your preview environment, + run the following command: + + ```bash + {{% vendor/cli %}} environment:info edge_hostname --environment {{< variable "ENVIRONMENT_NAME" >}} + ``` + +2. [Configure your DNS provider](../steps/_index.md#3-configure-your-dns-provider). + In particular, make sure your DNS record points to the target of your preview environment. + + {{< note >}} + + Using the target of your production environment to configure your DNS provider is technically possible, + but {{< vendor/name >}} recommends using the target of your preview environment as a best practice. + + {{< /note >}} + +3. Run a command similar to the following: + + ```bash + {{% vendor/cli %}} domain:add staging.example.com --environment {{< variable "STAGING_ENVIRONMENT_ID" >}} --attach {{< variable "PRODUCTION_CUSTOM_DOMAIN_TO_ATTACH" >}} + ``` + +<---> ++++ +title=In the Console ++++ + +1. Get the target for your preview environment.
+ To do so, navigate to your preview environment and click **{{< icon settings >}} Settings**.
+ Select the **Domains** tab.
+ In the **Configure your domain** section, copy the content of the **CNAME record** field.
+ Save it for later use at step 7. + +2. Click **Add domain**. + +3. Name the custom domain for your preview environment. + +4. Attach the custom domain for your preview environment to the desired production custom domain. + +5. Click **Add**. + +6. Click **Okay**. + +7. [Configure your DNS provider](../steps/_index.md#3-configure-your-dns-provider).
+ In particular, make sure your DNS record points to the target of your preview environment. + +{{< note >}} + +Using the target of your production environment to configure your DNS provider is technically possible, +but {{< vendor/name >}} recommends using the target of your preview environment as a best practice. + +{{< /note >}} + +{{< /codetabs >}} + +{{< note >}} + +You can’t update a custom domain when it's used on a preview environment. +You can only delete it and create a new one as a replacement. + +{{< /note >}} + +### Example + +You've added the `mysite.com` custom domain to your production environment. +You now want to add the `mydev.com` custom domain to a preview environment called `Dev`. + +To do so, follow these steps: + +{{< codetabs >}} ++++ +title=Using the CLI ++++ + +Run the following command: + +```bash +{{% vendor/cli %}} domain:add mydev.com --environment Dev --attach mysite.com +``` + +<---> ++++ +title=In the Console ++++ + +1. Get the target for `Dev`.
+ To do so, navigate to `Dev` and click **{{< icon settings >}} Settings**.
+ Select the **Domains** tab.
+ In the **Configure your domain** section, copy the content of the **CNAME record** field.
+ Save it for later use at step 7. + +2. Click **Add domain**. + +3. Enter `mydev.com` as a name for the custom domain you want to add to `Dev`. + +4. Select `mysite.com` as the production custom domain you want to attach `mydev.com` to. + +5. Click **Add**.
+ +6. Click **Okay**. + +7. [Configure your DNS provider](../steps/_index.md#3-configure-your-dns-provider).
+ In particular, make sure your DNS record points to `Dev`'s target. + +{{< /codetabs >}} + +In the above example, the `Dev` environment needs to exist +for you to add the `mydev.com` custom domain successfully. +If the `Dev` environment is later removed, +the `mydev.com` custom domain is removed too. + +## List the custom domains of a preview environment + +{{< codetabs >}} ++++ +title=Using the CLI ++++ + +Run a command similar to the following: + +```bash +{{% vendor/cli %}} domain:list --environment {{< variable "STAGING_ENVIRONMENT_ID" >}} +``` + +<---> ++++ +title=In the Console ++++ + +1. Navigate to your preview environment and click **{{< icon settings >}} Settings**. +2. Select the **Domains** tab.
+ All the custom domains for your preview environment are displayed. + +{{< /codetabs >}} + +## Get a specific custom domain used on a preview environment + +{{< codetabs >}} ++++ +title=Using the CLI ++++ + +Run a command similar to the following: + +```bash +{{% vendor/cli %}} domain:get staging.example.com --environment {{< variable "STAGING_ENVIRONMENT_ID" >}} +``` + +<---> ++++ +title=In the Console ++++ + +1. Navigate to your preview environment and click **{{< icon settings >}} Settings**.
+2. Select the **Domains** tab.
+ All the custom domains for the selected environment are displayed. +3. To see which actions you can perform on a displayed custom domain, + click **{{< icon "more" >}} More** next to it. + +{{< /codetabs >}} + +## Remove a custom domain from a preview environment + +{{< codetabs >}} ++++ +title=Using the CLI ++++ + +Run a command similar to the following: + +```bash +{{% vendor/cli %}} domain:delete staging.example.com --environment {{< variable "STAGING_ENVIRONMENT_ID" >}} +``` + +<---> ++++ +title=In the Console ++++ + +1. Navigate to your preview environment and click **{{< icon settings >}} Settings**. +2. Select the **Domains** tab.
+ All the custom domains for the selected environment are displayed. +3. Click **{{< icon "more" >}} More** on the custom domain you want to delete. +4. Click **Delete**. +5. Click **Yes, delete**. + +{{< /codetabs >}} \ No newline at end of file diff --git a/sites/platform/src/domains/cdn/_index.md b/sites/platform/src/domains/cdn/_index.md index 5523641134..78557656f9 100644 --- a/sites/platform/src/domains/cdn/_index.md +++ b/sites/platform/src/domains/cdn/_index.md @@ -62,6 +62,8 @@ see your CDN provider's official documentation. When you use a CDN, the {{< vendor/name >}} router [HTTP caching](../../define-routes/cache.md) becomes redundant. To disable it, change your cache configuration for the routes behind a CDN to the following: +{{< version/specific >}} + ```yaml {configFile="routes"} "https://{default}/": type: upstream @@ -70,8 +72,20 @@ To disable it, change your cache configuration for the routes behind a CDN to th # Disable the HTTP cache on this route. It's handled by the CDN instead. enabled: false ``` +<---> + +```yaml {configFile="routes"} +routes: + "https://{default}/": + type: upstream + upstream: "app:http" + cache: + # Disable the HTTP cache on this route. It's handled by the CDN instead. + enabled: false +``` +{{< /version/specific >}} -{{< version/only "1" >}} +{{< version/specific >}} ## Configure your CDN to support high SLA {{< premium-features/tiered "Enterprise and Elite" >}} @@ -85,7 +99,9 @@ If you want {{< vendor/name >}} to limit checks to one or more of the following - Europe - East Asia / Oceania -{{< /version/only >}} +<---> + +{{< /version/specific >}} ## Prevent direct access to your server @@ -139,15 +155,32 @@ To enable client-authenticated TLS, follow these steps: 4. Change your routing configuration for the routes behind a CDN to the following: - ```yaml {configFile="routes"} - https://{default}: + {{< version/specific >}} + +```yaml {configFile="routes"} +"https://{default}": + tls: + client_authentication: "require" + client_certificate_authorities: + - !include + type: string + path: cdn.crt +``` + + <---> + +```yaml {configFile="routes"} +routes: + "https://{default}": tls: client_authentication: "require" client_certificate_authorities: - !include - type: string - path: cdn.crt - ``` + type: string + path: cdn.crt +``` + + {{< /version/specific >}} The procedure can vary depending on your CDN. Contact your CDN provider for specific assistance. diff --git a/sites/platform/src/domains/cdn/cloudflare.md b/sites/platform/src/domains/cdn/cloudflare.md index 668df7a05a..c7c608b2c0 100644 --- a/sites/platform/src/domains/cdn/cloudflare.md +++ b/sites/platform/src/domains/cdn/cloudflare.md @@ -22,7 +22,7 @@ To properly configure your Cloudflare CDN, see the Cloudflare official documentation on [how to get started](https://developers.cloudflare.com/cache/get-started/). Then set up a [custom domain](../steps/_index.md). To get the [DNS challenge to succeed](../troubleshoot.md#ownership-verification), -have your CDN point to your [project's target URL](../../domains/steps/_index.md#2-get-the-target-for-your-project). +have your CDN point to your [project's target URL](../../domains/steps/_index.md#1-get-the-target-for-your-project). ## 3. Handle apex domains diff --git a/sites/platform/src/domains/cdn/fastly.md b/sites/platform/src/domains/cdn/fastly.md index f3e012e788..9fda160dd3 100644 --- a/sites/platform/src/domains/cdn/fastly.md +++ b/sites/platform/src/domains/cdn/fastly.md @@ -35,7 +35,7 @@ To properly configure your Fastly CDN, see the Fastly official documentation on [how to get started](https://docs.fastly.com/en/guides/getting-started#_basics). Then set up a [custom domain](../steps/_index.md). To get the [DNS challenge to succeed](../troubleshoot.md#ownership-verification), -have your CDN point to your [project's target URL](../../domains/steps/_index.md#2-get-the-target-for-your-project). +have your CDN point to your [project's target URL](../../domains/steps/_index.md#1-get-the-target-for-your-project). ## 3. Handle apex domains diff --git a/sites/platform/src/domains/cdn/managed-fastly.md b/sites/platform/src/domains/cdn/managed-fastly.md index 93479397f8..f4e7419329 100644 --- a/sites/platform/src/domains/cdn/managed-fastly.md +++ b/sites/platform/src/domains/cdn/managed-fastly.md @@ -22,7 +22,7 @@ To add a managed Fastly CDN to your project, When you request for a new domain to be added to your Fastly service, {{< vendor/name >}} support provides you with a [`CNAME` record](../../domains/steps/dns.md) for [domain control validation](../troubleshoot.md#ownership-verification). To add this `CNAME` record to your domain settings, -see how to [configure your DNS provider](../steps/_index.md#3-configure-your-dns-provider). +see how to [configure your DNS provider](../steps/_index.md#2-configure-your-dns-provider). ### Transport Layer Security (TLS) certificates diff --git a/sites/platform/src/domains/steps/_index.md b/sites/platform/src/domains/steps/_index.md index ec8c8e5fc2..ce4209bfac 100644 --- a/sites/platform/src/domains/steps/_index.md +++ b/sites/platform/src/domains/steps/_index.md @@ -23,12 +23,16 @@ You need: - A domain with access to its settings with the registrar - A registrar that allows `CNAME` records or [one of the alternatives](./dns.md) on [apex domains](/glossary.md#apex-domain) - Optional: The [CLI](../../administration/cli/_index.md) installed locally -- If you are on a development plan, you need to [upgrade your tier to a production plan](#1-change-your-plan-to-a-production-plan). + +{{< version/only "1" >}} +- If you are on a development plan, you need to [upgrade your tier to a production plan](#optional-change-your-plan-to-a-production-plan). +{{< /version/only >}}hu If you are planning to use several subdomains of the same domain on different projects, see how to [manage multiple subdomains](/domains/steps/subdomains.md) *before* you add your domain to {{< vendor/name >}}. -## 1. Change your plan to a production plan +{{< version/only "1" >}} +## Optional: Change your plan to a production plan If you are on a Development plan, you can't add a domain. You need to upgrade your subscription to a [production plan](/glossary.md#production-plan). @@ -36,8 +40,8 @@ You need to upgrade your subscription to a [production plan](/glossary.md#produc To upgrade your plan tier, you must be an organization owner or have the [manage plans permission](../../administration/users.md#organization-permissions). To upgrade your plan tier: - -{{< codetabs >}} +{{< /version/only >}} +{{< codetabs v2hide="true" >}} +++ title=Using the CLI @@ -62,16 +66,21 @@ title=In the Console 5. Click **Save**. {{< /codetabs >}} - +{{< version/only "1" >}} You can find [more information on plan tiers](https://platform.sh/pricing). +{{< /version/only >}} -## 2. Get the target for your project +## 1. Get the target for your project You want to point your DNS record to the automatically generated URL. Your domain needs to point to that target for your site to go live. +{{< version/only "1" >}} + For Dedicated plans, get the target for your project from your {{< vendor/name >}} contact. +{{< /version/only >}} + {{< codetabs >}} +++ @@ -96,7 +105,7 @@ title=In the Console {{< /codetabs >}} -## 3. Configure your DNS provider +## 2. Configure your DNS provider Your DNS provider (usually your registrar) is where you manage your domain. Most registrars offer similar functionalities regarding DNS configuration but use different terminology or configuration. @@ -117,7 +126,7 @@ To configure your domain name to point to your project: 1. Consult your provider's documentation to find out how to add or edit DNS records. 2. Open your registrar's domain management system. 3. Set the TTL on your domain to the lowest possible value to minimize transition time. -4. Add a `CNAME` record pointing from your domain to the [target](#2-get-the-target-for-your-project). +4. Add a `CNAME` record pointing from your domain to the [target](#1-get-the-target-for-your-project). Not all registrars allow these kinds of records. If yours doesn't, see the [alternatives](./dns.md#workarounds-for-apex-domains). 5. Optional: If you have multiple domains you want to be served by the same app, add a `CNAME` record for each of them. @@ -126,8 +135,8 @@ To configure your domain name to point to your project: If your domain is `example.com` and you are using the `www` subdomain, you have records like the following: -* `example.com` is a `CNAME`/`ANAME`/`ALIAS` record pointing to `main-abcd123.abcdefgh1234567.eu.platformsh.site`. -* `www.example.com` is a `CNAME` record pointing to `main-abcd123.abcdefgh1234567.eu.platformsh.site`. +* `example.com` is a `CNAME`/`ANAME`/`ALIAS` record pointing to `main-abcd123.abcdefgh1234567.eu.{{< vendor/urlraw "hostname" >}}`. +* `www.example.com` is a `CNAME` record pointing to `main-abcd123.abcdefgh1234567.eu.{{< vendor/urlraw "hostname" >}}`. Both `example.com` and `www.example.com` point to the same target. Redirects are handled by the [router you configure](../../define-routes/_index.md). @@ -141,7 +150,7 @@ title=Using a CDN To configure your CDN and your domain name to point to your project: 1. Open your CDN's management system. -2. Point the CDN at your [target](#2-get-the-target-for-your-project). +2. Point the CDN at your [target](#1-get-the-target-for-your-project). 3. Open your registrar’s domain management system. 4. Open your registrar's domain management system and configure your DNS zone settings to point at your CDN. The address or `CNAME` record to use varies by CDN provider. @@ -159,7 +168,7 @@ See how you can further [configure your CDN](../cdn/_index.md). {{< /codetabs >}} -## 4. Set your domain +## 3. Set your domain Add a single domain to your project: diff --git a/sites/platform/src/domains/steps/custom-domains-preview-environments.md b/sites/platform/src/domains/steps/custom-domains-preview-environments.md index bca11bd05c..7730c51ab9 100644 --- a/sites/platform/src/domains/steps/custom-domains-preview-environments.md +++ b/sites/platform/src/domains/steps/custom-domains-preview-environments.md @@ -106,7 +106,7 @@ title=Using the CLI {{% vendor/cli %}} environment:info edge_hostname --environment {{< variable "ENVIRONMENT_NAME" >}} ``` -2. [Configure your DNS provider](../steps/_index.md#3-configure-your-dns-provider). +2. [Configure your DNS provider](../steps/_index.md#2-configure-your-dns-provider). In particular, make sure your DNS record points to the target of your preview environment. {{< note >}} @@ -143,7 +143,7 @@ title=In the Console 6. Click **Okay**. -7. [Configure your DNS provider](../steps/_index.md#3-configure-your-dns-provider).
+7. [Configure your DNS provider](../steps/_index.md#2-configure-your-dns-provider).
In particular, make sure your DNS record points to the target of your preview environment. {{< note >}} @@ -201,7 +201,7 @@ title=In the Console 6. Click **Okay**. -7. [Configure your DNS provider](../steps/_index.md#3-configure-your-dns-provider).
+7. [Configure your DNS provider](../steps/_index.md#2-configure-your-dns-provider).
In particular, make sure your DNS record points to `Dev`'s target. {{< /codetabs >}} diff --git a/sites/platform/src/domains/steps/dns.md b/sites/platform/src/domains/steps/dns.md index e61cd6b3a7..62da2ba558 100644 --- a/sites/platform/src/domains/steps/dns.md +++ b/sites/platform/src/domains/steps/dns.md @@ -28,7 +28,7 @@ or until the router is back from maintenance. To prevent downtime, create `CNAME` records through your DNS provider. `CNAME` records map a domain to another. -Set up your `CNAME` records to point at your project's [target URL](../../domains/steps/_index.md#2-get-the-target-for-your-project). +Set up your `CNAME` records to point at your project's [target URL](../../domains/steps/_index.md#1-get-the-target-for-your-project). The DNS record for this target URL automatically resolves to the IP addresses of the routers in your project's region. When a router's IP address changes, the DNS record is automatically and immediately updated. diff --git a/sites/platform/src/domains/troubleshoot.md b/sites/platform/src/domains/troubleshoot.md index f03dadb20f..65f1119ea3 100644 --- a/sites/platform/src/domains/troubleshoot.md +++ b/sites/platform/src/domains/troubleshoot.md @@ -19,8 +19,8 @@ host www.{{< variable "YOUR_DOMAIN" >}} If your domain is `example.com`, the response should be something like the following: ```text -www.example.com is an alias for main-abcd123.abcdefgh1234567.eu.platformsh.site. -main-abcd123.abcdefgh1234567.eu.platformsh.site has address 192.0.2.1 +www.example.com is an alias for main-abcd123.abcdefgh1234567.eu.{{< vendor/urlraw "hostname" >}} +main-abcd123.abcdefgh1234567.eu.{{< vendor/urlraw "hostname" >}} has address 192.0.2.1 ``` If it isn't, try the following steps: diff --git a/themes/psh-docs/layouts/partials/tiered-features/body.html b/themes/psh-docs/layouts/partials/tiered-features/body.html index a2959a4d6d..8c01e1f7f5 100644 --- a/themes/psh-docs/layouts/partials/tiered-features/body.html +++ b/themes/psh-docs/layouts/partials/tiered-features/body.html @@ -1,34 +1,23 @@ -{{ $tiers := .tiers }} +{{- $tiers := .tiers -}}

Tier availability

-

This feature is available for - - {{ if gt (len $tiers) 1 }} + {{- if gt (len $tiers) 1 -}} - {{ range $index, $tier := sort $tiers }} - {{ if eq $index ( sub ( len $tiers ) 1 ) }} - + {{- range $index, $tier := sort $tiers -}} + {{- if eq $index ( sub ( len $tiers ) 1 ) -}} and {{ $tier }} - - {{ else }} - + {{- else -}} {{ $tier }}{{ if gt (len $tiers) 2 }},{{ end }} - - {{ end }} - {{ end }} + {{- end -}} + {{- end -}} - {{ else }} - + {{- else -}} {{ index $tiers 0 }} - - {{ end }} - - customers. Compare the {{ .Site.Params.vendor.name }} tiers on our pricing page, or contact our sales team for more information.

- - + {{- end -}} +  customers. Compare the {{ .Site.Params.vendor.name }} tiers on our pricing page, or contact our sales team for more information.