horust 0.1.0

A complete supervisor and init system, designed for running in containers.
Documentation

GHA Build Status MIT licensed

Horust is a supervisor system written in rust and designed to be run in containers.

Table of contents

Goals

  • Supervision: A feature full supervision system, designed (but not limited) to be used in containers.
  • Init system: Use Horust as your init system.
  • Understandability: The code should be easy to understand and easy to modify.
  • Rock solid: You should be able to trust your favorite egyptian God.

Status

At this point, this should be considered Alpha software.

Usage

Let's go through a simple example usage. We will create a website healthchecker using horust and a python script.

  1. Create a directory: mkdir -p /etc/horust/services
  2. Create your first service: /etc/horust/services/healthchecker.toml
command = "/tmp/healthcheck.py"
start-delay = "10s"
[restart]
strategy = "always"

There are many supported properties for your service file, but they are all optional. This is as minimal as we can get. As soon as we run horust, this service will be read and the command run. As soon as the service is over it won't be restarted, and horust will exit.

  1. Create a new file called healthcheck.py and in tmp:
#!/usr/bin/python3
import urllib.request
import sys
req = urllib.request.Request("https://www.google.com", method="HEAD")
resp = urllib.request.urlopen(req)
if resp.status == 200:
    sys.exit(0)
else:
    sys.exit(1)

Add execution permissions to it: chmod +x /tmp/healthcheck.py.

  1. Run horust: "./horust". By default it will search services inside the /etc/horust/services folder.

Now every 10 seconds, this will send an http head request to google.it. If the response is different than 200, then there is an issue!

In this case, we're just exiting with a different exit code. But in real life, you could trigger other actions. Use ctrl+c for stopping horust. Horust will send a SIGTERM signal to all the running services, and if it doesn't hear back for a while, it will terminate them via a SIGKILL.

Check the documentation for a complete reference of the options available on the service config file.

You can also bootstrap the creation of a new service, by using horust --sample-service > new_service.toml.

command = "/bin/bash -c 'echo hello world'"
working-directory = "/tmp/"
start-delay = "2s"
start-after = ["another.toml", "second.toml"]
user = "root"

[restart]
strategy = "never"
backoff = "0s"
attempts = 0

[healthiness]
http-endpoint = "http://localhost:8080/healthcheck"
file-path = "/var/myservice/up"

[failure]
successful-exit-code = [ 0, 1, 255]
strategy = "ignore"

[termination]
signal = "TERM"
wait = "10s"
die-if-failed = ["db.toml"]

Contributing

Thanks for considering contributing to horust! For getting started have a look on CONTRIBUTING.md.

License

Horust is provided under the MIT license. Please read the attached license file.