README.md
1# Paladin
2
3A simple process supervisor written in Go.
4
5## Description
6
7Paladin is a simple way to launch and maintain services. It provides the
8following features:
9- Simple TOML configuration.
10- Automatically restart failed processes.
11- Log each process to a different file, even separating stdout and stderr.
12- Specify process dependencies, so things start in the right order.
13- Launch processes under different users and groups.
14
15## Installation
16
17- Clone this repo in your `$GOPATH`.
18- Copy `etc/paladin.conf.sample` to `/etc/paladin.conf` and set your values.
19- Run `go build`.
20- Put `paldin` in your path.
21
22Compile with something like `-ldflags="-X main.localbase=/usr/local"` on
23systems where the config file will not live under `/etc`, such as FreeBSD.
24
25## License
26
27This code is under the BSD-2-Clause license. See the LICENSE file for the full
28text.
29
30## Configuration
31
32The config file uses TOML format. It consists of general options, and several
33`[[process]]` blocks that define each process that paladin is responsible for.
34
35### General Options
36
37The following general options do not go inside a TOML block:
38
39|Name | Required | Description
40|----------|---|-----------------------------------------------------
41|`log_file`| N | File path for main output. An empty string means stderr.
42
43### Process-specific Options
44
45The following options are per-process, and go in a `[[process]]` block:
46
47|Name | Required | Description
48|----------------|---|-------------------------------------------------------
49|`name` | Y | Used to identify the process. Must be unique.
50|`path` | Y | The full path to the program to be run.
51|`args` | N | An array of string arguments for the process.
52|`cwd` | N | The current working directory for the process.
53|`stdout` | N | The file path for logging stdout.
54|`stderr` | N | The file path for logging stderr. Follows stdout if unset.
55|`user` | N | Run the process as this user.
56|`group` | N | Run the process as this group.
57|`restart_delay` | N | Milliseconds to wait before restarting.
58|`ignore_failure`| N | Boolean. Set to `true` to disable restarting on failure.
59|`min_runtime` | N | Don't restart if it fails in fewer than this many milliseconds.
60|`soft_depends` | N | List of processes that must be started before this one.
61
62### Example Configuration
63
64```
65log_file = "/var/log/paladin.log"
66
67[[process]]
68name = "my-program"
69path = "/path/to/my-program"
70args = []
71cwd = "/path/to"
72restart_delay = 1000
73min_runtime = 100
74stdout = "/tmp/my-program-stdout"
75user = "myuser"
76group = "mygroup"
77
78[[process]]
79name = "my-other-program"
80path = "/path/to/my-other-program"
81args = ["-a", "-d"]
82min_runtime = 100
83soft_depends = [ "my-program" ]
84restart_delay = 1000
85```
86
87### Command-line Options
88
89| Name | Required | Description
90|------|----------|------------
91|`-f` | N | The config file to use. Defaults to /etc/paladin.conf (unless localbase is set).
92
93