Configure routes

The routes.yaml file in the .magento/routes.yaml directory defines routes for your Cloud for Adobe Commerce Integration, Staging, and Production environments. Routes determine how Magento processes incoming HTTP and HTTPS requests.

On Pro projects, we recommend updating YAML configuration files in an Integration environment and testing the changes before pushing the updates to Staging and Production environments. If you discover that configuration changes are not applied to Staging and Production sites after you redeploy and do not see any related error messages in the log, submit a Support ticket that describes the attempted configuration changes. Include any updated YAML configuration files in the ticket.

The default routes.yaml file specifies the route templates for processing HTTP requests as HTTPS on projects that have a single default domain and on projects configured for multiple domains:

1
2
3
4
5
6
"http://{default}/":
    type: upstream
    upstream: "mymagento:http"
"http://{all}/":
    type: upstream
    upstream: "mymagento:http"

Use the magento-cloud CLI to view a list of the configured routes:

1
2
3
4
5
6
7
magento-cloud environment:routes

+-------------------+----------+---------------+
| Route             | Type     | To            |
+-------------------+----------+---------------+
| http://{default}/ | upstream | mymagento:php |
+-------------------+----------+---------------+

Route templates

The routes.yaml file is a list of templated routes and their configurations. You can use the following placeholders in route templates:

  • The {default} placeholder represents the qualified domain name configured as the default for the project.

    For example, a project with the default domain example.com and the following route templates:

    1
    2
    
    https://www.{default}/
    https://{default}/blog
    

    These templates resolve to the following URLs in a production environment:

    1
    2
    
    https://www.example.com/
    https://example.com/blog
    
  • The {all} placeholder represents all the domain names configured for the project.

    For example, a project with example.com and example1.com domains with the following route templates:

    1
    2
    3
    
     https://www.{all}/
    
     https://{all}/blog
    

    These templates resolve to the following routes for all domains in the project:

    1
    2
    3
    4
    5
    6
    7
    
     https://www.example.com/
    
     https://www.example1.com/
    
     https://example.com/blog
    
     https://example1.com/blog
    

    The {all} placeholder is useful for projects configured for multiple domains. In a non-production branch, {all} is replaced with the project ID and environment ID for each domain.

    If a project does not have any domains configured, which is common during development, the {all} placeholder behaves in the same way as the {default} placeholder.

Adobe Commerce also generates routes for every active Integration environment. For Integration environments, the {default} placeholder is replaced with the following domain name:

1
[branch]-[per-environment-random-string]-[project-id].[region].magentosite.cloud

For example, the refactorcss branch for the mswy7hzcuhcjw project hosted in the us cluster has the following the domain:

1
https://refactorcss-oy3m2pq-mswy7hzcuhcjw.us.magentosite.cloud/

If your Cloud project supports multiple stores, follow the route configuration instructions for multiple websites or stores.

Route protocols

All environments support both HTTP and HTTPS automatically.

  • If the configuration specifies only the HTTP route, HTTPS routes are created automatically, allowing the site to be served from both HTTP and HTTPS without requiring redirects.

    For example, a project with the default domain example.com and the following route template:

    1
    
    http://{default}/
    

    This template resolves to the following URLs:

    1
    2
    3
    
    http://example.com/
    
    https://example.com/
    
  • If the configuration specifies only the HTTPS route, then all HTTP requests redirect to HTTPS.

    For example, a project with the default domain example.com with the following route template:

    1
    
    https://{default}/
    

    This template resolves to the following URL:

    1
    
    https://example.com/
    

    It also processes the following redirect:

    http://example.com/ ==> https://example.com/

We recommend serving all pages over TLS. For this configuration, you must configure redirects for all unencrypted request to the TLS equivalent using one of the following methods:

  • Change the protocol to HTTPS in the routes.yaml file.

    1
    2
    3
    4
    5
    6
    
    "https://{default}/":
        type: upstream
        upstream: "mymagento:http"
    "https://{all}/":
        type: upstream
        upstream: "mymagento:http"
    
  • For Staging and Production environments, we recommend enabling the Force TLS on Fastly option from the Magento Admin UI. When you use this option, Fastly handles the redirection to HTTPS, so you do not have to update the routes.yaml configuration.

Route options

Configure each route separately using the following properties:

Property Description
type: upstream Serves an application. Also, it has an upstream property that specifies the name of the application (as defined in .magento.app.yaml) followed by the :http endpoint.
type: redirect Redirects to another route. It is followed by the to property, which is an HTTP redirection to another route identified by its template.
cache: Controls caching for the route.
redirects: Controls redirect rules.
ssi: Controls enabling of Server Side Includes.

Simple routes

In the following examples, the route configuration routes the apex domain and the www subdomain to the mymagento application. This route does not redirect HTTPS requests.

Example 1:

1
2
3
4
5
6
7
"http://{default}/":
    type: upstream
    upstream: "mymagento:http"

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

In this example, the request routing follows these rules:

  • The server responds directly to requests with the following URL pattern:

    1
    
    http://example.com/path
    
  • The server issues a 301 redirect for requests with the following URL pattern:

    1
    
    http://www.example.com/mypath
    

    These requests redirect to the apex domain, for example:

    1
    
    http://example.com/mypath
    

In the following example, the route configuration does not redirect URLs from the www domain to the apex domain. Instead, requests are served from both the www and apex domain.

Example 2:

1
2
3
4
5
6
7
"http://{default}/":
    type: upstream
    upstream: "mymagento:http"

"http://www.{default}/":
    type: upstream
    upstream: "mymagento:http"

Wildcard routes

Cloud for Adobe Commerce supports wildcard routes, so you can map multiple subdomains to the same application. This works for redirect and upstream routes. You prefix the route with an asterisk (*). For example, the following routes to the same application:

  • *.example.com
  • www.example.com
  • blog.example.com
  • us.example.com

This functions as a catch-all domain in a live environment.

Routing a non-mapped domain

You can route to a system that is not mapped to a domain using a dot (.) to separate the subdomain.

Example:

A project with an add-theme branch routes to the following URL:

1
http://add-theme-projectID.us.magento.com/

If you define the following route template:

1
 http://www.{default}/

The route resolves to the following URL:

1
http://www.add-theme-projectID.us.magento.com/

You can insert any subdomain before the dot and the route resolves.

Example:

Define the following route template:

1
http://*.{default}/

This template resolves both of the following URLs:

1
2
http://foo.add-theme-projectID.us.magentosite.cloud/
http://bar.add-theme-projectID.us.magentosite.cloud/

You can view the route pattern for non-mapped domains by establishing an SSH connection to the environment, and using the Magento Cloud CLI to list the routes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
web@mymagento.0:~$ vendor/bin/ece-tools env:config:show routes

Magento Cloud Routes:
+------------------------------------------+--------------------------------------------------------------+
| Route configuration                      | Value                                                        |
+------------------------------------------+--------------------------------------------------------------+
| http://www.add-theme-projectID.us.magento.com/:                                                         |
+------------------------------------------+--------------------------------------------------------------+
| primary                                  | false                                                        |
| id                                       | null                                                         |
| attributes                               |                                                              |
| type                                     | upstream                                                     |
| to                                       | mymagento                                                    |
| original_url                             | https:/{default}/                                            |
+------------------------------------------+--------------------------------------------------------------+
| https://*.add-theme-projectID.us.magentosite.cloud/:                                                    |
+------------------------------------------+--------------------------------------------------------------+
| primary                                  | false                                                        |
| id                                       | null                                                         |
| attributes                               |                                                              |
| type                                     | upstream                                                     |
| to                                       | mymagento                                                    |
| original_url                             | https://*.{default}/                                         |
+------------------------------------------+--------------------------------------------------------------+

Redirects and caching

As discussed in more detail in Redirects, you can manage complex redirection rules, such as partial redirects, and specify rules for route-based caching:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
https://www.{default}/:
    type: redirect
    to: https://{default}/
https://{default}/:
    cache:
        cookies: [""]
        default_ttl: 0
        enabled: true
        headers:
            - Accept
            - Accept-Language
    ssi:
        enabled: false
    type: upstream
    upstream: mymagento:http