vineethnkrishnan/backupctl
Multi-DB backup orchestration: Restic + GPG, scheduled, encrypted, audited. One YAML.
Image
Security
Developer tools
Databases & storage
0
2.2K
vineethnkrishnan/backupctl repository overview
backupctl
Backup orchestration for databases, files, or both. One config, zero babysitting.
backupctl is a standalone Docker service that orchestrates scheduled backups for multiple projects — databases (PostgreSQL, MySQL, MongoDB), files, or both — with encrypted remote storage via restic, configurable notifications, and a full CLI for day-to-day operations.
Highlights
- Multi-project — single service manages dozens of projects from one YAML config
- Flexible scope — back up databases, files, or both per project; PostgreSQL, MySQL, MongoDB out of the box
- Restic + Hetzner Storage Box — encrypted, deduplicated backups over SFTP
- GPG encryption — optional per-project dump encryption before upload
- Notifications — Slack, Email (SMTP/TLS), Webhook (JSON + markdown)
- Uptime Kuma monitoring — optional heartbeat push monitors for passive failure detection
- Pre/post hooks — run arbitrary shell commands around each backup
- Retry with backoff — configurable exponential retry for transient failures
- Audit trail — every run tracked in PostgreSQL with real-time stage progress
- Crash recovery — orphan detection, lock cleanup, fallback replay on startup
- 15 CLI commands — backup, restore, status, health, snapshots, prune, logs, config, cache, restic passthrough, upgrade
- Dry run — validates config, adapters, connectivity, disk, and GPG before a real run
- Zero-edit install — interactive wizard generates
.env, SSH keys, and project config
Quick Start
# One-line install (pulls pre-built image)
curl -fsSL https://raw.githubusercontent.com/vineethkrishnan/backupctl/main/scripts/get-backupctl.sh | bash
# Or from source
git clone https://github.com/vineethkrishnan/backupctl.git && cd backupctl
./scripts/install.sh
# Verify
docker exec backupctl node dist/cli.js health
# Run first backup
docker exec backupctl node dist/cli.js run myproject --dry-run
docker exec backupctl node dist/cli.js run myproject
# Docker Hub
docker pull vineethnkrishnan/backupctl:latest
# GitHub Container Registry
docker pull ghcr.io/vineethkrishnan/backupctl:latest
CLI at a Glance
backupctl run <project> [--dry-run] # trigger or simulate backup
backupctl run --all # back up all projects
backupctl status [project] # backup status
backupctl health # audit DB, restic, disk, SSH
backupctl restore <proj> <snap> <path> # restore from snapshot
backupctl snapshots <project> # list restic snapshots
backupctl prune <project> | --all # remove old snapshots
backupctl logs <project> [--failed] # query audit log
backupctl config validate|show|reload # config management
backupctl cache <project> [--clear] # restic cache management
backupctl restic <project> <cmd> # restic passthrough
backupctl upgrade # check for updates
Inside Docker: docker exec backupctl node dist/cli.js <command>
Architecture
Hexagonal (Ports & Adapters) with strict layer separation.
┌──────────────────────────────────────┐
│ Infrastructure │
│ CLI · HTTP · Scheduler (driving) │
│ │ │
│ ┌──────────┴───────────┐ │
│ │ Application Layer │ │
│ │ Orchestrator·Registry │ │
│ └──────────┬───────────┘ │
│ │ │
│ ┌──────────┴───────────┐ │
│ │ Domain Layer │ │
│ │ Ports·Models·Policies │ │
│ └──────────┬───────────┘ │
│ │ │
│ Adapters (driven) │
│ Dumpers·Restic·Notifiers·GPG·Audit │
└──────────────────────────────────────┘
infrastructure/ → application/ → domain/ — never the reverse.
Documentation
backupctl.vinelab.in — full documentation site.
Also available in docs/:
| # | Document | What's inside |
|---|---|---|
| 1 | Introduction | Features, design goals, tech stack |
| 2 | Architecture | Hexagonal design, layers, naming, project structure |
| 3 | Requirements | PRD summary, goals, non-goals, audit schema |
| 4 | Installation | Prerequisites, wizard, manual setup, Docker |
| 5 | Configuration | .env reference, projects.yml schema, resolution rules |
| 6 | CLI Reference | All 15 commands with syntax, options, exit codes, examples |
| 7 | Bash Scripts | install.sh, dev.sh, backupctl-manage.sh |
| 8 | Backup Flow | 11-step flow, retry, concurrency, recovery, notifications |
| 9 | Restore Guide | Per-DB restore, decrypt, decompress, --guide |
| 10 | Cheatsheet | Daily ops quick reference, one-liners |
| 11 | Adding Adapters | Extending with new DB engines, notifiers, storage backends |
| 12 | Troubleshooting | Common issues, debug commands, log locations |
| 16 | Monitoring | Uptime Kuma push monitors, setup, heartbeat details |
| 18 | Storage Backend Drill | End-to-end backup + restore walkthrough proving a backend works |
Tech Stack
| Component | Technology |
|---|---|
| Runtime | Node.js 20 LTS |
| Framework | NestJS 11 |
| CLI | nest-commander |
| ORM | TypeORM (explicit migrations) |
| Audit DB | PostgreSQL 16 |
| Scheduler | @nestjs/schedule |
| Logging | Winston + daily rotation |
| Containers | Docker + Docker Compose |
| Remote storage | Restic → Hetzner Storage Box (SFTP) |
| Encryption | GPG |
| Testing | Jest (342 tests) |
Contributing
npm install # install deps
npm run start:dev # dev server (watch)
npm test # run tests
npm run lint # lint
npm run build # production build
See Adding Adapters for extending the system.
License
Tag summary
Content type
Image
Digest
sha256:377627298…
Size
214.6 MB
Last updated
3 days ago
docker pull vineethnkrishnan/backupctl