Backups and History

CaptainCore keeps four separate kinds of history per site environment: Restic backups of files and database, git-based quicksaves of the plugin and theme tree, zipped snapshots for download, and visual captures of rendered pages. Update logs tie a pair of quicksaves together to describe what an update run changed.

Storage layout

Backups are written with Restic through an Rclone backend. The repository path for a site environment is:

rclone:<rclone_backup>/<site>_<site_id>/<environment>/restic-repo

Quicksaves use a sibling repo at quicksave-repo, and archived server logs land in a logs folder next to them. The Restic password comes from ~/.captaincore/data/restic.key. Long-running repo operations set TMPDIR from the system path_tmp value, because repacking a large repo needs hundreds of gigabytes of scratch space.

Restic is invoked with an explicit rclone serve line so B2 deletes are hard deletes and the timeouts are generous:

restic ... -o "rclone.args=serve restic --stdio --b2-hard-delete --timeout=300s --contimeout=60s" -o rclone.timeout=600s

Remotes read from config.json

The system block supplies paths and default remotes; the per-captain block can override them.

The captain remotes.rclone_backup wins over the system rclone_backup. In fleet mode the captain ID is appended to the backup remote and to the local site path, so tenants never share a repo.

The excludes files

Two exclusion lists ship in lib/.

• lib/excludes is passed to rclone sync as --exclude-from when files are pulled down from the site. It skips error_log, /tmp, .DS_Store, node_modules/, the local database-backup.sql, and the backup and cache directories of the common backup plugins: UpdraftPlus, All-in-One WP Migration, Duplicator, BackWPup, BackupBuddy, Akeeba, Envato, Divi’s et-cache and et_temp, WP Super Cache and friends.
• lib/restic-excludes is passed to restic backup as --exclude-file. It covers the same plugin backup and cache directories, plus debug.log, error_log and phperror_log.

backup

captaincore backup <subcommand> <site>

Everyday use

backup generate defaults to -p, --parallel 3. --skip-if-recent=24h skips an environment backed up within that window, which is what makes a nightly @all run cheap to re-run.

captaincore backup generate @all --parallel=5 --skip-if-recent=20h

--payload on backup download names a token identifying which files and directories to include. The captaincore server writes large payload blobs to ~/.captaincore/data/payload/<token>.txt and passes the token on the command line rather than the blob.

Repository maintenance

backup migrate-v2 is the orchestrated version-1 to version-2 migration: it checks whether the repo is already v2, runs restic migrate upgrade_repo_v2, repacks uncompressed data with restic prune --repack-uncompressed, clears the remote Restic cache over SSH, then verifies the final state.

backup key-backup copies the Restic repo key out of B2 to a local backup-repo-key.txt (or quicksave-repo-key.txt) so a B2 data loss does not cost you the repo. key-restore puts it back.

backup forget and backup storage-cleanup preview by default; --confirm is required to actually delete.

captaincore backup check mysite-production --read-data

quicksave

Quicksaves are per-site git repositories tracking plugin, theme and configuration changes, with the git repo itself backed up into Restic.

quicksave database extracts and sanitizes the database SQL from the nearest backup snapshot for a given quicksave, which is how a quicksave can be paired with the data of its moment. quicksave malware-scan --full runs a Wordfence CLI scan over the whole quicksave directory rather than the signature list.

captaincore quicksave generate @all --parallel=10 --skip-if-recent=24h

snapshot

Snapshots are one-off downloadable zips, distinct from Restic snapshots.

--filter takes one or more of database, themes, plugins, uploads, everything-else. Without a filter the snapshot includes everything. --delete-after-snapshot deletes the site after the final snapshot is made. The generated zip is moved to the rclone_snapshot remote unless --skip-remote is given.

captaincore snapshot generate mysite-production --filter=database,themes,plugins [email protected]

store-snapshot

captaincore store-snapshot <url|file>

Moves a zip to the rclone_archive remote for cold storage.

captaincore store-snapshot https://example.com/mysite-2026-09-04.zip

archive

captaincore archive list
captaincore archive share <file>

archive list runs rclone lsjson against rclone_archive. archive share runs rclone link with --expire 168h, so the public link lasts seven days.

captaincore archive share mysite-2026-09-04.zip

capture

Captures render the site’s pages and store the HTML and screenshots, so injected scripts can be detected by comparison over time.

--pages overrides the pages to check, otherwise the site’s stored capture_pages configuration is used. capture scan --filter accepts critical, warning or external; --malware narrows to scripts only and hides ok results. Signatures come from lib/capture-signatures.json.

captaincore capture scan @production --malware --format=json

update-log

An update log describes what changed between a pair of quicksaves.

captaincore update-log list mysite-production

Archived server logs

Rotated access and error logs are streamed to B2 alongside the backup repos. See monitoring and health for logs archive, logs archive-list and logs archive-get.