A terminal UI for the systemd services you care about: your own apps plus anything else you pick. It saves their logs to files and can restart them when you deploy a new binary. Navigation uses Emacs keys.
make install # installs ~/.local/bin/serviceman and ~/.config/serviceman/config.json
serviceman daemon install # starts the ServiceMan daemon (logging + watching)
serviceman # opens the TUI
- If a config already exists,
make installasks whether to keep it (default), update it with new settings, or replace it (a backup is saved first). make uninstallremoves ServiceMan; see Uninstalling.
- Shows only the services you track, with their state, boot setting and health.
- Creates and edits user units through a form, with an optional preview of the unit file.
- Follows a service's journal live and saves its logs to files.
- Watching: restarts a service when its binary is replaced, so a deploy is just
make installorgo build -o ~/.local/bin/app. - Polls a health-check URL per service.
| Want to… | How |
|---|---|
| Track existing services | t, or serviceman track nginx myapp |
Run a binary from ~/.local/bin |
c, pick the binary, C-c C-c to install |
| Run any other command as a service | c, then Custom command or path |
| Edit a service | e, then C-c C-c to save |
| Watch logs live | RET |
| Restart it on every deploy | w (watching on) |
| Check that a web service is up | M-x Set URL; the HEALTH column shows it |
| Give a service its secrets | M-x Set env file |
| Open the app's own config | M-x Edit app config |
ServiceMan creates and edits only user units (no sudo). System units can be tracked, started, stopped and restarted, but not edited; ServiceMan asks for your sudo password when it needs it.
| Key | Does |
|---|---|
C-n / C-p |
Next / previous |
C-s |
Filter |
C-g |
Cancel |
t |
Track existing services |
c |
Create a service |
e |
Edit the service |
s |
Start / stop |
r |
Restart |
RET |
Follow the journal |
w |
Watching on / off |
D |
ServiceMan daemon on / off |
C-c C-c |
Save (in the New / Edit Service form) |
q |
Quit |
Every other command is in M-x: type to find it by name. ? lists all keys.
ESC works as Meta (ESC x = M-x).
- A user service,
serviceman-daemon.service, that does the logging and watching. - Turn it on with
serviceman daemon installorDin the TUI. - Logs go to
~/.local/share/serviceman/logs/<unit>.logand are rotated by size. - With watching on, it restarts the service when its binary is replaced (unless you stopped the service) and the details pane shows whether the restart worked.
ServiceMan fills in sensible defaults when your apps follow these:
- Binaries live in
~/.local/bin;clists them. - An app's own config lives in
~/.config/<binary>/. - An app's secrets live in
~/.secrets/<binary>.env; the New Service form uses it as the service's .env file when it exists. - A server with a
serviceman-infocommand (it prints JSON describing itself;caddyman-infois the same command, for CaddyMan) is autoconfigurable. The New Service list (c) and Track Services (t) mark it so, and list such binaries with the services. Picking it fills in the New Service form: description, arguments, health URL, app config and .env file. The Edit Service form fills in the ones left empty, and tracking an existing unit takes its health URL and app config. The health URL isauto: whenever it's checked, it's the one the server reports, so a server that picks its port on its first start is checked as soon as it has one (the HEALTH column saysno portuntil then), and a port changed later is followed.autoworks for any service whose binary hasserviceman-info, in the form, Set URL andserviceman track --url auto. Only binaries that contain the nameserviceman-infoare asked (in Track Services, only user units outside the distribution's directories), so other programs are never run with an argument they don't know. Each binary is asked once, and again when it or its config file changes.
The config is ~/.config/serviceman/config.json:
| Setting | Meaning |
|---|---|
editor |
Editor command; empty uses Emacs (emacsclient -t if a server is running) |
bin_dir |
Where c looks for binaries (~/.local/bin) |
log_dir |
Where log files go |
max_log_size_mb |
Rotate a log file at this size (20) |
max_log_files |
Rotated files to keep (5) |
services |
Tracked services (managed by ServiceMan) |
serviceman config version # your config's version vs. the current one
serviceman config update # add new settings (never changes existing ones)
serviceman config path # where the config is
serviceman config template # the default config
serviceman track [--user|--system] [--url URL] [--watch] [--config PATH] UNIT...
serviceman untrack UNIT...
serviceman list
serviceman daemon install | uninstall | status
serviceman paths # config, log and state locations
make uninstall # removes the daemon and the binary
rm -rf ~/.config/serviceman ~/.local/state/serviceman ~/.local/share/serviceman # config, state, logs
Services you tracked or created are left as they are.
See LICENSE.