How to configure routes?

Andrew Kester

Updated June 28, 2023 08:36

All redirects and rules on how traffic - external requests are directed are handled by defining routes in a .platform/routes.yaml file in your project repository.

You might need to control how people access your web applications, for example when you have multiple apps in one project. Or you might just want to direct requests to specific places, such as removing the www at the start of all requests.

If you have a single route served by a single app, you don’t need to include the file. Your project then includes a default route.

Default route definition

If you don’t include a file defining routes, a single default route is deployed. If you have one app to direct traffic to and its name is app, this is equivalent to the following:

.platform/routes.yaml

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

All traffic to your domain (say, https://example.com) is sent to your app. This also includes redirecting requests from http to https. It affects your default domain.

Basic redirect definition

In a basic situation, you have one app to direct traffic to. Say its name is app. And say you want to redirect requests from https://www.example.com to https://example.com.

Define your routes like this:

.platform/routes.yaml

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

Multi-app route definition

The specifics of configuring the Router container for multiple applications is explored in detail in the Multiple apps documentation.

Trailing slashes

All defined routes have at least a slash in the path. So you might define routes for 2 apps named app and api as follows:

.platform/routes.yaml


"https://{default}":
    type: upstream
    upstream: "app:http"
"https://subdomain.example.com":
    type: upstream
    upstream: "api:http"

Both of these routes would be resolved with trailing slashes. So if you check your PLATFORM_ROUTES variable, you see the following resolved routes (assuming example.com is your default domain):

{
  "https://example.com/": {
    "primary": true,
    "id": null,
    "attributes": {},
    "type": "upstream",
    "upstream": "app",
    "original_url": "https://{default}"
  },
  "https://subdomain.example.com/": {
    "primary": false,
    "id": null,
    "attributes": {},
    "type": "upstream",
    "upstream": "api",
    "original_url": "https://subdomain.example.com"
  }
}

Please visit our public documentation on this matter for more information.