Run as a service
The one-command installer and the Debian package set up the service for you. This page lists the commands for each, and how to set up the service by hand for a release archive.
Commands
Section titled “Commands”| Installer, Linux | Installer, macOS | Debian package | |
|---|---|---|---|
| Service | systemd user unit prism |
launchd agent com.prism.router |
system unit prism |
| Status | systemctl --user status prism |
launchctl print gui/$(id -u)/com.prism.router |
systemctl status prism |
| Stop | systemctl --user stop prism |
launchctl bootout gui/$(id -u)/com.prism.router |
sudo systemctl stop prism |
| Start | systemctl --user start prism |
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.prism.router.plist |
sudo systemctl start prism |
| Restart after editing the config or keys | systemctl --user restart prism |
launchctl kickstart -k gui/$(id -u)/com.prism.router |
sudo systemctl restart prism |
| Logs | journalctl --user -u prism -f |
~/Library/Logs/prism/prism.out.log, prism.err.log |
journalctl -u prism -f |
| Config | ~/.prism/config.toml |
~/.prism/config.toml |
/etc/prism/config.toml |
| Keys | ~/.config/prism/prism.env |
~/.config/prism/prism.env |
/etc/prism/prism.env |
Prism reads its configuration once at start. A change in config.toml or in
the key file takes effect after a restart. Settings saved in the web console
also apply after a restart; the console can restart Prism itself when
Allow restart and stop from the console is on (Configuration →
Maintenance).
Linux: keep running after logout
Section titled “Linux: keep running after logout”A systemd user unit runs only while you are logged in. On a machine that must serve requests all the time, allow your user services to run without a login session, once:
loginctl enable-linger "$USER"Restart rules
Section titled “Restart rules”Prism uses its exit code to tell the supervisor what to do:
| Exit code | Meaning | Supervisor should |
|---|---|---|
| 75 | restart requested (console restart, installed update) | start Prism again |
| 0 | stop requested (console stop) | leave it stopped |
| 1 | failure (for example an invalid config) | start it again after a delay |
The units the installer and the Debian package install follow these rules:
[Unit]StartLimitIntervalSec=0
[Service]Restart=alwaysRestartSec=5RestartForceExitStatus=75RestartPreventExitStatus=0Restart=always with RestartSec=5 and StartLimitIntervalSec=0 restarts a
crashed Prism every 5 seconds without giving up. StartLimit* keys work only
in the [Unit] section; systemd ignores them in [Service]. Without
RestartPreventExitStatus=0, a stop from the console is undone 5 seconds
later. The launchd agent restarts Prism when it exits with a non-zero code
(KeepAlive.SuccessfulExit = false, at most once every 5 seconds).
An invalid config makes Prism exit with serve failed: … on stderr. Under
systemd that line is in the journal, and the service is restarted every 5
seconds until the config is fixed. Versions → Check configuration in the
console checks the saved config inside the running service. From a terminal:
prism config check ~/.prism/config.tomlA variable the config names but the terminal does not have (the service reads
it from its environment file) is reported as not set in this shell and does
not fail the check; add --strict to make it an error.
Set up the service for a release archive
Section titled “Set up the service for a release archive”Each release archive carries the reference units in support/systemd/prism.service
and support/launchd/com.prism.router.plist.
Linux, system service
Section titled “Linux, system service”sudo useradd --system --home-dir /var/lib/prism --shell /usr/sbin/nologin prismsudo install -d -o prism -g prism /var/lib/prismsudo install -d -m 0755 /etc/prismsudo install -m 0755 prism /usr/local/bin/prismsudo touch /var/lib/prism/config.toml && sudo chown prism:prism /var/lib/prism/config.tomlsudo install -m 0600 /dev/null /etc/prism/prism.env # provider keys, one VAR=value per linesudo cp support/systemd/prism.service /etc/systemd/system/prism.servicesudo systemctl daemon-reloadsudo systemctl enable --now prismThe unit runs /usr/local/bin/prism serve as user prism in
/var/lib/prism, so the config is /var/lib/prism/config.toml and state goes
to /var/lib/prism/data. It reads keys from /etc/prism/prism.env.
A provider whose api_key_env names a variable that is not set (and that has
no key stored in the console) is disabled with one log line:
provider "<name>" disabled: api_key_env <VAR> is not set.
macOS, launchd agent
Section titled “macOS, launchd agent”The agent runs as your user, so keys stored in your login keychain with
prism setup are readable.
mkdir -p ~/.prism ~/Library/Logs/prism ~/.config/prismtouch ~/.prism/config.tomlinstall -m 0600 /dev/null ~/.config/prism/prism.envcp support/launchd/com.prism.router.plist ~/Library/LaunchAgents/sed -i '' "s/YOUR_USER/$(whoami)/g" ~/Library/LaunchAgents/com.prism.router.plistlaunchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.prism.router.plistThe agent loads ~/.config/prism/prism.env, then runs
/usr/local/bin/prism serve in ~/.prism. Install the binary there, or edit
the path in the plist.
Check the service
Section titled “Check the service”curl -fsS http://127.0.0.1:18000/health # {"status":"ok"}/prism/status returns a full status snapshot. When PRISM_ADMIN_TOKEN or
PRISM_READ_TOKEN is set, it needs that token in X-Prism-Admin-Token (or
the read token in X-Prism-Read-Token).