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`, and optionally give it a persistent directory
to store data in across restarts.

Running it via the command line:

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

Or using Docker Compose:

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

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

For more information and 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
}

# An alert named 'text' that will send an SMS message via Twilio:
alert twilio.sms "text" {
  sid = "sid"
  token = "token"
  from = "+01 867 5309"
  to = "+01 867 5309"
}

# A check named 'Example' that checks a webpage is accessible:
check http.get "Example" {
  url = "https://www.example.com/"
}
----

This defines one check and one alert. You can add as many of both as you want; by default
all alerts will be triggered when a check changes status.

All checks have a number of additional settings to control how they work. These can be
specified for each check, or changed globally by putting them in the "defaults" section.
If they're not specified then Goplum's built-in defaults will be used.

|===
|Setting |Description |Default

|`interval`
|Length of time between each run of the check.
|`30s`

|`timeout`
|Maximum length of time the check can run for before it's terminated.
|`20s`

|`alerts`
|A list of alert names to trigger when the service changes state.
 Supports '*' as a wildcard.
|`["*"]`

|`failing_threshold`
|The number of checks that must fail in a row before a failure alert is raised.
|`2`

|`good_threshold`
|The number of checks that must pass in a row before a recovery alert is raised.
|`2`
|===

An link:docs/example.conf[extended example] and a
link:docs/syntax.adoc[detailed guide to configuration syntax] are available in
the docs folder.

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