Serve wildcard and tenant subdomains
Use a wildcard hostname when your app answers on a subdomain per tenant or per user, and each lane should have its own set of them.
::example{slug="web-wildcard-tenants"}
Give tenant pages a domain of their own
Section titled “Give tenant pages a domain of their own”When tenants write what their pages contain, keep those pages off the app’s cookie site. The domain function gives them a domain that, like the lane’s domain, carries the lane number:
lanes: vars: sites_domain: ${{ domain('myapp-sites') }}lanesWhich worktrees get a lane, how many ports each lane reserves, and values computed per lane (lane.<name>).
lanes.varsValues computed for each lane and read as ${{ lane.<name> }}, such as a database name, vhost, bucket or Redis index per lane. Build names from ${{ lane.name }}, which is main in lane 0 and lane<N> in lane N whatever the branch, and numbers from ${{ lane.index }}. A var named domain replaces the default lane domain, and one named port fixes where the lane's port block starts. ${{ domain('pages') }} gives a name a site of its own in each lane, such as pages2.localhost in lane 2. Cannot be combined with matrix.
lanes.vars.<name>Values computed for each lane and read as ${{ lane.<name> }}, such as a database name, vhost, bucket or Redis index per lane. Build names from ${{ lane.name }}, which is main in lane 0 and lane<N> in lane N whatever the branch, and numbers from ${{ lane.index }}. A var named domain replaces the default lane domain, and one named port fixes where the lane's port block starts. ${{ domain('pages') }} gives a name a site of its own in each lane, such as pages2.localhost in lane 2. Cannot be combined with matrix.
That is myapp-sites.localhost in lane 0 and myapp-sites1.localhost in lane 1. Pick a name no other project uses, ending in a letter.
Route the wildcard to the service
Section titled “Route the wildcard to the service”A hostname that starts with *. matches every name below the rest of it. Quote it, since a leading * means something else in YAML.
services: sites: run_script: file: apps/sites/package.json name: dev hosts: "*.${{ lane.sites_domain }}" env: SITES_DOMAIN: ${{ lane.sites_domain }}servicesLong-running processes of each lane, started together after infrastructure, setup and lane.start tasks. Each service gets its own port as PORT and, with hosts, HTTPS hostnames. A service that exits shows as failed and is not restarted.
services.<name>A long-running process started with the lane, such as a dev server or a worker. Each service gets its own port from the lane's block (PORT, ${{ self.port }}); devlanes stops it with the lane and never restarts it when it exits. A service needs run or run_script, directly or through extends.
services.<name>.run_scriptScript to run from a project file, as { file, name }, such as { file: apps/api/package.json, name: dev }. devlanes picks the tool from the file name (package.json, Makefile, justfile, Taskfile.yml, deno.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle(.kts), settings.gradle(.kts)), runs the script in that file's directory and checks that it exists before starting. For Maven and Gradle, name is the arguments as typed after mvn or gradle, and Maven or Gradle reports a goal or task that does not exist. Presets need it to place their flags, and a profile's run_scripts can swap the script name. Exactly one of run and run_script is required after templates are applied.
services.<name>.run_script.fileFile that defines the script, relative to the project file's directory, such as apps/api/package.json. The script runs in this file's directory. Required unless an override or extends child keeps the inherited file.
services.<name>.run_script.nameScript, target, recipe, task, binary or package name in that file. For go.mod, a bare name such as api means ./cmd/api, and . or a path with / is relative to go.mod. For pom.xml and Gradle files it is the arguments as typed after mvn or gradle, such as -pl web -am spring-boot:run or :web:bootRun; quote an argument that contains spaces, as in a shell. It must name at least one goal or task. Required unless an override or extends child keeps the inherited name.
services.<name>.hostsHostnames the devlanes HTTPS proxy routes to this service, so https://<host> reaches it. One entry or a list; an entry is a hostname or a mapping with host and optional port (a named port), fallback and host_header. A *. wildcard matches subdomains, and an exact host wins over it. The first non-wildcard host becomes public_url, non-wildcard hosts join the lane's DEVLANES_ORIGINS, and having hosts makes the default ready a TCP check. Keep them under ${{ lane.domain }} so lanes do not collide.
services.<name>.envEnvironment variables for this service's process. They override global_env and are overridden by the active profile's env and --env; values may be text, numbers, booleans or ${{ ... }} expressions. Setting PORT replaces the port devlanes allocated; a literal number is the same in every lane, so lanes collide.
services.<name>.env.<name>Environment variables for this service's process. They override global_env and are overridden by the active profile's env and --env; values may be text, numbers, booleans or ${{ ... }} expressions. Setting PORT replaces the port devlanes allocated; a literal number is the same in every lane, so lanes collide.
The service gets the request with its original Host header and reads the tenant from it.
Keep exact hostnames and a fallback beside it
Section titled “Keep exact hostnames and a fallback beside it”An exact hostname wins over any wildcard, so the app and fixed names stay under the lane’s domain. A wildcard marked as a fallback takes every name nothing else claims, which suits a gateway that answers for unknown names.
services: app: run_script: file: apps/app/package.json name: dev hosts: app.${{ lane.domain }} gateway: run_script: file: apps/gateway/package.json name: dev hosts: - host: "*.${{ lane.domain }}" fallback: trueservicesLong-running processes of each lane, started together after infrastructure, setup and lane.start tasks. Each service gets its own port as PORT and, with hosts, HTTPS hostnames. A service that exits shows as failed and is not restarted.
services.<name>A long-running process started with the lane, such as a dev server or a worker. Each service gets its own port from the lane's block (PORT, ${{ self.port }}); devlanes stops it with the lane and never restarts it when it exits. A service needs run or run_script, directly or through extends.
services.<name>.run_scriptScript to run from a project file, as { file, name }, such as { file: apps/api/package.json, name: dev }. devlanes picks the tool from the file name (package.json, Makefile, justfile, Taskfile.yml, deno.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle(.kts), settings.gradle(.kts)), runs the script in that file's directory and checks that it exists before starting. For Maven and Gradle, name is the arguments as typed after mvn or gradle, and Maven or Gradle reports a goal or task that does not exist. Presets need it to place their flags, and a profile's run_scripts can swap the script name. Exactly one of run and run_script is required after templates are applied.
services.<name>.run_script.fileFile that defines the script, relative to the project file's directory, such as apps/api/package.json. The script runs in this file's directory. Required unless an override or extends child keeps the inherited file.
services.<name>.run_script.nameScript, target, recipe, task, binary or package name in that file. For go.mod, a bare name such as api means ./cmd/api, and . or a path with / is relative to go.mod. For pom.xml and Gradle files it is the arguments as typed after mvn or gradle, such as -pl web -am spring-boot:run or :web:bootRun; quote an argument that contains spaces, as in a shell. It must name at least one goal or task. Required unless an override or extends child keeps the inherited name.
services.<name>.hostsHostnames the devlanes HTTPS proxy routes to this service, so https://<host> reaches it. One entry or a list; an entry is a hostname or a mapping with host and optional port (a named port), fallback and host_header. A *. wildcard matches subdomains, and an exact host wins over it. The first non-wildcard host becomes public_url, non-wildcard hosts join the lane's DEVLANES_ORIGINS, and having hosts makes the default ready a TCP check. Keep them under ${{ lane.domain }} so lanes do not collide.
services.<name>.hosts[].hostHostname to route, evaluated for each lane. A leading *. makes a wildcard that matches any depth below it but not the name itself; quote it in YAML. Labels hold letters, digits and inner hyphens; case and a trailing dot are ignored.
services.<name>.hosts[].fallbackMake this route a catch-all: it is used only when no other route, exact or wildcard, matches the requested hostname. Typical for *.${{ lane.domain }} on a gateway that should answer every subdomain other services do not claim. Defaults to false.
Start the lane and list its routes, wildcards and the fallback included:
$ devlanes start$ devlanes url lsservices.<name>.hosts[] lists the fields of a route.
If tenant pages may share the app’s cookies
Section titled “If tenant pages may share the app’s cookies”Put the tenant wildcard under the lane’s domain, "*.${{ lane.domain }}", without a fallback. It then takes every name the exact hostnames leave, ahead of the gateway.
If a program other than a browser opens a tenant hostname
Section titled “If a program other than a browser opens a tenant hostname”A hosts file cannot hold wildcards, so such a program needs the resolver strategy from Fix programs that cannot resolve *.localhost.