Run Lore commands through the background service¶
In this tutorial you'll turn on the Lore background service, watch a command be carried out by it instead of by the process you ran, and turn it off again. When you're finished the service will be serving every Lore command you run, and you'll know how to override that for a single command.
The service and both settings are per user: the config is your user-level config.toml, and the socket lives in a directory private to your user. Another user on the same machine has their own, unaffected by anything here.
Prerequisites¶
- A
loreexecutable, version 0.10.0 or later. See install the Lore CLI. - A Lore repository you can run a read-only command in, such as the one from the quickstart.
- Linux, macOS, or Windows. The service talks to its clients over a local socket, which Lore needs one of on the platform.
Step 1 — Name the build that serves your commands¶
Lore never guesses which executable to start as the service, so you name it once. Use the absolute path of the lore you want serving your commands.
Step 2 — Turn the service on¶
Both settings are needed. With the setting on and no executable named, Lore tells you so and keeps running commands in the process you ran.
Step 3 — Run a command¶
Nothing is listening yet, so this starts a service and runs there. Use any repository path you have.
The command behaves exactly as it did before. What changed is where it ran: the service that started here outlives the command and serves the next one too.
Step 4 — Stop the service, and start one without running a command¶
lore service start asks for a service to be running and reports the one that is, whether or not it had to start it. lore service stop returns only once the socket is free, so nothing has to wait afterwards.
Step 5 — See what the service is doing¶
lore service status reports on the service without changing it. It names the build that is serving the machine, how long that service has been up, how many clients are connected to it, and how many SWFS mounts it holds. With nothing running it says so and still succeeds, so a script can branch on the output rather than on a connection failing.
Lore service is running
Executable: /usr/local/bin/lore
Uptime: 1h 4m 12s
Connections: 1
SWFS mounts: 0
The command counts its own connection, so a service nothing else is talking to reports one.
Trouble the service ran into while no command was running is buffered and printed under the status that reports it: failures while it was initializing, failures in the loop that accepts connections, and errors raised by SWFS callbacks. A service that has hit none of those reports none, so a status with no messages under it is the healthy reading rather than a missing one.
The buffer holds the most recent messages and is emptied as it is read, so each call shows what has arrived since the last one, and a call that finds messages were dropped says how many. These messages are the answer to the command that asked for them rather than diagnostics about it, so they are printed whatever --log-level is set to.
Step 6 — Override the setting for one command¶
LORE_USE_SERVICE decides one command without changing the stored setting. It reads 0, false, no and off as off.
PowerShell has no per-command environment prefix, so set the variable in a child process. Setting it in your own session would overwrite an override you had already set there, and clearing it afterwards would not put that back.
Note
lore service run is the service rather than a client of one, so it always does the work itself whatever these settings say. Use it to run a service in the foreground and watch its output; Ctrl+C stops it cleanly and releases its socket, as lore service stop does.
Verify¶
Stopping twice is what shows the first stop found a service and the second had none to find:
Both settings are stored in the user-level config.toml, so they hold for later commands:
Troubleshooting¶
Commands still run in the process that ran them¶
Lore prints a warning naming what is missing:
Relaying needs the setting and an executable. Run lore service set-executable <path> to complete the pair. Clearing the executable with lore service set-executable "" is the other way back to a pair that does not relay.
Lore service unavailable, exit code 32¶
[Error] Failed to send command to Lore service because: Lore service unavailable:
starting /opt/lore/bin/lore failed: No such file or directory (os error 2)
The command never ran, because no service could be reached and none could be started from the executable that is named. Check that the path in [service] executable still exists — this is what you see after a build directory is cleaned or a version is uninstalled. Exit code 32 means the service was unreachable, distinct from the command itself having run and failed, so a script can retry it after starting a service.
A command reached a service, but not the one you expected¶
A build directory that is still on the machine keeps serving commands after you have moved on to another one, because the executable is resolved from the stored setting rather than from the client you ran. lore service status names the build that is actually serving the socket, so compare its Executable against the client you meant to use and re-run lore service set-executable <path> followed by lore service stop if they differ. The next command starts a service from the newly named build.
A test run or a second checkout keeps stopping your service¶
Every service belonging to a user answers on the same socket by default, which is what makes one service serve every command you run. Set LORE_SERVICE_SOCKET to give a group of processes a service of their own:
The value names a single file, not a path. Lore refuses anything containing a path separator and uses the default instead.
Next steps¶
[service]table in the CLI configuration reference — both fields, the order the executable is resolved in, and the environment variables that override them.lore servicein the CLI command reference — every subcommand and its flags.