backupctl Documentation
April 19, 2026 · View on GitHub
backupctl is a backup orchestration service for databases, files, or both — managing scheduled, encrypted, deduplicated backups for multiple projects from a single Docker container. Built with NestJS 11 and hexagonal architecture, it supports PostgreSQL, MySQL, and MongoDB databases plus arbitrary file/asset directories — with restic remote storage, GPG encryption, audit logging, crash recovery, and a full CLI.
Documentation
| # | Page | Description |
|---|---|---|
| 1 | Introduction | What backupctl is, key features, design goals, tech stack |
| 2 | Architecture | Hexagonal design, layer rules, domain subdomains, dependency injection |
| 3 | Requirements | PRD summary — goals, non-goals, functional requirements, audit schema |
| 4 | Installation | Setup wizard, Docker deployment, first-run verification |
| 5 | Configuration | Project YAML format, .env globals, config resolution, examples |
| 6 | CLI Reference | All 14 commands with flags, arguments, exit codes, and examples |
| 7 | Bash Scripts | Host-side scripts: install.sh, dev.sh, backupctl-manage.sh |
| 8 | Backup Flow | The 13-step orchestration pipeline in detail |
| 9 | Restore Guide | Snapshot browsing, file restore, database import, --guide mode |
| 10 | Cheatsheet | Quick-reference commands for daily operations |
| 11 | Adding Adapters | How to add new database dumpers, notifiers, or storage backends |
| 12 | Troubleshooting | Common errors, diagnostics, recovery procedures |
| 13 | Development | Docker dev environment, networking, socat relay, testing, static analysis |
| 14 | Migrations | TypeORM migration commands, patterns, and troubleshooting |
| 15 | FAQ | Setup issues, Docker networking, ISP port blocking, SSH/GPG/restic fixes |
| 16 | Monitoring | Uptime Kuma push monitors for passive failure detection |
| 17 | Network | Docker network management, Docker socket setup, multi-arch image support |
| — | Help Center | Step-by-step runbooks for recurring production issues |
Quick Links
- First-time production setup — Installation + FAQ
- Development setup — Development Guide (Docker, networking, socat relay, testing)
- Docker networking — Network (Docker socket, multi-arch images, connect command)
- Configure a project — Configuration (YAML format, docker_network, all fields)
- Run a backup — CLI Reference →
run - Restore from snapshot — Restore Guide
- Daily commands — Cheatsheet
- Host scripts — Bash Scripts (
dev.sh,install.sh,backupctl-manage.sh) - Database migrations — TypeORM migration guide
Getting Help
If something isn't working, start with the Troubleshooting guide. It covers common errors, diagnostic commands, and recovery procedures for lock files, audit DB connectivity, restic repos, and more.
For recurring production issues with step-by-step runbooks — including diagnosis, short-term workaround, and permanent fix — see the Help Center.
If you've checked the troubleshooting guide and FAQ and still need help:
- Report an Issue — Bug reports, feature requests, or documentation improvements
- View Existing Issues — Check if someone else has reported the same problem