Backups
What gets backed up on each environment, the retention schedule, and how to restore via the Hub or the command line.
Every StoreFrame environment has automated, encrypted, off-site backups. Backups run daily and retain snapshots for up to 12 months. You can restore from the Hub UI or directly over SSH.
How backups work
A daily cron job on each environment backs up the entire project directory. After each backup, old snapshots are pruned according to the retention policy below. Everything is encrypted before leaving the server. Encryption keys are managed by StoreFrame — you do not need to configure or rotate them.
Schedule: Daily
What gets backed up
The backup covers the entire project directory at /var/www/<subdomain>.<domain>/, which includes:
| Path | Contents |
|---|---|
application/app/etc/env.php | Database credentials, Redis config |
application/app/etc/config.php | Module configuration |
application/pub/media/catalog/ | Product images |
application/var/log/ | Application logs |
backups/mysql/ | Scheduled daily MariaDB SQL dumps |
docker-compose.yml | Container composition |
Exclusions
The live MariaDB data files are not included, because copying a running database produces an inconsistent snapshot. Your database is protected by the daily SQL dumps in backups/mysql/, which are part of every backup.
Retention policy
| Policy | Value |
|---|---|
| Keep every snapshot from the last | 14 days |
| Keep monthly snapshots | 12 (one per month) |
| Keep yearly snapshots | 1 |
In practice: you have every daily snapshot from the last 14 days, then one snapshot per month going back a year, plus one yearly snapshot. For most restore scenarios the 14-day window covers you; monthly snapshots provide a longer safety net.
Manual backups you start from the Hub are kept separately: the 10 most recent are retained.
Database backups
MariaDB dumps are handled separately from the file backup. A MySQL backup script runs daily and writes compressed SQL dumps to /var/www/<subdomain>.<domain>/backups/mysql/, named backup_DD-MM-YYYY_HHMM.sql.gz (for example backup_08-01-2026_2211.sql.gz). These dump files are then captured by the next daily backup.
Dump retention: the 7 most recent dumps stay on disk locally; older dumps survive inside backup snapshots per the retention policy above.
To take an extra dump right now, run sudo framectl db dump on the VM.
Restoring via the Hub
For most restore operations, the Hub backup tab is the fastest path.
Go to your environment's Settings → Backup, select a snapshot, choose the database, and confirm. The Hub puts the store in maintenance mode, runs the restore in the background and reports the result. To get files back, copy them out of a snapshot over SSH (see below) and put them in place yourself.
The same database restore is available over SSH:
sudo framectl snapshot offsite restore --scope db --snapshot <snapshot_id>Restoring via SSH
For cases where you need more control — getting single files or folders back, restoring to a specific target path, or scripting a restore — use framectl snapshot offsite directly. The extract commands below copy files out of a snapshot into a side folder; they never overwrite the live site.
List available snapshots
sudo framectl snapshot offsite listThis shows a human-readable list of snapshots with short IDs (8 characters) and timestamps.
Restore a specific file
sudo framectl snapshot offsite extract file application/app/etc/env.php -s <snapshot_id>Paths are relative to the backup root (/var/www/<subdomain>.<domain>/). The restored file lands in a timestamped directory under /var/www/restore/YYYYMMDD-HHMMSS/, which keeps the full original path. Copy it to the production location once you've verified it. Use --target <dir> to restore somewhere else.
# Example: copy restored env.php back into place
cp /var/www/restore/20260109-143022/var/www/<subdomain>.<domain>/application/app/etc/env.php \
/var/www/<subdomain>.<domain>/application/app/etc/env.phpRestore a directory
sudo framectl snapshot offsite extract directory application/pub/media/catalog/ -s <snapshot_id>Restore a database from a SQL dump
To restore one of the 7 dumps still on the VM, use framectl db restore:
sudo framectl db restore --list # show the dumps on disk
sudo framectl db restore --latest # restore the newest dump
sudo framectl db restore backup_08-01-2026_2211.sql.gz # restore a specific dumpFor an older dump, restore it from a snapshot first, then import it:
# 1. Restore the MySQL backups directory from a snapshot
sudo framectl snapshot offsite extract directory backups/mysql/ -s <snapshot_id>
# 2. Import the dump you want
gunzip -c /var/www/restore/*/var/www/*/backups/mysql/backup_08-01-2026_2211.sql.gz \
| mysql magentosudo framectl snapshot offsite restore --scope db --snapshot <snapshot_id> does both steps for the newest dump in that snapshot, with maintenance mode on.
Copy out everything
sudo framectl snapshot offsite extract full -s <snapshot_id>This copies the entire project directory from the snapshot into a timestamped directory under /var/www/restore/. Nothing live is overwritten. Check the free disk space first: it needs as much room as the project itself.
Common path shortcuts
| What to restore | Path argument |
|---|---|
| Magento env.php | application/app/etc/env.php |
| All MySQL dumps | backups/mysql/ |
| Product images | application/pub/media/catalog/product/ |
| Application logs | application/var/log/ |
Manual backup trigger
To run a backup immediately outside the scheduled window, trigger one from the Hub's Settings → Backup tab, or run sudo framectl snapshot offsite backup on the VM (add --label "<name>" to name it). A manual backup takes a fresh database dump first.
Backup logs
Backup output is written to /var/log/restic.log. Check it to confirm the last run completed cleanly:
sudo tail -50 /var/log/restic.logA successful run ends with a snapshot <id> saved line followed by a forget prune summary.
Encryption and key management
Backups are encrypted before uploading off-site. Keys are generated during provisioning and managed by StoreFrame — you do not need to configure, rotate, or back them up. If you suspect a backup issue, file a support ticket.
Related
- Settings → Backup — restore snapshots from the Hub UI
- Users and SSH — how to connect to your environment