Share settings and choose which services start
Use this guide when a project has many services that repeat the same settings, and you rarely need all of them running at once.
::example{slug="workflows-profiles-tags"}
Share settings, tag services and group them
Section titled “Share settings, tag services and group them”A template is a named set of service settings that services take over with extends. A tag is a label on a service, and + with its name selects every service that has it. A profile is a named selection of services to start:
templates: server: run_script: name: dev ready: http: path: /healthzservices: accounts-api: extends: server run_script: { file: apps/accounts-api/package.json } hosts: "accounts.${{ lane.domain }}" tags: [api, essential] mailer: extends: server run_script: { file: apps/mailer/package.json } tags: [worker, essential]profiles: default: [+essential] backend: [+api, +worker]templatesNamed service settings that services reuse with extends: <template>. The service inherits every setting of the template and its own settings win: mappings (env, ready, stop, preset options, run_script) merge by key, lists (tags, hosts, sync) and single values replace. Setting run or run_script drops the inherited other one, and one ready probe (tcp, http, log, cmd) drops the inherited probe. Templates may extend other templates, are never started themselves, and are applied after every project file and local override is merged.
templates.<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.
templates.<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.
templates.<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.
templates.<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.
templates.<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.
templates.<name>.ready.http.pathPath requested with GET, such as /healthz; defaults to /.
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>.extendsTemplate under templates whose settings this service inherits; its own settings apply on top. Mappings (env, ready, stop, preset options, run_script) merge by key, lists (tags, hosts, sync) and single values replace. Setting run or run_script drops the inherited other one, and one ready probe (tcp, http, log, cmd) drops the inherited probe. Templates may extend other templates and are resolved after every project file and local override is merged.
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>.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>.tagsLabels for selecting and grouping services. +tag selects every service with the tag in profiles, in commands such as devlanes start +api, and in the TUI filter. Tags also set the service's color: the first tag with a color under the top-level tags wins, then the first tag naming a category such as api, web or worker, so put that tag first.
profilesNamed selections of services for devlanes start --profile <name>. A plain devlanes start brings back what the lane ran before; default is used when there is nothing to bring back, such as after devlanes stop. A profile is a list of names, globs and +tag selectors, or a mapping that can also exclude services, skip infra, add env and remap script names.
profiles.<name>Services started by devlanes start --profile <name> (default when no profile is given): a list of names, globs and +tag selectors, or a mapping that can also exclude services, skip infra, add env and remap script names. Several --profile flags start the union.
Each service keeps the template’s script name and adds its own file; its own settings win, as services.<name>.extends describes. The profile named default is what a plain start runs on a lane’s first start and after you stop the whole lane.
Start with a profile
Section titled “Start with a profile”$ devlanes start --profile backendThe start runs the services the profile selects, and the lane remembers the profile, so a plain start after a reboot brings back the same selection. Stopping the whole lane makes it forget the profile:
$ devlanes stopIf a profile needs its own variables
Section titled “If a profile needs its own variables”A profile written as a mapping can set env. While the profile is active, those variables reach every unit of the lane, which means each service and task, including services the profile does not select. A service’s own env cannot override them:
profiles: test: include: [+essential] env: DATA_FILE: "${{ lane.data_path }}/test/${{ self.name }}.json"profilesNamed selections of services for devlanes start --profile <name>. A plain devlanes start brings back what the lane ran before; default is used when there is nothing to bring back, such as after devlanes stop. A profile is a list of names, globs and +tag selectors, or a mapping that can also exclude services, skip infra, add env and remap script names.
profiles.<name>Services started by devlanes start --profile <name> (default when no profile is given): a list of names, globs and +tag selectors, or a mapping that can also exclude services, skip infra, add env and remap script names. Several --profile flags start the union.
profiles.<name>.includeServices this profile starts: names, globs such as crm-*, and +tag selectors. Globs skip services with autostart: false; names and tags include them.
profiles.<name>.envVariables for the services, tasks and infra.setup and infra.teardown commands of a lane while this profile is active, and for devlanes exec and devlanes with when they read neither self nor replica. They sit above each unit's own env, which cannot override them, so put a variable that some task must not get, such as NODE_ENV: production next to an install task that needs devDependencies, in global_env instead.
profiles.<name>.env.<name>Variables for the services, tasks and infra.setup and infra.teardown commands of a lane while this profile is active, and for devlanes exec and devlanes with when they read neither self nor replica. They sit above each unit's own env, which cannot override them, so put a variable that some task must not get, such as NODE_ENV: production next to an install task that needs devDependencies, in global_env instead.
If a profile should skip the containers
Section titled “If a profile should skip the containers”Set infra: false on the profile. A value that reads a container, such as a database URL, then has a value only while that container already runs, as a shared one another lane started does. Without it, each service the value reaches fails to start, and a value in global_env reaches all of them. So keep such a value with the services that use it:
services: api: env: DATABASE_URL: postgres://postgres:postgres@127.0.0.1:${{ infra.postgres.port }}/${{ lane.db_name }}profiles: frontend: include: [web] infra: falseservicesLong-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.
profilesNamed selections of services for devlanes start --profile <name>. A plain devlanes start brings back what the lane ran before; default is used when there is nothing to bring back, such as after devlanes stop. A profile is a list of names, globs and +tag selectors, or a mapping that can also exclude services, skip infra, add env and remap script names.
profiles.<name>Services started by devlanes start --profile <name> (default when no profile is given): a list of names, globs and +tag selectors, or a mapping that can also exclude services, skip infra, add env and remap script names. Several --profile flags start the union.
profiles.<name>.includeServices this profile starts: names, globs such as crm-*, and +tag selectors. Globs skip services with autostart: false; names and tags include them.
profiles.<name>.infraSet false to skip containers and infra.setup, for example to run only a frontend against another lane's backend. A value that reads infra.* then resolves only while its container already runs, as a shared one another lane started does. Otherwise a service or task whose env reads it fails to start, and so does every service and task of the lane when global_env or a profile's env reads it. With several profiles active, infra is skipped only when all of them set false. Defaults to true.
Point a frontend at another lane’s backend builds on such a profile.