A simple infrastructure monitoring tool.

Zenin is an infrastructure monitoring tool. You set up monitors that perform some kind of action, and Zenin records data.

Several probe types are built-in, and plugins are also supported. You can even arrange for plugins to be executed in response to the data your monitor collects.

Zenin is an evolution of other tools like Nagios and Uptime Kuma. It has no runtime dependencies; everything is included in the binary.

⚠️ Zenin started out as a fork of Uptime Kuma that added support for plugins.

See the troubleshooting section below if you have any problems running the container.

 docker run -d \
    -u zenin \
    -p 23111:23111 \
    -v ~/.config/zenin:/home/zenin/.config/zenin \
    --name zenin \
    jmkng/zenin:dev

This image is configured to use SQLite by default. No database setup is required.

You can configure it to use PostgresSQL by passing in some additional environment variables that tell Zenin how to connect to your database:

...

-e ZENIN_REPO_KIND=postgres
-e ZENIN_REPO_NAME=postgres
-e ZENIN_REPO_ADDRESS=0.0.0.0
-e ZENIN_REPO_PORT=5432
-e ZENIN_REPO_USERNAME=username
-e ZENIN_REPO_PASSWORD=password

...

Adjust the remaining flags as needed.

-u zenin

The image includes a non-root user account "zenin" so that you aren't forced to run as root.

Keep in mind, the built-in ICMP probe requires root access to send ICMP packets. If you aren't running as root, you can still use the ICMP probe to send UDP packets.

Just remove the flag to run as root.

-v ~/.config/zenin:/home/zenin/.config/zenin

Binds the directory ~/.config/zenin on your host system to /home/zenin/.config/zenin inside of the container. This allows you easy access to the database file and plugins from your host system.

You should change ~/.config/zenin to a path where you are comfortable storing this information.

Error: "make sure <plugins|themes> directory exists and is accessible"

If the host path of a bind mount does not exist when you pass it to the container, Docker will create it and it may be owned by root. Ensure the directory exists before starting the container.

Create the directory:

mkdir -p ~/.config/zenin

Or, adjust the user and group:

chown $USER:$USER ~/.config/zenin -R

If you want to build Zenin from source, follow these instructions.

1. Go v1.22.4+
2. Node.js v20.8.1+
   • npm v10.1.0+

Clone the project:

git clone https://github.com/jmkng/zenin

make build

You should end up with a zenin binary.

./zenin

The first account created on a Zenin server becomes the root account.

When you connect for the first time you will be prompted to claim the server by creating that account. Additional accounts can only be created by the root account. No registrations are allowed, your server is invite only.

After you claim the server, you can create monitors.

Themes are CSS files that Zenin reads from the themes directory.

You can change your theme through the settings pane in the user interface. By default, the theme is set to "Auto", which indicates no theme preference. In this mode, the default light or default dark theme will be used depending on system preference.

When Zenin loads a theme, it layers the theme over the default light or default dark theme, depending on the theme file name. If the name contains "dark," it will override the default dark theme; otherwise, it will override the default light theme. This affords more control over how your theme is presented.

Create a theme file named Snowball.css with these values, and it will layer over the default light theme:

/* Snowball.css */

:root {
    --background: rgb(252, 252, 252);
    --primary-button-background: rgb(150, 150, 150);
    --link-color: rgb(35, 150, 201);
    --focus-outline-color: rgb(35, 150, 201);
}

Create a dark version with the name Snowball Dark.css and darker color values:

/*  Snowball Dark.css */

:root {
    --background: rgb(27, 26, 28);
    --primary-button-background: rgb(80, 80, 80);
    --primary-button-color: var(--primary-color);
    --link-color: rgb(35, 150, 201);
    --focus-outline-color: rgb(35, 150, 201);
}

Zenin defines CSS Variables that can be modified to change the appearance of many elements in the user interface.

Many variables are applied broadly throughout the interface, such as --background, which is used as a general background color. However, more specific variables like --pane-background also exist for targeting specific areas.

You may also redefine a variable only for a small part of the interface:

:root {
    --hover-background: rgb(240, 240, 240);

    .dialog_portal, .dialog_modal {
        --hover-background: rgb(225, 225, 225);
    }
}

The button component uses the --hover-background variable to determine what color it should fade to when it is being hovered. This theme has defined --hover-background once in the root for all buttons to use, and once again within the .dialog_portal and .dialog_modal selectors. This means that buttons within dialogs and modals will have a slightly darker hover background.

You should prefer adjusting CSS variables over using selectors when possible, because it will minimize the chance that your theme will need to be updated in the future.

You can use your browser's developer tools to discover CSS variables that your theme can use. A list of recognized variables will also be documented here:

Recognized environment variables are documented here:

Clone the project:

git clone https://github.com/jmkng/zenin

Modify the export script as needed, and source it:

. scripts/export.sh

Start Zenin:

make run

If you are making changes to the user interface, start the local server for the web project too:

cd web && npm run dev

You can use the scripts in scripts/api to test the API, or just use them as example requests.

You might need these tools to run them:

• curl
• jq

Scripts that hit authenticated endpoints will expect a token to be in the ZENIN_SCRIPT_TOKEN environment variable. If you used the migrate script to insert seed data, you can just source the authenticate script to set this up for you:

. scripts/authenticate.sh

Use get_related to fetch all the monitors on the server, including the two most recent measurements for each:

scripts/api/monitor/get_related.sh

...

*   Trying 127.0.0.1:23111...
* Connected to 127.0.0.1 (127.0.0.1) port 23111
> GET /api/v1/monitor?measurements=2 HTTP/1.1
> Host: 127.0.0.1:23111
> User-Agent: curl/8.6.0
> Accept: */*
> Authorization: Bearer ...
> Content-Type: application/json
>
< HTTP/1.1 200 OK
< Access-Control-Allow-Headers: Content-Type, Authorization
< Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
< Access-Control-Allow-Origin: *
< Content-Type: application/json
< Date: Sun, 14 Jul 2024 19:17:07 GMT
< Transfer-Encoding: chunked
<
* Leftovers after chunking: 12 bytes
* Connection #0 to host 127.0.0.1 left intact
{"data":[ ... ]}

Alternatively, use jq to format the data:

scripts/api/monitor/get_related.sh | jq .

Use the makefile to build:

make

Linker flags are used to bake in a program version and the most recent commit hash.

Database tests are disabled by default. Enable them with the ZENIN_REPO_ENABLE_TEST environment variable.

Use the makefile to run tests:

go clean -testcache && make test