URLs and routing

📍 Where to find this in the UI

• App domains and HttpRoutes: Infra → Architecture tab → URLs
• Actual URLs per env: Infra → Environments → {env} → URLs

How do your users access your app?

Wakastart handles HTTP routing end to end: DNS → load balancer → service.

Domains (App Domain)

App URL = subdomain + (env prefix) + domain

The Wakastart URL pattern inserts the environment slug as a prefix between the subdomain and the root domain — except for prod, which has no prefix.

textCopy
prod  →  sous-domaine "app"  +  domaine "exemple.com"            =  https://app.exemple.com
dev   →  sous-domaine "app"  +  préfixe env "dev"  +  domaine    =  https://app.dev.exemple.com

Exposing an app at the root of a domain (apex)

By default, a URL always requires a subdomain (app, api…). But if you bring a CUSTOM domain (monsupersite.com), you may want to expose your app directly at the root — on monsupersite.com, with no label in front of it. This is called an apex domain.

Reserved for CUSTOM domains. Apex isn't available for a PLATFORM_MANAGED domain (*.wakastart.app), which is shared across the whole platform. Only a domain you bring, whose DNS you delegate to Wakastart, can be exposed at its root.

AppApexUrl (Architecture) → AppApexUrlInstance (per environment)

Like the rest of the architecture, the apex is declared once and then instantiated per environment:

A domain can only carry one apex (uniqueness constraint in the database). An app can, however, have multiple CUSTOM domains, each with its own apex.

DNS: always an A/AAAA record, never a CNAME

A CNAME at the root of a zone is structurally invalid (RFC 1034/1912). For any apex hostname, Wakastart therefore automatically forces an A/AAAA record, regardless of the provider — you have nothing to configure on the DNS side, it's handled at instantiation time.

Mandatory warning at instantiation

Exposing a domain at its root writes a DNS record at the root with no subdomain. However, Wakastart does not check what's currently resolving on that domain: a third-party site already in production there (hosted elsewhere, or an existing manual DNS record) could be made unreachable or run into conflict.

For this reason, the console displays a blocking confirmation modal before creating any apex — you must explicitly confirm that you want to expose the root domain. Verifying the domain's current usage remains your responsibility.

HttpRoute = a URL's internal routing

An HttpRoute is attached to a URL, saying "send everything under /api/* to the backend ServiceInstance, everything under / to the frontend ServiceInstance." This is application-level routing (equivalent to an nginx reverse proxy, but declarative).

textCopy
https://app.dev.exemple.com/api/users
            ↓
   Gateway Wakastart
            ↓
   Match HttpRoute path /api/*
            ↓
   Forward vers ServiceInstance "backend"
            ↓
   Pod backend renvoie 200 OK

Official front URL (Primary Front URL)

An app can have several routes (AppRoute) pointing to several services with the FRONT role (web front, mobile front packaged as a PWA, etc.). By default, nothing distinguishes which one is "the" reference front URL of the app.

On the Architecture → URLs screen, any route targeting a service with role: FRONT can be designated as the app's official front URL:

• Via the star in the routes table, or via the checkbox in the route creation/edit dialog.
• Only one active route can carry this flag per app (enforced in the database by a unique partial index) — checking a new route automatically unchecks the previous one (radio-button behavior, no confirmation needed).
• The flag is only available for a route whose target service has role: FRONT — for any other role (BACK, BFF, WORKER), the action is unavailable.

Important: this flag is purely declarative/display-only. It doesn't drive any K8s/cloud resource and has no influence on the ROUTE_* variables injected into services — it's only used to know "which URL to show a human" for this app.

Checking the URL per environment

The GET /app-routes/primary-front-url-by-environment?appId= endpoint resolves the designated route and computes its FQDN for each of the app's environments:

On the dashboard side, this information is shown via the See URLs button on the Applications list.