Configure routes

Magento Commerce processes an incoming URL using a route. The routes.yaml file—located at .magento/routes.yaml in your project—defines routes for Integration, Staging, and Production environments.

The deploy script uses values defined in the configuration files in the .magento directory. The script deletes the directory after deployment. Your local workspace is not affected.

The following is the default routes.yaml file:

"http://{default}/":
    type: upstream
    upstream: "mymagento:php"

If you do not create a custom routes.yaml file, the automated deployment uses the default file.

To list the configured routes:

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. A route template looks similar to this: http://www.{default}/ or https://{default}/blog, where {default} is the qualified domain name configured for the project. For example, the routes for example.com domain resolve to the following:

• http://www.example.com/
• https://example.com/blog

Magento Commerce also generates URLs for every active environment, so you can test that system. In a test system, {default} is replaced with the following:

[branch]-[project-id].[region].magentosite.cloud

For example, if the project ID is mswy7hzcuhcjw on a branch called refactorcss hosted in the us cluster, the domains are:

• http://www-refactorcss-mswy7hzcuhcjw.us.magentosite.cloud/
• https://refactorcss-mswy7hzcuhcjw.us.magentosite.cloud/blog

Route options

Configure each route separately using the following properties:

• 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

The following sample routes the naked domain and the www subdomain to the frontendapplication. This route does not redirect HTTPS:

"http://{default}/":
    type: upstream
    upstream: "frontend:http"

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

The following sample route does not redirect from the www to the naked domain; instead, it serves from both:

"http://{default}/":
    type: upstream
    upstream: "frontend:http"

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

In the first sample, the server responds directly to a request of the form http://example.com/hello, but it issues a 301 redirect for http://www.example.com/mypath (to http://example.com/mypath).

Wildcard routes

Magento Commerce (Cloud) 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 the dot (.) to separate the subdomain.

For example, a project with the vmwklxcpbi6zq ID and an add-theme branch routes to http://add-theme-vmwklxcpbi6zq.us.magento.com/.

If you define a http://www.{default}/ route, the route becomes http://www.add-theme-vmwklxcpbi6zq.us.magento.com/.

You can put any subdomain before the dot and the route resolves. In this example, the route is defined as http://*.{default}/, so both of the following URLs work:

• http://foo.add-theme-vmwklxcpbi6zq.us.magentosite.cloud/
• http://bar.add-theme-vmwklxcpbi6zq.us.magentosite.cloud/

If you examine the routes of this sample application, you see:

echo $MAGENTO_CLOUD_RELATIONSHIPS | base64 --decode | json_pp
https://*.add-theme-vmwklxcpbi6zq.us.magentosite.cloud/

See more information about caching.

Redirects

As discussed in more detail in Redirects, you can manage complex redirection rules, such as partial redirects:

http://www.{default}/:
    to: https://{default}/
    type: redirect
http://{default}/:
    to: https://{default}/
    type: redirect
https://{default}/:
    cache:
      cookies: [""]
      default_ttl: 0
      enabled: true
      headers:
      - Accept
      - Accept-Language
    ssi:
      enabled: false
    type: upstream
    upstream: php:http