---
**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://
