## 🚀 HELBACKUP v1.2.0

---

### 📦 AppData — Dynamic Container Mode

- **Mode toggle** in the AppData step: `Manual` / `All (dynamic)`
- **All (dynamic)** automatically backs up all Docker containers, including those added after job configuration — no manual adjustments required
- **Exclusion list:** permanently exclude specific containers via a chip-based UI with dropdown selection
- **Priority order:** optional list of containers to stop first; remaining containers follow in alphabetical order
- **All / None selection:** quickly select or deselect all containers in manual mode

**New config fields:**
- `allContainersDynamic`
- `excludedContainers`
- `stopOrderPriority`

> Runtime container resolution via Docker socket — no schema migration required.
> `useDatabaseDumps` is fully compatible with dynamic mode.
> Backward compatible: existing jobs behave unchanged when `allContainersDynamic` is `false` or absent.

---

### 🔐 Security

- **Stronger recovery keys:** entropy increased from 32 → 128 bits
- New format: `HLBK-ENC-XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX`
- Existing keys remain valid
- **Sanitized SSH errors:** IPs, usernames, and key paths removed from API responses; full details remain in internal logs
- **Credential leak fix:** self-export staging now uses UUID directories; `try/finally` guarantees cleanup of sensitive data

---

### 🐛 Bug Fixes

- **Cron validation:** invalid expressions now rejected with `400 Bad Request`
- **Manifest atomicity:** partial manifests are cleaned up if the DB write fails
- **NAS transfer handling:**
- Local staging preserved after checksum failure (enables retry)
- Remote `.partial` directories cleaned on failure
- **Manifest timeout:** `createJobManifest()` capped at 10 minutes
- **rsync abort fix:** proper process registration ensures clean aborts
- **MongoDB temp cleanup:** `/tmp/mongodump` removed after extraction (best effort)
- **Retention policy:** now applies to failed jobs, preventing disk exhaustion
- **Docker shutdown:** Dockerode pool gracefully closed before app shutdown
- **Disk warnings:** empty catch replaced with `logger.debug()`
- **Target validation:**
- NAS requires: `host`, `username`, `path`
- Local requires: `path`
- Invalid configs rejected with `400 Bad Request`

---

### ✨ New Features

- **Dry-run mode:** execute jobs with `dryRun: true`; `rsync` runs with `--dry-run`; VM & Docker image steps are skipped
- **Bandwidth limiting:** per-job `bwlimitKb` option (mapped to `rsync --bwlimit`)
- **Webhook retries:** exponential backoff (30 s / 5 min / 30 min); retry scheduler runs every 5 minutes
- **Audit log:** tracks all mutating API requests (`POST`, `PUT`, `DELETE`); includes actor (JWT), resource, action, and HTTP status; accessible via `GET /api/audit-log`
- **Manifest filtering:** `GET /api/v1/backups?jobId=X`
- **Cross-tab logout:** logging out in one tab invalidates all sessions

---

### 🎨 UI / UX

- **Skeleton loaders:** replaced spinners with animated placeholders
- **Toast duration:**
- Errors: 10 s
- Others: 5 s
- Custom duration supported: `toast('msg', 'error', 15000)`
- **Polling improvements:**
- Dashboard: 30 s → 15 s
- Jobs page: 10 s polling when active jobs exist
- **i18n fixes:** added missing translations for the log page (DE / EN)

---

### 🛠️ Internal

- **Manifest versioning:** introduced `schemaVersion: 1`
- **Docker exec refactor:** extracted duplicated logic into internal helpers

---

---

## 🚀 HELBACKUP — v1.1.0

---

### ⚠️ BREAKING: Update Required Mounts

Before updating, the following volume mounts **must** be set — **read-write (rw), not read-only!**

```yaml
volumes:
- /mnt/cache:/unraid/cache:rw
- /mnt/user:/unraid/user:rw
- /boot:/unraid/boot:rw
- /etc/libvirt:/unraid/libvirt:rw
- /var/run/docker.sock:/var/run/docker.sock
```

```The UNRAID Community Store template has been adjusted accordingly.```

> If mounts are missing, a persistent warning banner will appear on the login page and main layout showing the exact missing paths.

---

### ✨ New Features

**🗂️ Settings: Tab Layout** — Page split into four sections: Appearance, Notifications, Backup, System

**📺 Scanline Effect Toggle** — Can be disabled under Settings → Appearance

**📁 Custom Backup Paths** — Global source paths for Appdata, Flash and VMs configurable centrally under Settings → Backup; no longer set per job. Defaults: `/unraid/cache/appdata`, `/unraid/boot`, `/unraid/cache/domains`

**🔍 Directory Browser** — Built-in file browser for selecting mounted folders (no manual typing required)

**📶 Rsync Bandwidth Limit** — Configurable globally under Settings → Backup (KB/s, 0 = no limit)

**🔄 Restore Uses Configured Paths** — Flash, Appdata and VM restore use the source paths configured under Settings → Backup as the restore target

**🗄️ Database Dumps: Credentials from Container Environment**
Credentials are read automatically from container environment variables — no manual configuration needed:
- **MySQL/MariaDB** — `MYSQL_ROOT_PASSWORD` (all databases) or fallback to `MYSQL_USER` + `MYSQL_PASSWORD` + `MYSQL_DATABASE` (single app DB)
- **PostgreSQL** — `POSTGRES_USER` (fallback: `postgres`)
- **MongoDB** — `MONGO_INITDB_ROOT_USERNAME` + `MONGO_INITDB_ROOT_PASSWORD`
- **Redis** — `REDIS_PASSWORD` / `REQUIREPASS`

**🔴 Redis Dump Implemented** — Full RDB backup via `BGSAVE` + Docker Archive API; waits for save completion via `LASTSAVE` polling before extracting the file

**📦 Tar Mode Appdata Restore** — The restore wizard now supports backups created in tar mode (previously rsync mode only)

**🔐 Encrypted Appdata Restore** — Tar backups with encryption (`.tar.gz.gpg`) are automatically decrypted before restore

---

### 🐛 Bug Fixes

**🔢 Version Display** — UI now shows the correct version from the backend (no more hardcoded v0.1.0)

**⚙️ Release Workflow** — `frontend/package.json` is now automatically updated with the new version on release

**▶️ Container Restart After Backup** — Containers that were already stopped before the backup started are no longer restarted afterwards

**⛔ Cancel Running Job** — Running jobs can be stopped via a red "Cancel" button in the history view; status is saved as `cancelled`. Active rsync/tar processes are immediately terminated via SIGTERM; partial backup directories are automatically cleaned up

**🗄️ Database Dumps (`spawn docker ENOENT`)** — Database dumps no longer fail when no `docker` binary is present in the container; execution now runs entirely via the Docker socket

**📂 Appdata: Only Selected Containers Are Backed Up** — Previously the entire appdata folder was backed up despite container selection; now only the directories of selected containers are copied

**🔎 Appdata Path Resolution via Docker API** — Actual bind mount paths are resolved via `docker inspect`; containers with a custom appdata directory name (e.g. `my-jellyfin-config` instead of `jellyfin`) are correctly detected. Falls back to configured source path if no matching mounts are found

**🏷️ Appdata Subdirectories Prefixed with Container Name** — Backup directories are now created as `<containername>/<mount>/`; prevents collisions when multiple containers share the same mount basename (e.g. multiple `data/` folders)

**🐘 PostgreSQL Restore** — Required directories such as `pg_notify`, `pg_commit_ts`, `pg_logical` etc. are automatically recreated after restore if they were empty in the backup; supports Alpine and Debian-based images (scans up to 4 levels deep)

**📊 Dashboard Load Time** — Replaced `du -sb` with `df -B1`; Dashboard API now responds in milliseconds instead of ~48 seconds on large backup directories

**🔐 Appdata Encryption (Tar Mode)** — Hardcoded filename `appdata.tar.gz` replaced with dynamic detection of all `.tar.gz` files; `containers.json` is now correctly saved in an encrypted `_metadata.tar.gz.gpg`

**🔐 Custom Backup Encryption** — Unencrypted source files are now correctly removed from the working directory after encryption (previously transferred alongside the `.gpg` file)

**🔒 Security: Path Validation on Delete** — Backup paths from the database are validated against a whitelist of allowed base paths before `rm -rf` is executed

**🔄 Retention: FUSE-Safe Deletion** — Old backups are now deleted via `rm -rf` during retention cleanup instead of `fs.rm` — reliable on Unraid FUSE/shfs mounts

**📡 NAS Transfer: Cleanup on Failure** — Local staging directory is now always cleaned up even when rsync to NAS fails

**⛔ Abort Skips Retry Delay** — A cancelled job no longer waits out configured retry intervals

**🔁 Appdata Multi-Mount Error Handling** — If one mount fails for a container, remaining containers are still backed up; errors are collected and reported at the end

**🗺️ Restore Plan: Tar Backups Detected** — The restore wizard now correctly identifies which containers are included in a tar mode backup

---

---

---

# 🎉 HELBACKUP v1.0.0 — First Stable Release

> After extensive testing and refinement, HELBACKUP is ready for production.
> Thank you for being part of the journey from the very first commit. 🙏

---

## ✨ What is HELBACKUP?

A self-hosted, intelligent backup orchestrator built specifically for **Unraid**.
One Docker container. Full control. No cloud. No subscription.

---

## 🚀 Core Features

### 🗂️ Backup Types
- **Flash Drive** — Incremental rsync with SHA-256 verification
- **Appdata** — Optional container stop/start, Docker config export
- **Virtual Machines** — Libvirt snapshot, vDisk rsync, XML export
- **Docker Images** — Save as `.tar` via Docker API
- **System Config** — Network, users, shares, plugins, disk assignments

### 🎯 Backup Targets
- **Remote NAS / Server** — SSH + Rsync with optional strict host-key pinning
- **Local Filesystem** — Direct path on the Unraid array

### 🔒 Security & Encryption
- AES-256 end-to-end encryption with GPG
- SSH key support with permission validation (0600 enforced)
- JWT-based authentication with configurable entropy enforcement
- API token system with scoped access and expiry
- All credentials sanitized from API responses

### ♻️ Retention
- **Simple retention** — Keep last N backups
- **GFS (Grandfather-Father-Son)** — Daily / Weekly / Monthly rotation, saves up to 90% storage

### 💡 Smart Job Engine
- Visual dependency graph with drag-and-drop step ordering
- Sequential execution with configurable retry (linear / exponential backoff)
- `catch_up_on_start` — runs missed schedules after container restart
- Pre- and post-backup hook scripts
- Per-step `stop_on_error` control
- Atomic publish: all steps write to `.partial/`, finalize via rename

### 🌐 NAS Power Management
- Wake-on-LAN before backup
- Automatic graceful shutdown after job completes (optional)
- Health check with 60s retry window

### 🔔 Notifications — 7 Channels
Email · Gotify · ntfy · Pushover · Telegram · Discord · Slack

### 🪝 Webhooks & API
- HMAC-signed webhook events
- Full REST API with token-based auth
- Prometheus metrics endpoint

### 🩺 Disaster Recovery
- Recovery Mode — browse and restore from any backup
- Granular file restore
- Full server restore wizard
- Self-backup job (helbackup config included in backups, GPG-encrypted)

---

## 🖥️ Dashboard

- System status with intelligent failure detection
- Warning only shown when a job is **currently** in failed state (not historical)
- Per-target storage card with **cached SSH disk usage**
- Disk info fetched at job start (NAS guaranteed online), stored in DB — no live SSH on page load
- Manifest-derived backup volume shown for all target types
- 30-day backup history chart
- 30-day success rate
- Recent jobs list

---

## 🌍 Internationalization

Full UI in **German** (default) and **English**
All status messages, warnings, and system strings properly localized.

---

## 🛠️ Stack

| Layer | Tech |
|---|---|
| Runtime | Node.js 24 LTS, TypeScript strict |
| Frontend | React 18, Vite 5, Zustand, Tailwind CSS |
| Backend | Fastify 5 |
| Database | SQLite (better-sqlite3, WAL mode) |
| Scheduler | node-schedule (cron) |
| SSH / Transfer | ssh2, rsync |

---

## 📦 Installation

**Unraid Community Apps** — search for `HELBACKUP`

**Docker Compose:**
```yaml
services:
helbackup:
image: ghcr.io/kreuzbube88/helbackup:latest
container_name: helbackup
restart: unless-stopped
ports:
- "3000:3000"
environment:
- JWT_SECRET=your_secret_here # openssl rand -hex 32
- TZ=Europe/Berlin
volumes:
- /mnt/user/appdata/helbackup/config:/app/config
- /mnt/user/appdata/helbackup/data:/app/data
- /mnt/user/appdata/helbackup/logs:/app/logs
- /var/run/docker.sock:/var/run/docker.sock
- /boot:/unraid/boot
- /mnt/user:/unraid/user

---
⚠️ A backup is only as good as the restore

Before you need it in an emergency — test it.

1. Run a job → let it complete
2. Open Recovery → verify the backup
3. Follow the docs/en/05-recovery/disaster-recovery-day-zero.md on a test machine

---
Built with ❤️ for the Unraid community — MIT License © HEL*Apps
```

Edited April 20Apr 20 by Kreuzbube88

< reserved >

< reserved >

Danke für deine Arbeit. Ich habe es getestet. Leider gibt es keie Möglichkeit Ordner in appdata Verzeichnis und auch externe Ordner ausserhalb appdata auszuschließen (z.B. Plex Cache wie bei dem plugin backup/restore appdata oder habe ich was übersehen?

Beste Grüße

On 4/11/2026 at 7:55 PM, dibux said:

Danke für deine Arbeit. Ich habe es getestet. Leider gibt es keie Möglichkeit Ordner in appdata Verzeichnis und auch externe Ordner ausserhalb appdata auszuschließen (z.B. Plex Cache wie bei dem plugin backup/restore appdata oder habe ich was übersehen?

Beste Grüße

Der ausschluss von Ordner innerhalb Appdata ist mittlerweile realisiert, es werden nur doch die Ordner in Appdata gesichert die zu Docker Containern gehören.

Ein Ausschluss von Unterordner innerhalb der Docker Ordner ist nicht vorgesehen.

Danke für deine Rückmeldung. Leider reicht mir das nicht. Ich habe Docker die auch etwas von ausserhalb von appdata gesichert werden sollen und Docker die innerhalb appdata nicht alle Ordner gesichert bekommen. Das ist mir hier zu unflexibel. Ich wünsche mir das ich jeden Docker mit seinen Pfaden angezeigt bekomme und selbst entscheiden kann welcher Pfad (auch innerhalb appdata (z.B. Plex)) gesichert werden soll.

Das ist mir dann doch zu unfelxibel und zu sehr von dem bestimmt, was du als deine Lösung bestimmst. Aber danke für deine Arbeit.

Beste Grüße

Edited April 20Apr 20 by dibux

9 minutes ago, dibux said:

Ich habe Docker die auch etwas von ausserhalb von appdata gesichert werden sollen und Docker die innerhalb appdata nicht alle Ordner gesichert bekommen.

Nicht nur du, es gibt zahlreiche weitere. Ein Beispiel Plugin hattest du bereits genannt.

Deshalb würde ich mir auch mehr Flexibilität wünschen ähnlich wie es die etablieteren schon bieten die man für Appdata, Docker, VMs, Flash/Boot nutzen kann.

Ihr habt beide eine PN von mir bekommen :)

Inspirationen von u. a.:

Einmal das schon erwähnte Plugin: https://forums.unraid.net/topic/137710-plugin-appdatabackup/

Für VMs: https://forums.unraid.net/topic/86303-vm-backup-plugin/ + https://forums.unraid.net/topic/197218-vm-backup-restore-for-unraid/

Für Flash: https://forums.unraid.net/topic/100202-latest-super-easy-method-for-automated-flash-zip-backup/

Ein anderes Multi Backup Tool: https://forums.unraid.net/topic/193147-support-stephondoestech-unraidconfigguardian/

Edited April 25Apr 25 by Revan335