Laurence Horrocks-Barlow b9e8694c61 fix(engine)+docs: env overrides config for targeted runs; add full REFERENCE.md

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

2026-07-24 23:38:08 +01:00

2.5 KiB

Raw Blame History

apiscp-borg

A BorgBackup backup engine for ApisCP, plus native panel/CLI integration, packaged so it survives ApisCP upgrades. Sibling project to 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.

2.5 KiB Raw Blame History