Qovery allows you to define the routes used in your environments.

A route describes how an incoming HTTP request is going to be processed by Qovery. The routes are defined using .qovery.yml file in your application repository.

No network knowledge is required to create your custom routes

Before you begin, this page assumes the following:

• You have installed the Qovery CLI
• You need to deploy more than one application (e.g backend and frontend)

FAQ

Before digging deeper into this guide, I would explain why you should not or why you should use it.

Why you should use it

• You need to expose your application publicly through HTTPS
• You need to have one endpoint (foo.com) targeting multiple backend applications

Why you should not use it

• You only have one application within your environment
• You are not sure why you should use it (ask us)

Concepts

Router

Qovery has the concept of "router" which is where the traffic transit from the World and your application. Each application that needs to be accessible from outside - needs to be attached to at least one router.

An application can be attached to 0 to n routers. It's up to you and depends on your use case.

A router is defined by:

• a name (must be unique through the project)
• 0 to n custom domains
• 1 to n routes

Here is a configuration example of a router:

.qovery.yml

application:
  name: my-app-1
  project: my-project
  cloud_region: aws/us-west-2
  publicly_accessible: true
routers:
- name: main
  custom_domains:
  - branch: master
    domain: my.tld.com
  routes:
  - application_name: my-app-1
    paths:
    - /

Route

A "route" is a concept to connect a "router" to an application. An application can have 0 to n routes.

A route is defined by:

• a path
• an application name

Here is a configuration example of a route:

.qovery.yml

application:
  name: my-app-1
  project: my-project
  cloud_region: aws/us-west-2
  publicly_accessible: true
routers:
- name: main
  custom_domains:
  - branch: master
    domain: my.tld.com
  routes:
  - application_name: my-app-1
    paths:
    - /

Multiple routes

As explained above, each router can have multiple routes targeting different applications. Each application can use the same router by using the same router name within the same project.

Here is an example with two applications, which each of them have their own .qovery.yml file.

Application 1 - .qovery.yml

application:
  name: my-app-1
  project: my-project
  cloud_region: aws/us-west-2
  publicly_accessible: true
routers:
- name: main
  custom_domains:
  - branch: master
    domain: my.tld.com
  routes:
  - application_name: my-app-1
    paths:
    - /

Application 2 - .qovery.yml

application:
  name: my-app-2
  project: my-project
  cloud_region: aws/us-west-2
  publicly_accessible: true
routers:
- name: main
  custom_domains:
  - branch: master
    domain: my.tld.com
  routes:
  - application_name: my-app-2
    paths:
    - /app2/

Behind the scene Qovery will merge the two .qovery.yml into a single one. Which gives a router that will look like this:

Merged router

...
routers:
- name: main
  custom_domains:
  - branch: master
    domain: my.tld.com
  routes:
  - application_name: my-app-1
    paths:
    - /
  - application_name: my-app-2
    paths:
    - /app2/

Meaning, traffic with a route starting with the URL https://my.tld.com/app2 is routed on my-app-2, and the remaining traffic is routed on my-app-1.

Qovery takes care of duplicated routes and deny the latest created one to avoid unintended overrides.

Custom domains

A custom domain can be attached (optional) to a "router" and an environment. Then, multiple application can benefit from the same domain.

Every router on Qovery automatically gets a free qovery.io address which does not change per branch.

Example

Here is a concrete example to show how custom routes could be your best friend in a real-world application.

The e-commerce website

Let's imagine that we have to build an e-commerce website which gives the possibility to order shoes. This website must be able to take orders and provide an invoice for each order. Our system has one web interface, one order service, and one billing service that is for each of them an independent application.

What do we want?

• The web interface must be available through shopping.com and www.shopping.com
• The order service must be available through api.shopping.com/order
• The billing service must be available through api.shopping.com/billing as well
• The traffic coming on api.shopping.com and not covered by the two rules above must be routed on order

This is what the custom routing definition looks like for each of them

Web interface

Here is what the .qovery.yml looks like for the web interface:

.qovery.yml web interface

application:
  name: web-interface
  project: my-ecommerce-project
  cloud_region: aws/us-west-2
  publicly_accessible: true
routers:
- name: frontend
  custom_domains:
  - branch: master
    domain: shopping.com
  - branch: master
    domain: www.shopping.com
  routes:
  - application_name: web-interface
    paths:
    - /

Order service

Here is what the .qovery.yml looks like for the order service:

.qovery.yml order service

application:
  name: order-service
  project: my-ecommerce-project
  cloud_region: aws/us-west-2
  publicly_accessible: true
routers:
- name: backend
  custom_domains:
  - branch: master
    domain: api.shopping.com
  routes:
  - application_name: order-service
    paths:
    - /
    - /order/

Billing service

Here is what the .qovery.yml looks like for the billing service:

.qovery.yml billing service

application:
  name: billing-service
  project: my-ecommerce-project
  cloud_region: aws/us-west-2
  publicly_accessible: true
routers:
- name: backend
  custom_domains:
  - branch: master
    domain: api.shopping.com
  routes:
  - application_name: billing-service
    paths:
    - /billing/

At the end, api.shopping.com, shopping.com and www.shopping.com work as expected. Happy custom routing.