~craftyguy/superd

a user service supervisor

df8e8ec manager: check that service template has @<param> when enabling

2 days ago

7c55270 changelog: add 0.7

24 days ago

superd is a user service supervisor that is only intended to be used for supervising user services. It makes absolutely no attempt to replace init/pid 1, and should never be used do to that.

#Design goals:

#Simple to configure

Service configuration uses systemd's .service files, so that it's low(er) effort to configure services. Many things intended to run as user services already have systemd config written. (Important: see later section on service configuration)

#Reasonably fast to start things

On startup, all service supervisors are started at once. The services run their commands if there are no dependencies specified, only services with dependencies wait for their dependencies to start up first.

#Only does 1 thing

This doesn't do anything except run some stuff, and manage the stuff it runs (restarting on failure, etc).

#Building

Building this project requires a Go compiler/toolchain and make:

$ make

To install locally:

$ make install

Installation prefix can be set in the generally accepted way with setting PREFIX:

$ make PREFIX=/some/location
# make PREFIX=/some/location install

Other paths can be modified from the command line as well, see the top section of the Makefile for more information.

#Usage

See relevant man pages: superd(1), superd.service(5), superctl(1)

#Contributing

Send patches and questions to the superd mailing list: https://lists.sr.ht/~craftyguy/superd

All patches should complete make test successfully.

A script is provided in the repo to help with running superd and superctl for debug/testing. It will create a directory structure under ./home in the repo and point the relevant XDG_* vars there, so that superd won't run services from ~/.config and will instead load/run anything you place in ./home. This allows running superd/superctl in a way that won't clash with an existing instance of superd (e.g. started by your login manager / DE.)

$ ./run superd -v
* Creating /home/clayton/src/superd/home/runtime_dir
* Creating /home/clayton/src/superd/home/config
* Creating /home/clayton/src/superd/home
export XDG_CONFIG_HOME='/home/clayton/src/superd/home/config'
export XDG_RUNTIME_DIR='/home/clayton/src/superd/home/runtime_dir'
export XDG_STATE_HOME='/home/clayton/src/superd/home'
Log is at: /home/clayton/src/superd/home/superd.log

Optionally, delve can be invoked by setting DEBUG:

$ DEBUG=1 ./run superctl status
export XDG_CONFIG_HOME='/home/clayton/src/superd/home/config'
export XDG_RUNTIME_DIR='/home/clayton/src/superd/home/runtime_dir'
export XDG_STATE_HOME='/home/clayton/src/superd/home'
Log is at: /home/clayton/src/superd/home/superd.log
Type 'help' for list of commands.
(dlv)

#Getting Help

There's an IRC channel on OFTC: #superd

And a mailing list: https://lists.sr.ht/~craftyguy/superd

There's also a Todo page: https://todo.sr.ht/~craftyguy/superd

However, please ask for assistance in IRC or on the mailing list, before filing a new issue at the project's todo page.

#FAQ

#Why yet another supervisor thing, and not use runit, supervisord, s6, upstart/startup, systemd, whatever?

I don't always use distros that use systemd. I believe that declarative service config, while less powerful than writing piles of shell script, is easier to do and maintain long term. Almost everything else is either complicated to setup, can't handle dependencies, tries to do too much, or would require most folks to spend some non-trivial amount of time to learn to configure and "port" services too.

#Why call it "superd"?

"Super" is short for "supervisor" or "superintendent." The "d" is added at the end because that's currently the cool trendy thing to do with daemons.

#How do I run this thing?

If you require a dbus user session, it's currently best to just start some window manager (e.g. sway) with dbus-run-session <wm exe>, and then have superd run via whatever autostart mechanism the window manager provides.

For example, with sway:

$ cat ~/.config/sway/config
...
exec superd
...
$ dbus-run-session /usr/bin/sway

Theoretically there should be a way to start dbus as another service managed by superd, and specify a known address for the dbus session socket, but this needs more work since communicating the dbus address to services that need it is a bit janky. Also see: https://todo.sr.ht/~craftyguy/superd/8