Skip to main content
A route defines how requests are handled after they reach Upsun. It tells the Upsun platform how to handle incoming web requests and to which application (or destination) to direct the requests. You define routes in a router, which is the .routes key in your project’s .upsun/config.yaml file in your Git repository. Routes define how your web applications are accessed, which is helpful when you have multiple apps in one project or you want to redirect requests to specific destinations, such as example.com rather than www.example.com. If you have a single route served by a single app, you do not need to configure routes: your project includes a default route. Before adding routes to your Upsun project, you must configure your DNS records so that each route’s hostname resolves to the project’s assigned target (for example, via CNAME or appropriate DNS records). If DNS doesn’t point to your project, certificate renewal will fail.

​
Examples

These examples show how to define routes.

​
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 myapp, this is equivalent to the following:
.upsun/config.yaml
routes:
  "https://{default}/":
    type: upstream
    upstream: myapp: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 myapp. And say you want to redirect requests from https://www.example.com to https://example.com. Define your routes like this:
.upsun/config.yaml
routes:
  "https://{default}/":
    type: upstream
    upstream: "myapp:http"

  "https://www.{default}/":
    type: redirect
    to: "https://{default}/"
This affects your default domain. You have one route that serves content (the one with the upstream) and one that redirects to the first (the one with the redirect). Redirects from http to https are generally included by default and don’t need to be listed.

​
Multi-app route definition

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

​
Sticky routing

Sticky routing ensures that all requests from a specific client are consistently routed to the same instance of your application. This can be critical for stateful applications that rely on local session data, preventing user context from being lost in a horizontally scaled environment. You can enable it in your route configuration to have the router attempt to send repeated requests from the same client to the same instance. At Upsun, sticky routing is implemented using a hash of the client’s IP address. This ensures requests from the same IP are generally routed to the same container.
.upsun/config.yaml
routes:
  "https://{default}/":
    type: upstream
    upstream: app:http
    sticky: true
This enables sticky routing at the router level.

Note

Because the routing uses IP hashing, scaling your environment up or down can change the hash distribution, causing requests to be routed to different containers. For production workloads that require persistent sessions, use an external session store (for example, Redis), or design your app to be stateless.

​
Trailing slashes

All defined routes have at least a slash in the path. So you might define routes for 2 apps named myapp and api as follows:
.upsun/config.yaml
routes:
  "https://{default}":
    type: upstream
    upstream: "myapp: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": "myapp",
    "original_url": "https://{default}"
  },
  "https://subdomain.example.com/": {
    "primary": false,
    "id": null,
    "attributes": {},
    "type": "upstream",
    "upstream": "api",
    "original_url": "https://subdomain.example.com"
  }
}

​
Route placeholders

Each route in your configuration file is defined in one of two ways:
  • An absolute URL such as https://example.com/blog
  • A URL with a placeholder such as https://{default}/blog
The available placeholders are {default} and {all}. They stand in for the custom domains you’ve defined in your project. These domains can be top-level domains (example.com) or subdomains (app.example.com).

​
{default}

{default} represents your default custom domain. If you have set your default domain to example.com, example.com and {default} in your .upsun/config.yaml file have the same result for your Production environment. You can use the {default} placeholder:
.upsun/config.yaml
routes:
  "https://{default}/blog":
    type: upstream
    upstream: "myapp:http"
And you can use an absolute URL:
.upsun/config.yaml
routes:
  "https://example.com/blog":
    type: upstream
    upstream: "myapp:http"
In both cases, the URLs for your Production environment are the same.

​
URLs in preview environments

URLs in preview environments (development and staging types) follow a different pattern. No matter how you have set your default domain (even if you don’t have one), using either the absolute URL or the {default} placeholder results in the same URL. In any case, you get the same URL for an environment named feature: 
https://feature-t6dnbai-abcdef1234567.us-2.platformsh.site/blog
Note that the example.com prefix isn’t part of the generated URL.

​
{all}

You can also set up multiple domains for a single project. To define rules for all of them, use {all} in your template. Say you have both example.com and example.net as domains in a project. You can then define the following routes:
.upsun/config.yaml
routes:
  "https://{all}/":
    type: upstream
    upstream: "myapp:http"

  "https://www.{all}/":
    type: redirect
    to: "https://{all}/"
The first route means you’re serving the same content at multiple domains: your app runs at both https://example.com and https://example.net. The second route means that https://www.example.com redirects to https://example.com and https://www.example.net redirects to https://example.net. If your project has no domains or only one, {all} behaves exactly like {default}. If you have two routes sharing the same HTTP scheme, domain, and path and the first route is using {default} and the second is using {all}, the route using {default} takes precedence. Say you have two apps named app1 and app2 and define two routes like this:
.upsun/config.yaml
routes:
  "https://{default}/":
    type: upstream
    upstream: "app1:http"

  "https://{all}/":
    type: upstream
    upstream: "app2:http"
Requests to your default domain are served by app1.

​
Wildcard routes

Upsun supports wildcard routes, so you can map multiple subdomains to the same application. Both redirect and upstream routes support wildcard routes. Prefix a route with an asterisk (*), for example *.{default}. If you have configured example.com as your default domain, HTTP requests to www.example.com, blog.example.com, and us.example.com are all routed to the same endpoint. It also works on preview environments. If you have a branch named feature, it’s {default} domain looks something like: feature-def123-vmwklxcpbi6zq.us.upsun.com (depending on the project’s region). So requests to blog.feature-def123-vmwklxcpbi6zq.us.upsun.com and us.feature-def123-vmwklxcpbi6zq.eu.upsun.com are both routed to the same endpoint. Let’s Encrypt wildcard certificates aren’t supported (they would need DNS validation). So if you want to use a wildcard route and protect it with HTTPS, you need to provide a custom TLS certificate.

​
Route identifiers

When your project has deployed and routes are generated, all placeholders ({default} and {all}) are replaced with appropriate domain names and any additional routes (such as redirecting HTTP to HTTPS) are created. This means the final generated routes differ by environment and so shouldn’t be hard coded in your app. These routes are available in the PLATFORM_ROUTES environment variable as a base64-encoded JSON object. They are also available within an application container from the /run/config.json file so you can maintain a high number of routes more easily. To locate routes in a standardized fashion in any environment, you may specify an id for on each route. This identifier is the same across all environments. Say you have two apps, app1 and app2, that you want to serve at two subdomains, site1 and site2. You can define your routes like this:
.upsun/config.yaml
routes:
  "https://site1.{default}/":
    type: upstream
    upstream: 'app1:http'

  "https://site2.{default}/":
    type: upstream
    id: 'the-second'
    upstream: 'app2:http'
To see the generated routes on your environment named feature, run: 
upsun ssh --environment feature 'echo $PLATFORM_ROUTES | base64 --decode | jq .'
The result is something like this: 
{
  "https://site1.feature-t6dnbai-abcdef1234567.us-2.platformsh.site/": {
    "primary": true,
    "id": null,
    "attributes": {},
    "type": "upstream",
    "upstream": "app1",
    "original_url": "https://site1.{default}/"
  },
  "https://site2.feature-t6dnbai-abcdef1234567.us-2.platformsh.site/": {
    "primary": null,
    "id": "the-second",
    "attributes": {},
    "type": "upstream",
    "upstream": "app2",
    "original_url": "https://site2.{default}/"
  },
  "http://site1.feature-t6dnbai-abcdef1234567.us-2.platformsh.site/": {
    "to": "https://site1.feature-t6dnbai-abcdef1234567.us-2.platformsh.site/",
    "original_url": "http://site1.{default}/",
    "type": "redirect",
    "primary": null,
    "id": null,
    "attributes": {}
  },
  "http://site2.feature-t6dnbai-abcdef1234567.us-2.platformsh.site/": {
    "to": "https://site2.feature-t6dnbai-abcdef1234567.us-2.platformsh.site/",
    "original_url": "http://site2.{default}/",
    "type": "redirect",
    "primary": null,
    "id": null,
    "attributes": {},
  }
}
The site2 HTTPS route has an id specified as the-second, while the other routes have null for their id. You can use this id to look up the domain of the route in every environment.

​
Route attributes

You might want to add extra information to routes to identify them in your app. Route attributes are arbitrary key-value pairs attached to a route. This metadata has no impact on Upsun, but is available in the PLATFORM_ROUTES environment variable. So you can define a route like this:
.upsun/config.yaml
routes:
  "http://{default}/":
    type: upstream
    upstream: "myapp:http"
    attributes:
        "foo": "bar"
The attributes appear in the routes data like so: 
"https://feature-t6dnbai-abcdef1234567.us-2.platformsh.site/": {
  "primary": true,
  "id": null,
  "attributes": {
    "foo": "bar"
  },
  "type": "upstream",
  "upstream": "myapp",
  "original_url": "https://{default}/"
}

​
Route limits

The maximum size of the routes document is 128 KB, which should fit around 300 different routes. If your .upsun/config.yaml file would result in too large of a route information value, it’s rejected. The full list of generated route information is often much larger than what’s specified in the .upsun/config.yaml file. For example, by default all HTTPS routes (and all uses of {all}) are duplicated to create HTTP redirect routes. As a general rule, you should keep to your defined routes under 100. If your .upsun/config.yaml file is rejected for being too big, do one of the following: Let’s Encrypt allows a maximum of 100 hostnames per certificate. You can have 1 Let’s Encrypt certificate for each of your environments. If you define both a {default} and a www.{default} route for each domain you use, you can add up to 50 hostnames. Going over this limitation results in a warning on deploy and no new TLS certificates are issued. Non-default ports (other than 80 and 443) aren’t supported and can’t be included in routes configuration.

​
Route configuration reference

You can configure each route separately with the following properties:
NameTypeRequiredDescription
typestringYesOne of the following options:
  • upstream means content is served at that route by an app and requires the upstream property to be set.
  • redirect means the route is redirected elsewhere in your project and requires the to property.
  • proxy means requests are redirected outside your project and requires the to property. See more about proxy routes.
upstreamstringIf type is upstreamThe name of the app to be served (as defined in your app configuration) followed by :http. Example: app:http
stickybooleanNoEnables sticky routing for the route. When true, the router attempts to send repeat requests from the same client to the same upstream container, based on a hash of the client’s IP address.
tostringIf type is redirectThe absolute URL or other route to which the given route should be redirected with an HTTP 301 status code.
ssibooleanNoWhether server side includes are enabled.
redirectsObjectNoDefines redirects for partial routes. For definition and options, see the redirect rules.
cacheObjectNoDefines caching policies for the given route. Enabled by default. For details and options, see route caching.
idstringNoA unique identifier for the route. See route identifiers.
primarybooleanNoWhether the route is the primary route for the project. Can only be true for one route in the configuration file, but if you use the {all} placeholder, it can be true for multiple final routes. Defaults to the first defined upstream route.
tlsObjectNoTLS configuration. See HTTPS.
attributesObjectNoAny key-value pairs you want to make available to your app. See route attributes.

​
CLI access

The Upsun CLI can show you the routes you have configured for an environment. These are the routes as defined in the .upsun/config.yaml file with the placeholders plus the default redirect from HTTP to HTTPS. They aren’t the final generated routes. Run the following command: 
upsun environment:routes
You get output similar to: 
Routes on the project Example (abcdef123456), environment main (type: production):
+---------------------------+----------+---------------------------+
| Route                     | Type     | To                        |
+---------------------------+----------+---------------------------+
| https://www.{default}/    | upstream | myapp:http                  |
| https://www.{default}/api | upstream | api:http                  |
| http://www.{default}/     | redirect | https://www.{default}/    |
| http://www.{default}/api  | redirect | https://www.{default}/api |
+-----------------------+----------+-------------------------------+

To view a single route, run: upsun route:get <route>
Viewing a single route gives you more detailed info, such as its cache and SSI settings.

​
WebSocket routes

To use the WebSocket protocol on a route, cache must be disabled because WebSocket is incompatible with buffering, which is a requirement for the router caching.
  1. Define a route that serves WebSocket:
.upsun/config.yaml
routes:
  "https://{default}/ws":
    type: upstream
    upstream: "myapp:http"
    cache:
      enabled: false

  # Below HTTP config may not be necessary for every Websocket client.
  "https://{default}/ws":
    type: upstream
    upstream: "myapp:http"
    cache:
      enabled: false
  1. Disable request buffering in your app configuration.
.upsun/config.yaml
applications:
  myapp:
    web:
      commands:
        start: /app/.linuxbrew/bin/websocketd --port=$PORT ./wsmanager.sh
      upstream:
        socket_family: tcp
        protocol: http
      locations:
        '/':
          passthru: true
          request_buffering:
              enabled: false

​
.htaccess files

Upsun uses Nginx servers, not Apache ones. You can’t use .htaccess files with Nginx, they are therefore ignored on Upsun. You can accomplish the same redirect and rewrite goals with your routes and web server locations.
Last modified on March 11, 2026