Backup

Backups of the database and the uploads, to this server or remote storage, on a schedule.

kitloom/backup · admins: kitloom/backup-filament, kitloom/backup-nova

Video lessons

Recorded in the Filament admin; the Nova admin works the same way.

Backups

Backup Settings

Backups of a kitloom site — the UpdraftPlus of kitloom — on top of spatie/laravel-backup: the database and the uploads in one zip archive, copied to this server, S3-compatible storage, SFTP or FTP, kept for as many archives and days as the settings say, on a daily or weekly schedule, with failures emailed to the site's administration address. The admin is kitloom/backup-filament or kitloom/backup-nova (the Backups section in either).

The server

Cron. The module puts the backup into Laravel's schedule itself; the server only needs the scheduler called every minute:
```
* * * * * cd /path/to/site && php artisan schedule:run >> /dev/null 2>&1
```
The status line says whether the scheduler comes by (it notes the time once in ten minutes, option kitloom_backup_cron_seen). On several servers the backup and this note are made by one of them, by a lock in the cache, so a site on several servers needs a shared cache store (Redis, the database) — with each server's own cache the lock is local and the task runs on every one.
The dump program of the database: mysqldump (MySQL), mariadb-dump, pg_dump, sqlite3. Without it the database cannot be backed up; the status says so. Elsewhere than on PATH: dump.dump_binary_path of the connection in config/database.php, as spatie reads it.
A queue worker for "Back up now" when the queue is not sync. On sync it runs in the request and the admin hears the outcome at once.
A Flysystem adapter for a remote destination, required by the application, not by this package: see "Remote destinations". The settings name the missing one.

Remote destinations

Only "This server" is on out of the box. S3, SFTP and FTP are off, and their adapters are not installed with the module, so a site that keeps its archives at home does not carry the AWS SDK. To send archives elsewhere:

Require the adapter in the application:

bash

composer require league/flysystem-aws-s3-v3   # S3 and S3-compatible storage
composer require league/flysystem-sftp-v3     # SFTP
composer require league/flysystem-ftp         # FTP, also needs PHP's ftp extension

The adapters are MIT; the S3 one brings aws/aws-sdk-php, which is Apache-2.0.

In the backup settings, switch the destination on and fill in its fields. Until the required ones are filled the destination is skipped and the status names what is missing.
Run "Back up now" once: a destination that refuses shows in the status with the storage's own error.

Every destination switched on gets a copy of each archive, and old archives are removed from each of them by the same "Archives kept" and "Days archives are kept".

S3-compatible storage. Access key ID, secret access key, region and bucket are required; Amazon S3 needs nothing more. Other storage needs the endpoint its documentation gives: for Cloudflare R2 https://<account>.r2.cloudflarestorage.com with region auto, for MinIO the server's address with "Path-style addresses" on. "Folder in the bucket" puts archives under a prefix; empty is the bucket root. The key must list the bucket and put, get and delete objects in it (s3:ListBucket, s3:PutObject, s3:GetObject, s3:DeleteObject on Amazon): the cleanup deletes old archives, the rescan lists them, a download reads them.

SFTP. Host and username are required, the port is 22 by default. Sign in with a password or with a private key pasted whole (-----BEGIN …); with an encrypted key the password field holds its passphrase. An empty "Folder" is the one the user logs into.

FTP. Host and username are required, the port is 21 by default. "Over TLS (FTPS)" is on by default; turn it off only for a server that cannot do TLS, since the password then travels in the clear. Passive mode is on by default, which is what servers behind a firewall need.

Settings

Options of the site (wp_options), declared by BackupOptions and written through SettingWriter:

Option	What
`kitloom_backup_database`, `kitloom_backup_uploads`	What goes into the archive (both on)
`kitloom_backup_to_local`, `_to_s3`, `_to_sftp`, `_to_ftp`	Destinations switched on (this server only)
`kitloom_backup_s3_key`, `_s3_secret`, `_s3_region`, `_s3_bucket`, `_s3_endpoint`, `_s3_path_style`, `_s3_folder`	S3-compatible storage
`kitloom_backup_sftp_host`, `_port`, `_username`, `_password`, `_private_key`, `_folder`	SFTP
`kitloom_backup_ftp_host`, `_port`, `_username`, `_password`, `_ssl`, `_passive`, `_folder`	FTP
`kitloom_backup_keep`, `kitloom_backup_keep_days`	Retention: the newest N archives, none older than D days (0 — no limit); the newest is never deleted
`kitloom_backup_schedule`, `_time`, `_weekday`	`off` / `daily` / `weekly`, HH:MM in the site's timezone, 0 (Sunday)–6
`kitloom_backup_last_success`, `_last_failure`, `_cron_seen`	The module's own record for the status

Secrets (_secret, _password, _private_key) are encrypted with the application key, never shown back in the admin, and kept when their field is left empty. They are protected options: no user writes one through the writer in the clear.

Failures (a backup, a cleanup) are mailed by spatie's notifications to the admin_email option; successes are not mailed.

AI agents

With kitloom/ai installed, an agent whose user has manage_options reads the status and the newest archives (backup_status) and backs the site up now (backup_run) — worth asking for before an agent changes many records. The archive goes only to the destinations set here, and the backup settings stay locked for agents; downloading and deleting archives is left to a person in the admin. kitloom-backup.ai.register false — no backup tools.

Site Health

With spatie/laravel-health installed — kitloom/health brings it — Site Health gets a check of its own, BackupDestinations: a warning when backups are in use (scheduled, or made at least once) and their only destination is "This server", or none is switched on. Archives on the server alone are lost with it, and on Laravel Cloud or App Platform, whose disk is reset on every deploy, with the next deploy. Unused backups are not judged. kitloom-backup.health.register false — no check.

How it runs

Nothing is read at boot. When a backup, a cleanup, a download or a rescan runs, SpatieConfig turns the options into spatie's backup config and the destinations' disks (kitloom-backup-local, kitloom-backup-s3, …) for that process only. BackupRunner makes the archive with spatie's BackupJob and cleans each destination with RetentionStrategy; the kitloom:backup command (what the schedule runs) and the queued RunBackup job ("Back up now") both run it. spatie's events keep the status and the list of archives (table backups, BackupIndex) in line.

The archive holds db-dumps/… and the uploads folder under its own name. Uploads on a disk that is not a folder of this server (S3) are not archived: their storage keeps them. spatie's BACKUP_ARCHIVE_PASSWORD still encrypts the archive.

spatie's own backup:* commands keep the application's config/backup.php: the module's settings apply to kitloom:backup and the admin.

Configuration

php artisan vendor:publish --tag=kitloom-backup-config for kitloom-backup.php: the folder name on destinations (name), this server's folder (local.root, by default storage/app/private/kitloom-backups), the working folder, the database connection and the uploads disk (by default the media module's kitloom-media.disk, otherwise public), the schedule switch, the queue of "Back up now", the tools for AI agents (ai.register), the admin switches (filament.register, nova.register).

Tests

From the application that installs the package: php vendor/bin/phpunit --testsuite Backup. The dump is faked (src/Testing/FakeDumpers.php): the tests need neither mysqldump nor sqlite3, and leave nothing behind.