goplum

= Goplum

image::logo.png?raw=true[Goplum logo,role="right"]

Goplum is an extensible monitoring and alerting daemon designed for
personal infrastructure and small businesses. It can monitor
websites and APIs, and send alerts by text message if they go down.

== Getting started

The easiest way to run Goplum is via Docker. It doesn't require any
special privileges or settings, you just need to provide a config file
to it at `/goplum.conf`.

Running it via the command line:

[source]
----
docker run -d --restart always -v /path/to/my/goplum.conf:/goplum.conf csmith/goplum
----

Or using Docker Compose:

[source,yaml]
----
version: "3.8"

services:
  goplum:
    image: csmith/goplum
    volumes:
      - ./goplum.conf:/goplum.conf
    restart: always
----

For alternative installation methods see link:docs/install.adoc[the installation documentation].

== Configuration

Goplum's configuration contains an optional defaults section, a list of alerts, and
a list of checks. A simple example might look like this:

[source,goplum]
----
defaults {
  # Change the default interval for all checks to 10 second, rather than
  # Goplum's normal default of 30 seconds:
  interval = 10s
}

alert twilio.sms "text" {
  sid = "sid"
  token = "token"
  from = "+01 867 5309"
  to = "+01 867 5309"
}

check http.get "Example" {
  url = "https://www.example.com/"
}
----

This defines one check - of type `http.get` that will run every 30 seconds (the default
interval specified in the "defaults" block). If the check starts failing, all the
defined alerts will be triggered -- in this case sending a text message via Twilio.

Each check and alert has a name, which is used to refer to it in the config and in messages,
and a type. The type consists of the name of a plugin, a period, and then the type of check
or alert from that plugin. Some checks and alerts take parameters, which are specified as
`key = value` assignments within the block, one per line.

Checks have four additional settings. These can be changed globally by putting them in the
"defaults" section. If they're not specified then Goplum's built-in defaults will be used:

interval::
The time after which the check is repeated, for example `20s` for 20 seconds, `10m` for
10 minutes, or `7h` for 7 hours. Global default: 30 seconds.

alerts::
A list of alert names which should be triggered when the service changes state. The wildcard
'\*' may be used anywhere to match any number of characters. Note that an empty array is treated
the same as a missing option, so default settings will be used; to disable alerts use
`["-"]`. Global default: `["*"]` (all alerts).

failing_threshold::
The number of times a check must fail in a row before the service is considered failing.
This allows you to ignore brief, transient problems that may occur between your monitoring
location and the service itself, or very brief outages such as webserver restarts.
Global default: 2.

good_threshold::
The number of times a check must pass in a row before the service is considered up. This
prevents alert noise if a check occasionally passes for some reason. Global default: 2.

More information on the syntax for configuration files is found in the
link:docs/syntax.adoc[syntax guide].

== Bundled plugins

All checks and alerts in Goplum are implemented as plugins. The following are maintained in
this repository and are available by default in the Docker image:

* link:plugins/http[http] - checks for HTTP services, and alerting via webhooks
* link:plugins/network[network] - low level checks for network services
* link:plugins/pushover[pushover] - sends alerts via Pushover
* link:plugins/slack[slack] - sends alerts via Slack
* link:plugins/twilio[twilio] - sends SMS alerts via Twilio
* link:plugins/debug[debug] - provides tools for building and testing Goplum
* link:plugins/exec[exec] - allows executing arbitrary commands

== Plugin API

Goplum is designed to be easily extensible. Plugins must have a main package which contains
a function named "Plum" that returns an implementation of `goplum.Plugin`. They are then
compiled with the `-buildtype=plugin` flag to create a shared library.

The Docker image loads plugins recursively from the `/plugins` directory, allowing you to
mount custom folders if you wish to supply your own plugins.

Note that the Go plugin loader does not work on Windows. For Windows-based development,
the `goplumdev` command hardcodes plugins, skipping the loader.