Backups and restoration

Back up more than the database

A recoverable store needs a consistent set of data, files, and secrets. Keep encrypted off-server copies and test access with someone other than the original installer. Decide how much recent order data you can afford to lose and how long recovery may take; those requirements determine backup frequency and retention.

Include all of the following:

• The primary MariaDB/MySQL database and any independently configured compensation-journal database.
• .env, especially the original APP_KEY, stored through a protected secrets-backup process.
• storage/app/private for private files and local backup artifacts.
• storage/app/public for merchant media.
• storage/app/agovena/installed.json, which should agree with the database installation identity.
• storage/app/packages and any other configured package locations, plus the exact Core release, themes, and dependency lockfiles.
• Deployment configuration, service units, cron configuration, and any external storage your store actually uses.

Backing up all persistent storage/app is safer than selecting only uploads. Avoid recursively including old backup archives in a new archive without a retention plan. See the filesystem configuration and installation lock.

Create an encrypted database backup

Core provides Admin → Backups and this command:

php artisan agovena:backup

The command backs up the configured primary database, compresses and encrypts its payload, and prunes expired artifacts. It does not archive uploads, .env, packages, or a second database connection. The default target is the local disk's backups directory, normally storage/app/private/backups.

MariaDB/MySQL backups invoke the configured dump client with --single-transaction, routines, and triggers. Make the compatible client available to the FPM/CLI user. AGOVENA_MYSQLDUMP_BINARY defaults to mysqldump; AGOVENA_MYSQL_BINARY defaults to mysql for restoration. On hosts using differently named MariaDB clients, configure those executable paths explicitly. The database account also needs the permissions required by its dump operation.

The implementation is in BackupManager. A single-transaction dump is not an all-services snapshot, and concurrent schema changes should be avoided.

Configure scheduling and retention

In Admin → Backups, choose disabled, hourly, every six hours, every twelve hours, daily, or weekly. Saving an interval does not start cron. The scheduler must run and show a recent heartbeat.

Defaults are a daily schedule, 30 retention days, and 10 retained artifacts. Review AGOVENA_BACKUP_DISK, AGOVENA_BACKUP_DIRECTORY, AGOVENA_BACKUP_INTERVAL, AGOVENA_BACKUP_RETENTION_DAYS, and AGOVENA_BACKUP_RETENTION_COUNT. Configure AGOVENA_BACKUP_ALERT_EMAIL with a working mail transport for command failure alerts. An alert on the same failed server is not independent monitoring.

References: backup configuration and BackupSchedule.

Verify an artifact without inventing its name

The backup command reports the relative artifact path. Pass that exact value as the path argument to php artisan agovena:backup-verify. Do not rename an artifact to change its database type.

This command verifies decryption, payload recognition, and SQLite integrity where applicable. For a MySQL/MariaDB SQL payload, recognition is not a full database import or application recovery rehearsal. See BackupRestoreVerifier. Losing the encryption key can make an otherwise intact backup unreadable.

Rehearse restoration on an isolated host

1. Restrict network access and disable outbound payment, provisioning, and customer-mail effects. Do not let restored queued jobs run against real accounts.
2. Restore the matching application revision, .env/key, package files, and persistent storage from one recovery point. Use a separate database target, never the live store by accident.
3. Restore the database with your protected database backup tooling. For a working isolated Admin installation, Backups → Restore can restore a recognized encrypted artifact into its configured database. It requires management permission and recent password confirmation, and replaces data. It does not restore application files or provide a universal CLI restore command.
4. Restore any separate journal/database and reconcile it with the same recovery point.
5. Run php artisan storage:link and php artisan agovena:doctor. Investigate installation-marker mismatches instead of rerunning the installer.
6. Verify customer access, existing orders/invoices, encrypted settings, private downloads, public media, and package availability. Test background processing only with isolated endpoints.

The Admin restore action does not make a live database restore safe while other processes are writing. During a real incident, stop or isolate writers first and preserve the failed state for investigation. Reconcile provider payments and deliveries created after the recovery point before reopening. An old database cannot undo a payment or remote server that already exists.