2f0d93a0ae
apiscp-borg is a sibling of apiscp-kopia built on BorgBackup. This first milestone lands the project scaffold and the Layer 1 engine: - borg-apiscp-backup: per-site named archives (siteN-shadow/info/db), fresh per-site DB dumps via ApisCP site-context export, system + custom archives, borg prune retention per prefix, Prometheus metrics, email notifications. - apiscp-borg-common.sh: logging, mail, site/owner helpers. - config example, systemd service+timer, install.sh, README, DESIGN. Borg preserves POSIX ACLs and xattrs natively, so (unlike the kopia engine) no metadata sidecar is required; DESIGN.md records how Borg reshapes the design. Repository/restore tools, Layer 2 panel integration, hooks, uninstall, and the full reference are the next milestones.
53 lines
2.2 KiB
Markdown
53 lines
2.2 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.
|
|
|
|
## License
|
|
|
|
MIT. See `LICENSE`.
|