b9e8694c61
- Engine: same targeted-run fix as apiscp-kopia (env BACKUP_SITES/SYSTEM/PATHS/ DATABASES now override the sourced config, so `run --site` scopes correctly instead of backing up every site). - docs/REFERENCE.md: exhaustive reference (every command, verb, config key, installer, automation, both GUIs, security model, recovery), plus a README Documentation section.
60 lines
2.5 KiB
Markdown
60 lines
2.5 KiB
Markdown
# apiscp-borg
|
|
|
|
A [BorgBackup](https://www.borgbackup.org/) backup engine for
|
|
[ApisCP](https://apiscp.com), plus native panel/CLI integration, packaged so it
|
|
survives ApisCP upgrades. Sibling project to
|
|
[apiscp-kopia](https://git.discworld.casa/laurence/apiscp-kopia): same
|
|
architecture, different backend.
|
|
|
|
## Why Borg, and why a plugin
|
|
|
|
Borg is a fast, deduplicating, compressing, encrypted backup tool. Unlike kopia,
|
|
**Borg preserves POSIX ACLs and extended attributes natively**, which is exactly
|
|
the metadata ApisCP encodes account permissions in. So a plugin is not needed to
|
|
work around lost metadata (the reason apiscp-kopia exists). The value here is:
|
|
|
|
- runs ApisCP's `backup_dbs.php` before archiving, so per-site database dumps
|
|
are current instead of a day stale;
|
|
- archives each site as its own named set (`siteN-shadow-...`, `siteN-db-...`),
|
|
enabling single-site restore and per-site retention;
|
|
- captures per-site databases through ApisCP's site-context export (a host-level
|
|
dump cannot see them);
|
|
- wires retention (`borg prune`), maintenance (`borg compact`), integrity
|
|
(`borg check`), scheduling, email notifications, one-time key backup, and both
|
|
an appliance-admin and a site-owner GUI into ApisCP.
|
|
|
|
See `docs/DESIGN.md` for how Borg changes the design relative to apiscp-kopia.
|
|
|
|
## Architecture
|
|
|
|
Two decoupled layers, both upgrade-safe:
|
|
|
|
- **Layer 1: the engine.** A standalone POSIX-sh program on a systemd timer,
|
|
with no coupling to ApisCP's PHP internals. `bin/borg-apiscp-backup` plus
|
|
`borg-apiscp-repo` and `borg-apiscp-restore`.
|
|
- **Layer 2: native integration.** An ApisCP module, GUI apps, and account hooks
|
|
under `/usr/local/apnscp/config/custom`, which survive `upcp`.
|
|
|
|
## Requirements
|
|
|
|
- ApisCP (any recent release)
|
|
- `borgbackup` (`borg`) 1.2+ on the host (and on the remote for ssh backends)
|
|
- a filesystem that carries ACLs and xattrs (default on ext4/xfs/btrfs)
|
|
|
|
## Status
|
|
|
|
Early scaffold. The Layer 1 engine is the first milestone; the repository and
|
|
restore tools, Layer 2 panel integration (module + two GUIs + hooks), install /
|
|
uninstall, and full reference documentation are being built out to track the
|
|
apiscp-kopia feature set. Not yet ready for production use.
|
|
|
|
## Documentation
|
|
|
|
- `docs/REFERENCE.md`: exhaustive reference for every command, verb,
|
|
configuration key, installer, and automation shipped in this repository.
|
|
- `docs/DESIGN.md`: design rationale, and how Borg's native ACL/xattr
|
|
handling changes the approach taken relative to apiscp-kopia.
|
|
|
|
## License
|
|
|
|
MIT. See `LICENSE`.
|