Restore comprehensive README with app icon and Docker guide
This commit is contained in:
jschantli committed
1 parent
b4095b82ea
commit
7c665cac33
1 file changed
+146
-1
@@ -1,2 +1,147 @@
|
|||||||
# PangolinSentinel
|
<div align="center">
|
||||||
|
<img src="icon.png" width="130" height="130" alt="Pangolin Sentinel Logo" style="border-radius: 24px; box-shadow: 0 12px 28px rgba(0,0,0,0.5);">
|
||||||
|
<h1>Pangolin Sentinel</h1>
|
||||||
|
<p><strong>Unraid & Docker VPS Update & Hot-Backup Hub</strong></p>
|
||||||
|
<p>
|
||||||
|
<img src="https://img.shields.io/badge/Docker-Ready-2496ED?style=flat-square&logo=docker&logoColor=white" alt="Docker">
|
||||||
|
<img src="https://img.shields.io/badge/Unraid-Compatible-F15A24?style=flat-square&logo=unraid&logoColor=white" alt="Unraid">
|
||||||
|
<img src="https://img.shields.io/badge/FastAPI-2.0-009688?style=flat-square&logo=fastapi&logoColor=white" alt="FastAPI">
|
||||||
|
<img src="https://img.shields.io/badge/Vue.js-3-4FC08D?style=flat-square&logo=vuedotjs&logoColor=white" alt="Vue 3">
|
||||||
|
<img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License">
|
||||||
|
</p>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**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://<YOUR_UNRAID_OR_SERVER_IP>: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 "<sentinel-public-key>" >> ~/.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.
|
||||||
Reference in new issue
Block a user