Run dev servers and a production build side by side
Use this guide when you want the built app running next to the dev servers of the same worktree, with its own ports and hostnames.
::example{slug="workflows-dev-and-prod"}
Give each app a start script
Section titled “Give each app a start script”The second project runs each app from its build, so each package.json with a dev script also needs a script that serves the build. The API’s start script runs the server without the watch flag.
{ "scripts": { "dev": "vite", "build": "vite build", "start": "vite preview" }}Write the second project file
Section titled “Write the second project file”Put it next to devlanes.yaml, here the one from Services that find each other. It extends that file, so it has the same services and tasks, and its own project name gives it its own lanes, ports and hostnames.
extends: devlanes.yamlproject: myapp-prod
global_env: NODE_ENV: production
tasks: install: # npm skips devDependencies such as Vite under production, and the build needs them. env: NODE_ENV: development build: run_script: file: web/package.json name: build when: lane.start
profiles: default: # Without include here or in devlanes.yaml, this profile would start no services. include: ["*"] run_scripts: dev: startextendsOther project files this one builds on: one path or a list, relative to this file, such as devlanes.yaml for a devlanes.prod.yaml that runs the same apps another way. They are merged in order, each with its own .local.yaml, then this file and its .local.yaml go last, so later files win. Mappings merge by key and lists and single values replace, as with local overrides. An extended file may be partial and its project is ignored; paths in it mean what they would in this file.
projectProject name, the same in every worktree of the repository. It builds each lane's default domain (<project>.localhost for lane 0, <project><N>.localhost for lane N), names lanes in commands (acme@2), the containers devlanes creates and DEVLANES_LANE_PROJECT, and other projects reach this one as projects.<project>. Lowercase letters, digits, dots, underscores and dashes.
global_envVariables for every service and task of the lane, above devlanes' own variables (PORT, DEVLANES_*) and below each unit's env and the profile's env. Use it for values many units share, such as a database URL built from ${{ infra.postgres.port }}. An entry without a value, such as one that reads a container a profile with infra: false left stopped, fails every service and task of the lane, so a value only some services need belongs in their env. devlanes exec leaves such an entry out and names it. Never set PORT here: it would replace every service's own port.
global_env.<name>Variables for every service and task of the lane, above devlanes' own variables (PORT, DEVLANES_*) and below each unit's env and the profile's env. Use it for values many units share, such as a database URL built from ${{ infra.postgres.port }}. An entry without a value, such as one that reads a container a profile with infra: false left stopped, fails every service and task of the lane, so a value only some services need belongs in their env. devlanes exec leaves such an entry out and names it. Never set PORT here: it would replace every service's own port.
tasksOne-shot commands such as installs, migrations and seeds, run by hand with devlanes run <name> or automatically at a lane event set with when. Tasks of the same event run in declaration order.
tasks.<name>A one-shot command, run by hand with devlanes run <name> or automatically at a lane event set with when. Anything that ends by itself belongs here, not in services, where an exit counts as a failure.
tasks.<name>.run_scriptScript to run from a project file, as { file, name }, such as { file: apps/api/package.json, name: migrate }. It runs with that file's tool (the project's package manager for package.json) in the file's directory, and a missing script fails before anything starts. Prefer it to run for scripts that live in a file. Use exactly one of run, run_script or steps.
tasks.<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.
tasks.<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.
tasks.<name>.whenLane event that runs this task automatically. Without it the task runs only by hand with devlanes run <name> or as a step of another task.
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>.run_scriptsSwap script names for services that use run_script: { dev: start } runs the start script wherever a service's run_script names dev. The file stays the same, and each name is swapped once, not chained. The whole name is matched, so a Maven or Gradle name such as spring-boot:run -Pdev is swapped only by that exact text.
profiles.<name>.run_scripts.<name>Swap script names for services that use run_script: { dev: start } runs the start script wherever a service's run_script names dev. The file stays the same, and each name is swapped once, not chained. The whole name is matched, so a Maven or Gradle name such as spring-boot:run -Pdev is swapped only by that exact text.
The default profile, the services a lane’s first start brings up, runs start wherever a service’s script is dev, and the build runs before the services on every start.
Start it
Section titled “Start it”devlanes finds only devlanes.yaml by itself, so name the second file the first time. After that, -p reaches the project.
$ devlanes --file devlanes.prod.yaml start --no-ui$ devlanes -p myapp-prod statusThe built app answers on https://myapp-prod.localhost, next to the dev server on https://myapp.localhost.
If both projects use one database
Section titled “If both projects use one database”A value built only from the lane’s name is the same in both projects. Put the project’s name in it to keep their data apart:
lanes: vars: db_name: ${{ project.name | replace('-', '_') }}_${{ lane.name }}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.