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)
• 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
• 14 CLI commands — backup, restore, status, health, snapshots, prune, logs, config, cache, restic passthrough
• 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

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.vineethnk.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 14 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

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

MIT