diff --git a/README.md b/README.md index fdd46a5..8d0b766 100644 --- a/README.md +++ b/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: -- Creating backups of your Lubelogger database. -- Storing them in a specified directory. -- Notifying external systems like **Uptime Kuma** and **Gotify** about the backup status. +This script automates the backup process for **Lubelogger** β€” a self-hosted, open-source vehicle maintenance records and fuel mileage tracker. -## Features: -- **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. +## βœ… What It Does -## Prerequisites: -- **Lubelogger API**: Make sure your Lubelogger instance is running and the API endpoint for backup generation is accessible. -- **Uptime Kuma**: For monitoring the backup process. -- **Gotify**: For receiving notifications about backup errors. -- **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. +- Creates a backup of your Lubelogger database. +- Stores backups in a local directory. +- Notifies external systems (like **Uptime Kuma** and **Gotify**) of backup status. +- Cleans up backups and logs older than a specified retention period. -## Setup Instructions: +--- -### 1. Clone the Repository: -Clone this repository to your local machine or server: +## βš™οΈ Features + +- **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: -Create a `.env` file in the same directory as the script to store the necessary configuration: +### 2. Configure Environment Variables -```bash -# .env +Create a `.env` file: + +```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. -- **PASSWORD**: The root password for the Lubelogger API. -- **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. +> Make sure your Lubelogger API credentials and URLs are correct. +> Optional services like Uptime Kuma and Gotify will only be used if their variables are set. -### 3. Make the Script Executable: -Make the backup script executable: +### 3. Make the Script Executable ```bash chmod +x lubelogger_backup.sh ``` -### 4. Run the Backup Script: -To run the script manually, execute: +### 4. Run the Backup ```bash ./lubelogger_backup.sh ``` -### 5. Automate the Backup (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: +### 5. Automate via Cron (Optional) + +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: -When the script runs, you should see output logs like this: +## πŸ” How It Works + +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: -- Ensure that the Uptime Kuma check-in URL and API key are correctly set in the `.env` file. -- 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. +Licensed under the **GNU General Public License v3.0**. +See the [LICENSE](LICENSE) file for full details.