octokuma/README.md

<h2><img align="middle" src="https://raw.githubusercontent.com/odb/official-bash-logo/master/assets/Logos/Icons/PNG/64x64.png" >
Octokuma - Easy Monitor and Reboot Lightsail Instances
</h2>

**octokuma** is a script designed to monitor specific Uptime Kuma monitors and automatically reboot corresponding Amazon Lightsail instances if any of them go down. It leverages the `octosail` script to manage the Lightsail instances and can be scheduled to run at regular intervals using systemd timers.

## Table of Contents

- [Features](#features)
- [How It Works](#how-it-works)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
  - [Automatic Configuration](#automatic-configuration)
  - [Manual Configuration](#manual-configuration)
- [Running the Script](#running-the-script)
- [Setting Up Systemd Timer](#setting-up-systemd-timer)
  - [Create and Configure the Service File](#create-and-configure-the-service-file)
  - [Create and Configure the Timer File](#create-and-configure-the-timer-file)
  - [Enable and Start the Timer](#enable-and-start-the-timer)
- [Logging](#logging)
- [Troubleshooting](#troubleshooting)
- [Additional Notes](#additional-notes)
  - [Running the Script as Current User](#running-the-script-as-current-user)
  - [Environment Variables](#environment-variables)
  - [Ensuring AWS CLI Access](#ensuring-aws-cli-access)
  - [Permissions for octosail Script](#permissions-for-octosail-script)
  - [Testing the Setup](#testing-the-setup)
  - [Monitoring the Service](#monitoring-the-service)
  - [Stopping the Timer](#stopping-the-timer)
- [License](#free-software-license)

## Features

- Monitors specified Uptime Kuma monitors.
- Automatically reboots corresponding Amazon Lightsail instances if a monitor is down.
- Interactive configuration setup using `whiptail`.
- Dependency checks and automatic installation prompts.
- Designed to run as a systemd service for regular monitoring.
- **Runs as the current user** to access user-specific configurations.
- **Logs are stored in `~/.local/log/`** to keep your home directory organized.

## How It Works

1. **Dependency Checks:**
   - Ensures that `jq`, `whiptail`, and `octosail` are installed.
   - Prompts the user to install any missing dependencies.

2. **Configuration Loading:**
   - Reads configuration from a JSON file located in the user's home directory.
   - If the configuration file is not found, prompts the user to create it interactively.

3. **Monitoring Logic:**
   - Iterates over each monitor specified in the configuration.
   - Checks the status of each monitor via Uptime Kuma's API.
   - If a monitor is down, uses `octosail` to reboot the associated Lightsail instance.

## Prerequisites

- **AWS CLI:** The script requires the AWS Command Line Interface (CLI) to interact with your AWS account.
- **AWS Credentials:** You need to have your AWS credentials configured. The `octosail` script will help you set this up if not already configured.
- **Dependencies:**
  - `jq`: For JSON parsing.
  - `whiptail`: For interactive prompts.
  - `octosail`: Script to manage Lightsail instances.

## Installation

1. **Download the Script:**

   ```bash
   sudo curl -L "https://git.vdm.dev/api/v1/repos/octoleo/octokuma/raw/src/octokuma" -o /usr/local/bin/octokuma
   sudo chmod +x /usr/local/bin/octokuma
   ```

2. **Ensure Dependencies are Installed:**

   The script will check for dependencies and prompt you to install any that are missing when you run it for the first time.

## Configuration

The script uses a JSON configuration file to store settings, including the Uptime Kuma URL and the list of monitors to check.

### Automatic Configuration

When you run the script for the first time, it will check for the configuration file. If not found, it will prompt you to create it interactively using `whiptail`.

**Steps:**

1. **Run the Script:**

   ```bash
   octokuma
   ```

2. **Follow the Prompts:**

   - **Uptime Kuma URL:**
     - You will be asked to enter your Uptime Kuma URL.
   - **Add Monitors:**
     - The script will ask if you want to add a monitor.
     - If you select "Yes," you will be prompted to enter the Monitor ID and the corresponding Lightsail Instance Name.
     - Repeat the process to add multiple monitors.
   - **Save Configuration:**
     - Once you have added all monitors, the configuration will be saved to the default path (`$HOME/.config/octokuma/config.json`).

### Manual Configuration

If you prefer to create or edit the configuration file manually, follow these steps:

1. **Create the Configuration Directory:**

   ```bash
   mkdir -p $HOME/.config/octokuma
   ```

2. **Create the Configuration File:**

   ```bash
   nano $HOME/.config/octokuma/config.json
   ```

3. **Add the Following Content:**

   ```json
   {
     "uptime_kuma_url": "https://your-uptime-kuma-url",
     "monitors": [
       {
         "monitor_id": 24,
         "instance_name": "YourInstanceName1"
       },
       {
         "monitor_id": 25,
         "instance_name": "YourInstanceName2"
       }
     ]
   }
   ```

   - Replace `"https://your-uptime-kuma-url"` with your actual Uptime Kuma URL.
   - Replace `monitor_id` and `instance_name` with your actual monitor IDs and corresponding Lightsail instance names.

4. **Save and Close the File:**

   Press `Ctrl+O` to save and `Ctrl+X` to exit.

**Note:** You can also specify a custom configuration file path using the `--config` option:

```bash
octokuma --config /path/to/your/config.json
```

## Running the Script

To run the script manually, simply execute:

```bash
octokuma
```

- If you have specified a custom configuration file, use:

  ```bash
  octokuma --config /path/to/your/config.json
  ```

## Setting Up Systemd Timer

To automate `octokuma` execution at regular intervals, configure a systemd service and timer with `sudo systemctl edit --force --full`.

### Create and Configure the Service File

1. **Edit the service file by running:**

   ```bash
   sudo systemctl edit --force --full octokuma.service
   ```

2. **Enter the following content for the service configuration:**

   ```ini
   [Unit]
   Description=OctoKuma Monitoring Service

   [Service]
   Type=oneshot
   User=ubuntu
   Group=ubuntu
   ExecStart=/usr/local/bin/octokuma
   ExecStartPre=/bin/sh -c 'if [ -e /var/lock/octokuma-monitoring.lock ]; then echo "Monitoring already in progress."; exit 1; else touch /var/lock/octokuma-monitoring.lock; fi'
   ExecStartPost=/bin/rm -f /var/lock/octokuma-monitoring.lock
   StandardOutput=append:/home/ubuntu/.local/log/octokuma.log
   StandardError=append:/home/ubuntu/.local/log/octokuma.log
   ```

3. **Save and close the file.**

   - `User=ubuntu` and `Group=ubuntu` ensure that the service runs with appropriate permissions.
   - Change `ubuntu` to your relevant user name and group name.
   - Logs are directed to `/home/ubuntu/.local/log/octokuma.log`.

### Create and Configure the Timer File

1. **Edit the timer file by running:**

   ```bash
   sudo systemctl edit --force --full octokuma.timer
   ```

2. **Enter the following configuration for the timer:**

   ```ini
   [Unit]
   Description=Run OctoKuma Monitoring Service every 5 minutes

   [Timer]
   OnCalendar=*:0/5
   Persistent=true

   [Install]
   WantedBy=timers.target
   ```

3. **Save and close the file.**

   - `OnBootSec=1min` triggers the service 1 minute after system boot.
   - `OnUnitActiveSec=5min` schedules it to run every 5 minutes thereafter.

### Enable and Start the Timer

To activate the timer:

```bash
sudo systemctl enable octokuma.timer
sudo systemctl start octokuma.timer
```

### Verifying the Service and Timer

- **Service Status:**

  ```bash
  sudo systemctl status octokuma.service
  ```

- **Timer Status:**

  ```bash
  sudo systemctl status octokuma.timer
  ```

## Logging

- **Log File Location:** The log file is located at `/home/ubuntu/.local/log/octokuma.log`.

Ensure the log directory exists:

```bash
mkdir -p /home/ubuntu/.local/log
```

## Troubleshooting

1. **Dependency Issues:**
   - Install missing dependencies:

     ```bash
     sudo apt-get install jq whiptail
     ```

2. **Configuration Issues:**
   - Validate the configuration file:

     ```bash
     jq '.' /path/to/config.json
     ```

3. **AWS CLI Configuration:**
   - Configure AWS CLI with:

     ```

bash
     aws configure
     ```

4. **Permissions Issues:**
   - Ensure `octosail` is executable:

     ```bash
     sudo chmod +x /usr/local/bin/octosail
     ```

## Additional Notes

- **Environment Variables:** Adjust `PATH` if necessary.
- **Testing the Setup:** Test `octokuma` manually to verify functionality:

  ```bash
  octokuma
  ```

- **Stopping the Timer:** Disable with:

  ```bash
  sudo systemctl disable --now octokuma.timer
  ```

---
# Free Software License
```txt
@copyright  Copyright (C) 2021 Llewellyn van der Merwe. All rights reserved.
@license    GNU General Public License version 2; see LICENSE
```

**Disclaimer:** Be cautious when using scripts that can reboot servers. Ensure you have proper access controls and safeguards in place to prevent unintended actions. Test the script thoroughly in a safe environment before deploying it to production.