Pangolin Sentinel

Unraid & Docker VPS Update & Hot-Backup Hub

---

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:

docker compose up -d --build

Example docker-compose.yml:

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

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.
   • 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:

     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.