a user service supervisor

#44 Error with symbolic links in custom dir

~tomterl commented on superd todo

8 months ago

#46 xdg-desktop-portal doesn't auto-start

~whynothugo commented on superd todo

11 months 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 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.


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


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.

#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.


#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
#Running D-Bus as a superd service

D-bus can also run as a superd service. By default, clients will attempt to connect to the session socket $XDG_RUNTIME_DIR/bus. A simple service that runs the following command would listen on that same path:

dbus-daemon --session --address unix:path=$XDG_RUNTIME_DIR/bus

This has one major caveat: the dbus-server will only emit readiness notifications when built with systemd support, so it will not notify its readiness on distributions that build dbus-server without systemd support.

Ordering dependant services without readiness notification results in race conditions. For further discussion, see: https://todo.sr.ht/~craftyguy/superd/8