Proxy routes

โ€‹ Sometimes you want your app to pass requests on to another location, such as a different Platform.sh project. Basic redirects only work within the same project, so use proxy routes for routes elsewhere. โ€‹ You can define an external proxy on your Platform.sh project by defining a route like the following:

.platform/routes.yaml
https://{default}/foo:
    type: proxy
    to: https://www.example.com

This route passes requests for https://{default}/foo/index.html to https://www.example.com/foo/index.html. โ€‹ You can also define a proxy route to an URL composed of an IP address and a port:

.platform/routes.yaml
https://{default}/foo:
    type: proxy
    to: https://192.0.2.0:8000

URL paths 

In the basic example above, the route preserves the URL path, /foo, in the request.

If you want to proxy a route to https://www.example.com without the URL path /foo, add a trailing slash / to the to definition.

.platform/routes.yaml
https://{default}/foo:
    type: proxy
    to: https://www.example.com/

The trailing slash makes the proxy route interpret the location as having a different path. So requests for https://{default}/foo/index.html are forwarded to https://www.example.com/index.html.

To override the URL path entirely, define a route that contains its own path. For example:

.platform/routes.yaml
https://{default}/foo:
    type: proxy
    to: https://www.example.com/bar

This route passes requests for https://{default}/foo/index.html to https://www.example.com/bar/index.html.

Multiple apps with the same base URL 

You can use proxy routes to map a single domain to multiple Platform.sh projects with their own subdomain/domain names. You might have a need to access multiple projects, each hosting specific applications for different languages. You want to serve them all at the same base URL with different paths (https://example.com/en, https://example.com/fr, and so on).

Because domains can’t be reused at Platform.sh, you can’t just set the same domain for all projects. Use proxy routes so a single project can access different projects using the same base URL.

In the following example, a single project specifies proxy routes to three apps with the same default base URL. Each app handles a different language.

.platform/routes.yaml
https://{default}/en:
    type: proxy
    to: https://en.example.com/

https://{default}/jp:
    type: proxy
    to: https://jp.example.com/

https://{default}/pt:
    type: proxy
    to: https://pt.example.com/

The apps behind the proxy need to ensure links to assets are shown to the target domain. For example, by changing https://en.example.com/style.css to https://example.com/en/style.css.

The following diagram shows the example project forwarding specific requests to the correct app.

sequenceDiagram participant User participant Project as Proxy project participant En as En project participant Jp as Jp project participant Pt as Pt project User->>+Project: example.com/en/index.html Project->>+En: en.example.com/index.html Note over En: Changes asset links En-->>-Project: index.html Project-->>-User: index.html User->>+Project: example.com/jp/index.html Project->>+Jp: jp.example.com/index.html Note over Jp: Changes asset links Jp-->>-Project: index.html Project-->>-User: index.html User->>+Project: example.com/pt/index.html Project->>+Pt: pt.example.com/index.html Note over Pt: Changes asset links Pt-->>-Project: index.html Project-->>-User: index.html

Large projects 

This architecture makes the router of a single project into the central element of your app. This setup may make scaling more difficult as the router scales with the size of that project. The router can become a bottleneck for all external sites and acts as a single point of failure. โ€‹ For larger projects, you should handle multiple websites with the same base URL via a CDN.