[200~docs: refine and modularize README for clarity and reusability

README.md

@@ -1,38 +1,49 @@
-# Lubelogger Backup Script
+# 📦 Lubelogger Backup Script
 
-This script automates the backup process for **Lubelogger**—a self-hosted, open-source vehicle maintenance records and fuel mileage tracker. It includes:
+This script automates the backup process for **Lubelogger** — a self-hosted, open-source vehicle maintenance records and fuel mileage tracker.
-- Creating backups of your Lubelogger database.
-- Storing them in a specified directory.
-- Notifying external systems like **Uptime Kuma** and **Gotify** about the backup status.
 
-## Features:
+## ✅ What It Does
-- **Automated Backup**: Downloads backups from the Lubelogger API.
-- **Notifications**: Sends notifications to Uptime Kuma and Gotify about backup success or failure.
-- **Log Management**: Generates logs for each backup with timestamps.
-- **Retention**: Automatically deletes old backup and log files after a specified number of days.
 
-## Prerequisites:
+- Creates a backup of your Lubelogger database.
-- **Lubelogger API**: Make sure your Lubelogger instance is running and the API endpoint for backup generation is accessible.
+- Stores backups in a local directory.
-- **Uptime Kuma**: For monitoring the backup process.
+- Notifies external systems (like **Uptime Kuma** and **Gotify**) of backup status.
-- **Gotify**: For receiving notifications about backup errors.
+- Cleans up backups and logs older than a specified retention period.
-- **Curl**: This script relies on `curl` to interact with APIs and download backups.
-- **Bash**: This script is written in bash and requires a Linux or Unix-based system.
 
-## Setup Instructions:
+---
 
-### 1. Clone the Repository:
+## ⚙️ Features
-Clone this repository to your local machine or server:
+
+- **Automated Backup** via the Lubelogger API
+- **Success/Failure Notifications** through Uptime Kuma and Gotify
+- **Detailed Logging** with timestamps
+- **Retention Policy** for auto-cleanup of old files
+
+---
+
+## 📋 Requirements
+
+- **Lubelogger** (accessible API endpoint for backups)
+- **Curl** (for HTTP requests)
+- **Bash** (Linux or Unix-based system)
+- *(Optional)* **Uptime Kuma** for monitoring
+- *(Optional)* **Gotify** for alerting
+
+---
+
+## 🚀 Setup
+
+### 1. Clone the Repository
 
 ```bash
 git clone https://git.nickhepler.cloud/nick/lubelogger-backup.git
 cd lubelogger-backup-script
 ```
 
-### 2. Create `.env` File:
+### 2. Configure Environment Variables
-Create a `.env` file in the same directory as the script to store the necessary configuration:
 
-```bash
+Create a `.env` file:
-# .env
+
+```env
 USERNAME=rootUser
 PASSWORD=rootPassword
 BASE_URL=https://lubelogger.mydomain.com
@@ -41,57 +52,52 @@ BACKUP_DIR=$HOME/lubelogger_backups
 RETENTION_DAYS=7
 BACKUP_TAG=lubelogger-db1
 
-# Uptime Kuma settings (only the hostname is required)
+# Uptime Kuma (optional)
 UPTIME_KUMA_URL=https://uptime-kuma.example.com
 UPTIME_KUMA_API_KEY=your-uptime-kuma-api-key
 
-# Gotify settings (only the hostname is required)
+# Gotify (optional)
 GOTIFY_PUSH_URL=https://push.example.de
 GOTIFY_PUSH_KEY=your-app-token
 ```
 
-- **USERNAME**: The root user for the Lubelogger API.
+> Make sure your Lubelogger API credentials and URLs are correct.  
-- **PASSWORD**: The root password for the Lubelogger API.
+> Optional services like Uptime Kuma and Gotify will only be used if their variables are set.
-- **BASE_URL**: The base URL for your Lubelogger instance.
-- **BACKUP_DIR**: The directory where backup files will be stored.
-- **RETENTION_DAYS**: The number of days to retain backups before deleting them.
-- **BACKUP_TAG**: A custom tag for identifying your backups.
-- **UPTIME_KUMA_URL**: The hostname for your Uptime Kuma instance (e.g., `https://uptime-kuma.example.com`).
-- **UPTIME_KUMA_API_KEY**: Your Uptime Kuma API key.
-- **GOTIFY_PUSH_URL**: The hostname for your Gotify instance (e.g., `https://push.example.de`).
-- **GOTIFY_PUSH_KEY**: Your Gotify application token.
 
-### 3. Make the Script Executable:
+### 3. Make the Script Executable
-Make the backup script executable:
 
 ```bash
 chmod +x lubelogger_backup.sh
 ```
 
-### 4. Run the Backup Script:
+### 4. Run the Backup
-To run the script manually, execute:
 
 ```bash
 ./lubelogger_backup.sh
 ```
 
-### 5. Automate the Backup (Optional):
+### 5. Automate via Cron (Optional)
-You can automate the backup process using `cron`. For example, to run the backup script every day at 2 AM, add the following cron job:
+
+To schedule daily backups at 2 AM:
 
 ```bash
 0 2 * * * /path/to/lubelogger_backup.sh
 ```
 
-## How It Works:
+---
-1. **Backup Creation**: The script sends a request to the Lubelogger API (`/api/makebackup`) to trigger the backup creation.
-2. **Backup Download**: The script downloads the backup as a `.zip` file from the generated URL.
-3. **Uptime Kuma Check-in**: The script sends a check-in to Uptime Kuma to indicate the backup is running as expected.
-4. **Gotify Error Notification**: If there are any errors during the backup process, Gotify is notified with the error details.
-5. **Log Management**: The script generates logs for each backup with detailed timestamps, errors, and status.
-6. **Retention**: The script automatically deletes backups and logs older than the specified retention period (configured in the `.env` file).
 
-## Example Output:
+## 🔍 How It Works
-When the script runs, you should see output logs like this:
+
+1. **Triggers** a backup via Lubelogger’s `/api/makebackup`
+2. **Downloads** the backup `.zip` from the returned URL
+3. **Sends** check-in to Uptime Kuma (if configured)
+4. **Sends** error notification via Gotify (if any failures)
+5. **Generates** a timestamped log file
+6. **Deletes** backups and logs older than `RETENTION_DAYS`
+
+---
+
+## 🖥️ Example Output
 
 ```bash
 [$(date)] 🔄 Starting Lubelogger backup job
@@ -102,27 +108,25 @@ When the script runs, you should see output logs like this:
 [$(date)] ✅ Backup job finished
 ```
 
-### Logs and Errors:
+---
-- The script scans logs for any occurrence of "Error" and sends a Gotify notification with the details.
+
-- In case of a failure in the backup process, Uptime Kuma and Gotify will be notified with the appropriate status.
+## 🧰 Troubleshooting
+
+### Uptime Kuma
+- Confirm `UPTIME_KUMA_URL` and `API_KEY` are correct
+- Ensure check-in monitoring is configured
+
+### Gotify
+- Validate push token and URL
+- Confirm your Gotify server is reachable and running
+
+### Permissions
+- Ensure `lubelogger_backup.sh` is executable
+- Verify `BACKUP_DIR` exists and is writable
 
 ---
 
-## Troubleshooting:
+## 📄 License
 
-### Uptime Kuma:
+Licensed under the **GNU General Public License v3.0**.  
-- Ensure that the Uptime Kuma check-in URL and API key are correctly set in the `.env` file.
+See the [LICENSE](LICENSE) file for full details.
-- Verify that Uptime Kuma is accessible and configured properly.
-
-### Gotify:
-- If Gotify notifications are not working, ensure that your Gotify server is correctly set up to accept push notifications via `POST` with form data.
-- Double-check the app token and push URL in the `.env` file.
-
-### Permissions:
-- Make sure that the script has the appropriate permissions to execute and access the backup directory.
-- Ensure that the directory specified in `BACKUP_DIR` exists and is writable by the user running the script.
-
----
-
-## License:
-This project is licensed under the GNU General Public License v3.0 or later - see the [LICENSE](LICENSE) file for details.