# Backups

Source: https://www.storeframe.io/docs/infrastructure/operations/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](/docs/hub/environments/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:

```bash
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

```bash
sudo framectl snapshot offsite list
```

This shows a human-readable list of snapshots with short IDs (8 characters) and timestamps.

### Restore a specific file

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

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

### Restore a directory

```bash
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`:

```bash
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 dump
```

For an older dump, restore it from a snapshot first, then import it:

```bash
# 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 magento
```

`sudo 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

```bash
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](/docs/hub/environments/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:

```bash
sudo tail -50 /var/log/restic.log
```

A 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](/docs/help/support/file-a-ticket).

## Related

* [Settings → Backup](/docs/hub/environments/settings/backup) — restore snapshots from the Hub UI
* [Users and SSH](/docs/infrastructure/operations/users-and-ssh) — how to connect to your environment
