Quick Start

Getting Started

To start monitoring URLs, you need to provide a configuration (JSON file) either from an URL or local file. The configuration file contains the probes, alerts, and notification configurations. You can generate a configuration file using Monika Config Generator web app. Alternatively, you can use one of the following configuration examples:

1. SMTP Gmail
2. Mailgun
3. SendGrid
4. Webhook
5. Slack
6. Telegram
7. WhatsApp
8. Microsoft Teams
9. Monika Whatsapp Notifier
10. Desktop Notifications
11. Default

When you have created the configuration file, you can run monika as follows

 monika -c <path_to_your_configuration.json>

Or you can provide an URL that contains monika configuration

 monika -c https://domain.com/path/to/your/configuration.json

Options and parameters can be seen by running monika -h. Or if you cloned this repository, you need to run bin/run -h.

Quick Start

At the center of monica is a configuration file. Follow the following steps to quickly setup monitoring and get notification when a website is down via Gmail.

1. Create a monika.json file and fill it out with the following

   1 {
   2   "notifications": [
   3     {
   4       "id": "unique-id-smtp",
   5       "type": "smtp",
   6       "data": {
   7         "recipients": ["YOUR_EMAIL_ADDRESS_HERE"],
   8         "hostname": "smtp.gmail.com",
   9         "port": 587,
   10         "username": "YOUR_GMAIL_ACCOUNT",
   11         "password": "YOUR_GMAIL_PASSWORD_OR_APP_PASSWORD"
   12       }
   13     }
   14   ],
   15   "probes": [
   16     {
   17       "id": "1",
   18       "name": "Monika Landing Page",
   19       "description": "Landing page of awesome Monika",
   20       "interval": 10,
   21       "requests": [
   22         {
   23           "url": "https://hyperjumptech.github.io/monika",
   24           "timeout": 7000
   25         }
   26       ],
   27       "alerts": ["status-not-2xx"]
   28     }
   29   ]
   30 }

2. Replace YOUR_EMAIL_ADDRESS_HERE in the monika.json with your email address that will receive the notification.

3. Replace YOUR_GMAIL_ACCOUNT with your valid Gmail account, e.g., yourname@gmail.com.

4. Replace YOUR_GMAIL_PASSWORD_OR_APP_PASSWORD with your Gmail password.

   1. If you have activated Two Factor Authentication (2FA), you need to create an app password. Refer here to create an app password for your Gmail account.

5. If you have installed Monika globally, run monika from Terminal app (macOS) in the same directory where monika.json exists. If you haven't, you can quickly run Monika by running npx @hyperjumptech/monika in the same directory where monika.json exists.

6. During runtime, Monika will output a log that looks like this

    INFO (on x1): Starting Monika. Probes: 4. Notifications: 1

1 INFO: 2021-06-16T04:14:40.128Z 1 id:5 200 http://localhost:7001/health 7ms
2 INFO: 2021-06-16T04:14:45.109Z 2 id:5 200 http://localhost:7001/health 4ms
3 INFO: 2021-06-16T04:14:50.126Z 3 id:5 200 http://localhost:7001/health 10ms
4 INFO: 2021-06-16T04:14:55.107Z 4 id:5 200 http://localhost:7001/health 1ms
5 WARN: 2021-06-16T04:15:00.117Z 5 id:5 500 http://localhost:7001/health 0ms, ALERT: status-not-2xx
6 WARN: 2021-06-16T04:15:05.371Z 6 id:5 500 http://localhost:7001/health 0ms, ALERT: status-not-2xx
7 WARN: 2021-06-16T04:15:10.128Z 7 id:5 500 http://localhost:7001/health 0ms, ALERT: status-not-2xx
8 WARN: 2021-06-16T04:15:15.138Z 8 id:5 500 http://localhost:7001/health 0ms, ALERT: status-not-2xx, NOTIF: service probably down
9 INFO: 2021-06-16T04:15:20.130Z 9 id:5 200 http://localhost:7001/health 6ms
10 INFO: 2021-06-16T04:15:25.128Z 10 id:5 200 http://localhost:7001/health 4ms
11 INFO: 2021-06-16T04:15:30.137Z 11 id:5 200 http://localhost:7001/health 6ms
12 INFO: 2021-06-16T04:15:35.146Z 12 id:5 200 http://localhost:7001/health 8ms, NOTIF: service is back up
13 INFO: 2021-06-16T04:15:40.140Z 13 id:5 200 http://localhost:7001/health 4ms
14 
15 
16 INFO_TYPE: current-time iteration probe:id _probeURL_ [response time in ms],[ALERT messages if any], [NOTIFICATION messages if any]

1 ## Configuration file
2 
3 > The configuration file contains the [notification](/monika/guides/notifications), [probes](/monika/guides/probes), and [alerts](/monika/guides/alerts) as shown below.

// monika.json

{ "notifications": [...], "probes": [ { ... "alerts": [...] } ] }

1 For advanced configuration, you can find them on the sidebar menu.
2 
3 Monika by default reads a configuration file called `monika.json` in the current working directory if it exists. You can specify a path to a JSON configuration file with `-c` flag as follows
4 
5 ```bash
6 monika -c <path_to_configuration_json_file>

Or if you haven't installed Monika globally, you can run it without installing first using npx:

 npx @hyperjumptech/monika -c <path_to_configuration_json_file>

Background run

By default Monika will run in the foreground. Like other Node.js applications, there are several ways to run Monika in the background on Unix, Linux, and macOS.

Using nohup

• On your terminal, run nohup monika &

• You'll get an output similar to the following.

  1 [1] 93457
  2 appending output to nohup.out

  In the above example, 93457 is the process ID (pid). And the output of Monika is written to nohup.out file.

• To stop Monika, run kill -9 <pid>.

Using screen

• On Debian/Ubuntu, you can install it by running sudo apt install screen.

• Run screen.

• Run monika -c monika.json

• Press Ctrl+a then D. This will cause Monika to run on a different screen in the background.

• To go back to the screen, run screen -ls to list the running screens. You will get an output similar to the following.

  1 There is a screen on:
  2   9049.pts-0.the-server (03/23/21 08:34:38) (Detached)
  3   1 Socket in /run/screen/S-server.

  9049.pts-0.the-server is the name of the screen.

• Then run screen -r <name_of_the_screen>.

• To stop Monika, hit Ctrl+c then Ctrl+d.