Monika: synthetic monitoring driven by a YAML file of probes

Monika turns a list of URLs into scheduled checks

Monika exists to answer one question on a schedule: is your service answering, and is it answering quickly. The project describes itself as a command line application for synthetic monitoring, and the name comes from MonitoringBerkala, periodic monitoring in Indonesian. That framing matters for who the tool suits. It is a process you start, point at a configuration file, and leave running. There is no hosted component and no dashboard account in the repository layout.

The configuration is YAML, and it holds a list of probes. Each probe describes what to check and what counts as a failure. The project summary is explicit about the second half of that promise: you get an alert when the site is slow as well as when it is down, so latency is a first class part of the model rather than an afterthought attached to a downtime check.

This shape fits a small operations team. It also fits a larger team that wants to keep monitoring configuration inside the same review process as the rest of its infrastructure, since the file is plain YAML and lives next to the code it describes.

Assertions decide what counts as an outage

A probe in Monika pairs requests with alerts, and each alert carries an assertion expression plus a message. The assertion is evaluated against the response, which means the failure condition is written by you instead of being inferred from a status code list. The docker compose services defined in the repository include HTTPBin, and the configuration shown for it uses expressions such as response.status != 302 and response.status == 302.

That first probe is short enough to read in one breath:

probes:
  - id: 'should not follow redirect'
    requests:
      - url: http://localhost:3000/status/302
        followRedirects: 0
    alerts:
      - assertion: response.status != 302
        message: You should not follow the redirect

Here followRedirects is set to 0, so the alert fires when the status is anything other than 302. The message is plain text that a human will read in a chat channel, so the wording of the message matters as much as the expression. The expression language reaches beyond the status code, since a probe can also assert on response time to catch the slow case the project advertises.

Redirect handling is a choice the config has to make for you

The HTTPBin examples in the repository are a small lesson in how much a probe depends on defaults. The same host, port 3000, is probed three times with three different behaviours: one request disables redirect following, one leaves the setting out entirely, and one sets followRedirects to 2. Each of the three carries its own assertion and its own message, which tells you the status code you get back can change based on that single field.

The practical consequence is that a probe written against a redirecting URL can pass or fail for reasons that have nothing to do with the service you care about. If the default behaviour of the HTTP client changes in a future release, an assertion written for the old default stops meaning what you intended. Pinning followRedirects explicitly on probes that involve redirects removes that ambiguity, and the repository makes it cheap because the setting is a single key under a request.

The same caution applies to the message strings. In the shipped examples, the alert that fires on a successful redirect reads You are not following the redirect, which is worded for the failing case rather than the passing one. If you copy those blocks verbatim, the text your team receives will not match the outcome.

One YAML file mixes HTTP probes and database probes

Monika is not limited to HTTP. The development documentation includes probe blocks for MariaDB, MySQL, MongoDB, PostgreSQL and Redis, and they sit in the same probes list as the HTTP entries. A MariaDB probe uses a host, port, username, password and database key, while MongoDB, PostgreSQL and Redis take a connection URI instead. The MySQL sample uses port 3307 and MariaDB uses 3306, matching the port mapping of the compose services in the dev folder.

This makes Monika useful for checking more than the public edge of a stack, but it also means one file holds several different credential shapes. The samples place the username and password directly in the YAML with a database key left empty, so an operator fills in the values in the file itself. That is convenient for a quick local test against the compose services, and it means a copy of the file is a copy of the credentials. If that file ever lands in a repository or an image layer, the credentials travel with it.

Running from source means building before you can monitor

The README documents installation on a separate Quick Start page rather than in the repository itself, and the badges point at the npm package @hyperjumptech/monika and a Docker image on Docker Hub. The in-repository path is the developer path. It is a Node.js application written in TypeScript on the oclif framework, developed on node 20 (LTS) with npm v10, and the package manifest sets the CLI entry point to ./bin/run.js.

To work on the source, clone the repository and install the dependencies:

git clone [email protected]:hyperjumptech/monika.git
npm ci
npm run build -w packages/notification

The notification workspace has to be built separately, since notifications live in their own package. From there the CLI starts in development mode on Linux, Unix and Mac:

npm start

On Windows the equivalent is the dev.cmd script in the bin folder. The start script is not a thin wrapper. It runs the clean, TypeScript build and oclif manifest generation first, so every launch pays for a compile before the first probe is sent. Formatting and regression checks are separate commands, npm run format and npm run test.

Prometheus output and a local lab of services

The repository includes a Prometheus path, which changes what Monika is useful for. The documented flow starts the Prometheus server from its own compose file, then starts Monika with a Prometheus flag and a port, then opens the Expression Browser at localhost:9090/graph to query the metrics. The two commands are given as `docker compose -f ./dev/prometheus/docker-compose.yaml up` and `npm start -- --prometheus 3001`.

That second command is the most useful single detail in the README for anyone already running Prometheus. It gives you a monitor that both sends alerts and exposes metrics, instead of a tool that only tells you something is broken. The flag also tells you the port is a parameter of the CLI rather than a fixed setting, which matters if you run more than one instance with different configuration files.

For testing probes without touching real infrastructure, the dev folder holds a compose stack of services you can probe locally, started with `cd dev && docker compose up`. The stack covers HTTPBin plus the five databases used in the probe samples, which is enough to exercise the probe types end to end before pointing Monika at production.

The container starts Monika with no arguments and expects a mounted config

The Dockerfile reveals the deployment contract. The build stage uses node:20-alpine, installs the npm workspaces, packs the CLI, and the runtime stage installs the packed tarball globally with npm install -g --unsafe-perm. The runtime image is node:18-alpine, which is older than the node 20 (LTS) the README says the project was developed on. That gap is the kind of thing worth checking before you run the image in production, because the runtime major version is not the one the project targets.

The container creates a /config directory and its command is bare:

FROM node:18-alpine AS runner
RUN apk update && apk add python3 py3-setuptools make gcc
COPY --from=builder /monika/hyperjumptech-monika-*.tgz ./
COPY --from=builder /monika/packages/notification/hyperjumptech-monika-notification-*.tgz ./packages/notification/
RUN npm install -g --unsafe-perm ./hyperjumptech-monika-*.tgz
WORKDIR /
RUN mkdir /config
STOPSIGNAL SIGINT
CMD ["monika"]

The Makefile shows how the pieces fit. The docker-run target mounts monika.example.yml at /config/monika.yml and runs the image detached, which means the image carries no usable configuration of its own and the config arrives entirely through a volume. The image also sets STOPSIGNAL SIGINT, so shutdown depends on Monika handling an interrupt rather than the default SIGTERM, a detail that matters if you rely on a grace period to finish in-flight probes. The repo also ships snapcraft.yaml and a Dockerfile.flyio, so container packaging is a first class part of how this project ships.

Editorial conclusion

Monika is worth adopting if your team wants self-hosted synthetic checks over HTTP and a handful of databases, and is comfortable maintaining a YAML file and a container. It is the wrong tool if you need a managed status page, multi-tenant alerting or a support contract. Before committing, check that the version you install matches the configuration format you plan to write: the packaged version is 1.22.0, released on 2025-02-24, while the last push to main was on 2026-10-22, and the repository also ships monika.example.yml and monika.example.json as the reference for your own file.

Frequently asked questions

Official sources

1. hyperjumptech/monika on GitHub
2. License: MIT
3. Project website
4. README
5. Releases