diff --git a/README.md b/README.md index eeef1e8..f7cbd7d 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,147 @@ -# PangolinSentinel +
+ Pangolin Sentinel Logo +

Pangolin Sentinel

+

Unraid & Docker VPS Update & Hot-Backup Hub

+

+ Docker + Unraid + FastAPI + Vue 3 + License +

+
+--- + +**Pangolin Sentinel** is a production-grade, self-hosted web application and daemon built specifically for monitoring, updating, and backing up your remote Pangolin Reverse Proxy VPS directly from an Unraid server or any Docker host. + +--- + +## 🌟 Key Features + +### 1. Pangolin Stack Management & Safe Updates +- **Full Remote Stack Control**: Inspects and controls Pangolin (`fosrl/pangolin`), Gerbil WireGuard tunnels (`fosrl/gerbil`), and Traefik ingress containers over secure SSH. +- **One-Click Safe Stack Update**: Pulls latest Docker images, recreates containers, cleans dangling images, and runs post-update health checks. +- **Zero-Downtime Hot Backups**: Safeguards Pangolin SQLite databases (`pangolin.db`) using zero-lock hot backup (`sqlite3 .backup`) before any file changes or updates. +- **Visual File Editor**: In-browser configuration editor for `docker-compose.yml`, `config.yml`, and `.env` with automatic timestamped `.bak` backups upon saving. + +### 2. Debian VPS System Maintenance & Package Updates +- **Real-Time Host Metrics**: Live CPU utilization (per-core breakdown, load average), RAM usage (used, buffers, free), root disk & local Unraid backup disk meters. +- **Automated APT Upgrade Management**: Scans for upgradable packages, distinguishes security patches, and streams real-time `apt-get upgrade` output. +- **Kernel Reboot Detection**: Identifies whether `/var/run/reboot-required` has been triggered by kernel or glibc updates with one-click safe system reboot. + +### 3. Multi-Scope Backup & Disaster Recovery Engine +- **Backup Scopes**: + - `Pangolin Stack`: Hot SQLite DB snapshot, compose stack, `config.yml`, `.env`, and Traefik SSL certificates. + - `Host VPS Configuration`: `/etc/ufw`, network interfaces, hosts, cron schedules, and systemd units. + - `Full Disaster Recovery`: Bundles both Pangolin and host system into a unified `.tar.gz` recovery snapshot. +- **Integrity Verification**: Automatic SHA-256 calculation and on-demand `tar` verification. +- **In-Browser File Explorer**: Preview and inspect the contents of backup archives without extracting them. +- **One-Click Restore with Rollback Protection**: Automatically stages restore and restarts containers on the VPS. +- **Direct Download & Upload**: Download archives to your local PC or upload an archive from another VPS to migrate. +- **Automated Retention Pruning**: Configurable retention limits to auto-prune older backups and protect disk space. + +### 4. Scheduling & Multi-Channel Alerting +- **Cron Scheduler**: Background automated backups (e.g. daily at 3:00 AM UTC). +- **Webhooks**: Integrations for **Discord** (rich embeds), **Telegram** (bot messages), and **Generic JSON Webhooks** for n8n/Home Assistant. +- **Test Ping**: Built-in test button to verify webhook credentials. + +### 5. Live Console & Job History +- **Real-Time Terminal Streaming**: WebSocket-powered live output streaming with auto-scroll and ANSI color rendering. +- **Historical Log Viewer**: Access detailed execution logs for all past update, backup, and restore jobs. + +--- + +## 🐳 Docker Deployment + +Pangolin Sentinel is containerized and ready to run on Unraid, Docker Compose, or standalone Docker. + +### 1. Using Docker Compose (Recommended) + +Clone the repository and run: + +```bash +docker compose up -d --build +``` + +Example `docker-compose.yml`: + +```yaml +services: + pangolin-sentinel: + image: pangolin-sentinel:latest + build: . + container_name: pangolin-sentinel + restart: unless-stopped + ports: + - "8888:8888" + volumes: + # Persistent app data (settings, SSH keys, job history, backup index) + - ./data:/data + # Local storage destination for backup archives + - ./backups:/backups + environment: + - TZ=America/New_York + - PORT=8888 + - HOST=0.0.0.0 + - DATA_DIR=/data + - BACKUP_DIR=/backups + # Optional: set PUID/PGID for host user permissions (e.g. 99:100 on Unraid) + # - PUID=99 + # - PGID=100 +``` + +### 2. Using Standalone `docker run` + +```bash +docker run -d \ + --name pangolin-sentinel \ + --restart unless-stopped \ + -p 8888:8888 \ + -v /mnt/user/appdata/pangolin-sentinel:/data \ + -v /mnt/user/backups/pangolin:/backups \ + -e TZ=UTC \ + -e PUID=99 \ + -e PGID=100 \ + pangolin-sentinel:latest +``` + +### 3. Deploying on Unraid + +1. **Volume Mappings**: + - `/data` ➔ `/mnt/user/appdata/pangolin-sentinel` (Persistent settings, SSH keys, job history) + - `/backups` ➔ `/mnt/user/backups/pangolin` (Where backup archives pulled from VPS are stored on your array) +2. **Port**: `8888` (Web UI) +3. **App Icon & Template**: + - A ready-to-use template is available at [`pangolin-sentinel-unraid.xml`](pangolin-sentinel-unraid.xml). + - Copy this file into `/boot/config/plugins/dockerMan/templates-user/my-PangolinSentinel.xml` on your Unraid flash drive. + - The template references the custom high-visibility app icon served directly by the container (`/assets/icon.png`) or hosted remotely via GitHub. + +--- + +## ⚙️ Environment Variables + +| Variable | Default | Description | +|---|---|---| +| `PORT` | `8888` | Port for web dashboard and API | +| `HOST` | `0.0.0.0` | Listen host | +| `DATA_DIR` | `/data` | Directory where `settings.json`, SSH keys, and catalog are saved | +| `BACKUP_DIR` | `/backups` | Directory where pulled VPS backup `.tar.gz` archives are saved | +| `PUID` | `0` (root) | Optional user ID to run as (set `99` for Unraid nobody) | +| `PGID` | `0` (root) | Optional group ID to run as (set `100` for Unraid users) | +| `TZ` | `UTC` | Timezone for scheduler and timestamps | + +--- + +## 🚀 Initial Setup + +1. Open `http://:8888` in your browser. +2. Enter your desired master administrator password to initialize the dashboard. +3. In **Settings**: + - Enter your Pangolin VPS IP / Hostname and SSH port. + - Choose **SSH Key Pair** (recommended) and copy the generated public key to your VPS: + ```bash + echo "" >> ~/.ssh/authorized_keys + ``` + - Alternatively, enter your VPS SSH password. +4. Click **Test Connection** to verify end-to-end communication, Docker stack detection, and database status.