Run Spring Boot and Quarkus
Use this guide when a Java service runs on Spring Boot or Quarkus and each lane should run its own copy under the lane’s hostname.
Add the preset
Section titled “Add the preset”A preset passes the lane’s port to the framework and binds the app to 127.0.0.1. Name it on the service, next to the Maven goal or Gradle task that starts the app:
Spring Boot
services: api: preset: spring-boot run_script: file: pom.xml name: spring-boot:run hosts: "api.${{ lane.domain }}" ready: http: path: /actuator/health timeout: 180sservicesLong-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>.presetFramework integration that adds the flags and variables a dev server needs to run in a lane, such as --port <port> --strictPort --host 127.0.0.1 for vite or SERVER_PORT for spring-boot, so you do not pass them yourself. One of vite, next, wrangler, tauri, spring-boot or quarkus. Requires run_script (quarkus needs a pom.xml or build.gradle(.kts) one); with a hand-written run, drop the preset and pass its flags yourself. Its options go under a sibling key with the preset's name, for example vite: { args: [--open] }.
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>.readyWhen the service counts as up: once its check passed and it has run half a second. devlanes start waits for it, and after: services tasks run once every started service is ready. Write started (no probe) or a mapping with one of tcp, http, log or cmd, plus timeout (default 60s). Without it, a service with hosts waits for TCP on its port and one without hosts uses started. A service that exits within that half second failed to start. A check that times out marks the service failed, which also skips after: services tasks; the process keeps running and is not restarted.
services.<name>.ready.httpReady once a GET request to path on the unit's main port answers with status, or with a 2xx status when status is unset. Redirects are not followed. Best when the app has a health route that fails while it is broken. Each request sends User-Agent: devlanes-ready, so an app can leave the checks out of its request logs.
services.<name>.ready.http.pathPath requested with GET, such as /healthz; defaults to /.
services.<name>.ready.http.timeoutHow long the HTTP check may take to pass, replacing the check's timeout; defaults to 60s. When it runs out, a service is marked failed but keeps running, and for an infra container the start fails.
The preset also lets Spring trust the proxy’s forwarded headers, so links the app builds use the lane’s https:// hostname, and turns off DevTools LiveReload, whose fixed port would collide between lanes. With Gradle, the file is build.gradle.kts and the name bootRun.
Quarkus
services: api: preset: quarkus run_script: file: build.gradle.kts name: quarkusDev hosts: "api.${{ lane.domain }}" ready: http: path: /q/health/ready timeout: 180sservicesLong-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>.presetFramework integration that adds the flags and variables a dev server needs to run in a lane, such as --port <port> --strictPort --host 127.0.0.1 for vite or SERVER_PORT for spring-boot, so you do not pass them yourself. One of vite, next, wrangler, tauri, spring-boot or quarkus. Requires run_script (quarkus needs a pom.xml or build.gradle(.kts) one); with a hand-written run, drop the preset and pass its flags yourself. Its options go under a sibling key with the preset's name, for example vite: { args: [--open] }.
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>.readyWhen the service counts as up: once its check passed and it has run half a second. devlanes start waits for it, and after: services tasks run once every started service is ready. Write started (no probe) or a mapping with one of tcp, http, log or cmd, plus timeout (default 60s). Without it, a service with hosts waits for TCP on its port and one without hosts uses started. A service that exits within that half second failed to start. A check that times out marks the service failed, which also skips after: services tasks; the process keeps running and is not restarted.
services.<name>.ready.httpReady once a GET request to path on the unit's main port answers with status, or with a 2xx status when status is unset. Redirects are not followed. Best when the app has a health route that fails while it is broken. Each request sends User-Agent: devlanes-ready, so an app can leave the checks out of its request logs.
services.<name>.ready.http.pathPath requested with GET, such as /healthz; defaults to /.
services.<name>.ready.http.timeoutHow long the HTTP check may take to pass, replacing the check's timeout; defaults to 60s. When it runs out, a service is marked failed but keeps running, and for an infra container the start fails.
The preset also moves the dev-mode debugger from port 5005 to a port of each lane, self.ports.debug, which dev mode prints when it starts, and lets continuous testing pick a free port. It needs a pom.xml or Gradle file in run_script. With Maven, the name is quarkus:dev.
Quarkus answers 400 to a request for a hostname it does not know, so the preset allows the service’s first hostname. A service with more hostnames lists them all, with localhost and 127.0.0.1, in QUARKUS_HTTP_HOST_VALIDATION_ALLOWED_HOSTS in its env.
The health paths come from Spring Boot Actuator and the SmallRye Health extension; without them, check a route of your app. The first start downloads dependencies, so the check waits longer than the default. name is what you would type after mvn or gradle, as Run scripts your project already has shows.
Start the lane
Section titled “Start the lane”$ devlanes startThe start runs the project’s Maven or Gradle wrapper and lists the app on the lane’s hostname, such as https://api.myapp.localhost. The app trusts the devlanes CA when it calls another lane hostname.
Run one module of a multi-module build
Section titled “Run one module of a multi-module build”To build the modules an app needs from the root pom, name the app’s module with -pl and add -am. Maven then runs the goal in every module it builds, so the parent pom skips the plugin and the app’s module turns it back on:
<plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> <configuration> <skip>true</skip> </configuration></plugin>Put the same plugin with <skip>false</skip> in web/pom.xml, then point the service at the root pom:
services: web: preset: spring-boot run_script: file: pom.xml name: -pl web -am spring-boot:runservicesLong-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>.presetFramework integration that adds the flags and variables a dev server needs to run in a lane, such as --port <port> --strictPort --host 127.0.0.1 for vite or SERVER_PORT for spring-boot, so you do not pass them yourself. One of vite, next, wrangler, tauri, spring-boot or quarkus. Requires run_script (quarkus needs a pom.xml or build.gradle(.kts) one); with a hand-written run, drop the preset and pass its flags yourself. Its options go under a sibling key with the preset's name, for example vite: { args: [--open] }.
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.
Give -am to one service only. Maven has no build lock, so two services that build the same module at once write over each other’s files.
Let devlanes run the containers
Section titled “Let devlanes run the containers”devlanes runs the project’s containers once for every lane or once per lane, as Give each lane its own container shows. The frameworks’ own container support would get in the way:
- Spring Boot: the preset sets
SPRING_DOCKER_COMPOSE_ENABLED=false, becausespring-boot-docker-composewould start a second copy of the Compose file’s containers for each worktree. When devlanes does not run those containers, turn it back on withspring-boot: { docker_compose: true }on the service. - Quarkus: Dev Services such as Kafka and Keycloak share one container between every app in dev mode, so two lanes would use the same one. Turn them off and point Quarkus at a container under
infra:
infra: compose: docker-compose.yml per_lane: [postgres]
services: api: env: QUARKUS_DEVSERVICES_ENABLED: "false" QUARKUS_DATASOURCE_JDBC_URL: jdbc:postgresql://127.0.0.1:${{ infra.postgres.port }}/myappinfraContainers the lanes depend on (databases, brokers, object stores), started and waited on before setup, tasks and services, plus the commands that create and remove each lane's data in them.
Config referenceinfra.composeCompose file, or a list of files merged like repeated -f, relative to the project. Its services are shared by every lane unless listed in per_lane; the shared project runs from the primary worktree with the .env next to the project file there as --env-file.
infra.per_laneCompose services run once per lane instead of shared, each in its own Compose project with ports from the lane's block and its own named volumes, removed by devlanes lane clean. Needs Compose 2.24.4 or newer.
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>.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.
If Actuator listens on its own port
Section titled “If Actuator listens on its own port”Name a management port on the service, and the preset sets Spring’s management port to it, bound to 127.0.0.1:
services: api: hosts: - "api.${{ lane.domain }}" - host: "actuator.${{ lane.domain }}" port: managementservicesLong-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>.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[].portSend this hostname to one of the unit's named ports instead of its main port. For a service it is a port name as in self.ports.<name>, and naming it here allocates that port; in infra.hosts it is the container port for Compose services, or the port's name for plain containers.
The HTTP ready check asks the main port, so point it at a route of your app.
If you start a jar with run
Section titled “If you start a jar with run”A preset needs run_script. For a command such as java -jar, leave the preset out and set its variables yourself:
services: api: run: java -jar target/api.jar env: SERVER_PORT: ${{ self.port }} SERVER_ADDRESS: 127.0.0.1 SERVER_FORWARD_HEADERS_STRATEGY: framework SPRING_DOCKER_COMPOSE_ENABLED: "false"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>.runCommand that starts the service. A string runs with /bin/sh -c, so pipes, && and multi-line scripts work; a list is an argv run directly without a shell. It starts in the project file's directory unless cwd is set. devlanes runs it exactly as written, so it cannot be combined with preset; prefer run_script when the command is a script in a project file. Exactly one of run and run_script is required after templates are applied. In a list, an item that is one ${{ }} expression giving a number or true/false becomes its text, such as --port followed by ${{ self.port }}.
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.
A Quarkus jar takes QUARKUS_HTTP_PORT, QUARKUS_HTTP_HOST and QUARKUS_HTTP_HOST_VALIDATION_ALLOWED_HOSTS instead.