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