Run workers and replicas
A queue consumer, a scheduler or another background process runs as a service like any other, with a few settings because nothing sends it requests.
::example{slug="workflows-queue-workers"}
Configure the worker
Section titled “Configure the worker”services: worker: run: [node, worker.mjs] cwd: worker ready: log: "worker ready" stop: signal: SIGINT timeout: 15s keep_awake: 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>.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>.cwdDirectory run starts in, relative to the project file's directory in the lane's worktree; defaults to that directory. Platform detection also looks here. Cannot be combined with run_script, which runs in the script file's directory; devlanes config check refuses the pair, including a cwd inherited through extends.
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.logReady once a line of the unit's log, as devlanes logs shows it (for a container, its Docker log), matches this regular expression, with colors removed; lines printed before the check began count too. Suits workers without a port: have them print a line once connected.
services.<name>.stopHow devlanes stops the service: signal goes to its whole process tree, and after timeout every process still running is SIGKILLed. The service then shows as stopped and is not restarted. Defaults to SIGTERM and 10s.
services.<name>.stop.signalSignal sent to the service's whole process tree when devlanes stops or restarts it. One of SIGTERM (default), SIGINT, SIGHUP, SIGQUIT, SIGUSR1, SIGUSR2 or SIGKILL; use SIGINT for programs that only shut down cleanly on Ctrl-C.
services.<name>.stop.timeoutHow long to wait after signal before devlanes SIGKILLs every process of the service that is still running. The service then shows as stopped; devlanes never restarts it. Defaults to 10s; raise it for programs that need time to flush or close connections.
services.<name>.keep_awakeWhile this service runs, devlanes never throttles or freezes its lane, whatever lanes.throttle_after and lanes.freeze_after in the user config say. Set it on workers, queue consumers, schedulers and tunnels that do work without inbound requests, which a frozen lane would otherwise stall. One such service keeps the whole lane awake. An expression is evaluated for each lane, such as ${{ lane.index == 0 }} to keep only the main lane awake. Defaults to false.
Have the worker print one line once it is connected, and the ready check waits for that line. The stop settings give it the signal it finishes its current job on, and time to do so. Keeping the lane awake stops devlanes from freezing a lane that gets no requests while the worker runs; Throttling and freezing explains freezing.
Run several copies
Section titled “Run several copies”services: worker: replicas: 2 env: WORKER_ID: ${{ replica.index }} ready: log: worker ${{ replica.index }} readyservicesLong-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>.replicasNumber of copies of this service to run, each with its own port, for example several queue workers. They run as <name>.1 to <name>.N, ${{ replica.index }} counts from 1, and services.<name> in expressions means the first copy; use ${{ replica.index }} in hosts to give each copy its own hostname. A plain number of at least 1, the same in every lane, because each copy reserves ports in every lane's block; ${{ ... }} expressions are not allowed. Defaults to 1.
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.
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.logReady once a line of the unit's log, as devlanes logs shows it (for a container, its Docker log), matches this regular expression, with colors removed; lines printed before the check began count too. Suits workers without a port: have them print a line once connected.
The copies run as worker.1 and worker.2, each with its own port, and the replica index tells each one which it is. The service’s name stands for all its copies, so this stops both:
$ devlanes stop workerName one copy, such as worker.2, to act on it alone.
If the job ends by itself
Section titled “If the job ends by itself”A command that exits when its work is done, such as a cleanup, is a task; as a service it would show as failed. Run installs, migrations and seeds covers tasks.