shopdb-flask/docs/BACKUP-RESTORE.md

# Backup and Restore

Each site owns its own data (single-tenant, ADR-004), so backups are the site's
responsibility. A complete backup is two parts:

1. **The MySQL database** - all asset, user, audit, and settings data.
2. **The `instance/` directory** - uploaded floor plans, branding assets,
   `plugins.json` (the enabled-plugin list), and any tokens or files the app
   writes to disk. These are NOT in the database, so a DB-only backup loses
   them. Back up `instance/` alongside every database dump.

Restoring the database without the matching `instance/` directory leaves the
app pointing at floor plans and logos that no longer exist.

## What to back up

| Item | Location | Why |
|------|----------|-----|
| Database | MySQL `shopdb_flask` | All application data. |
| `instance/branding/` | repo `instance/` dir | Uploaded logos and favicon. |
| `instance/modelimages/` | repo `instance/` dir | Uploaded vendor-model photos. |
| `instance/employeephotos/` | repo `instance/` dir | Uploaded self-hosted employee photos (external mode serves photos from the HR database instead). |
| `instance/` floor plans | repo `instance/` dir | Uploaded map blueprints. |
| `instance/plugins.json` | repo `instance/` dir | Which plugins this site enabled. |
| `.env` | repo root (offline, secured) | Secrets needed to bring the stack back up. Store separately from the data backup, in a secrets manager. |

## Backup

### Database (Docker)

```bash
docker compose exec -T db mysqldump \
  -u root -p"${MYSQL_ROOT_PASSWORD}" \
  --single-transaction --routines --triggers \
  shopdb_flask | gzip > shopdb-$(date +%F).sql.gz
```

`--single-transaction` gives a consistent dump without locking the tables (InnoDB).

### Database (external MySQL, no container)

```bash
mysqldump -h <host> -u <user> -p \
  --single-transaction --routines --triggers \
  shopdb_flask | gzip > shopdb-$(date +%F).sql.gz
```

### instance directory

```bash
tar czf instance-$(date +%F).tar.gz instance/
```

Recommended cadence: nightly database dump to offsite storage, 14-day
retention; `instance/` captured on the same schedule (and always right before an
upgrade). Verify a restore quarterly.

## Restore

Restoring replaces the current database contents. Do it into a known-empty or a
throwaway target first if you are unsure.

### Step 1: Bring up the stack (or a fresh one)

```bash
cp .env.example .env   # or restore your saved .env
# ensure MYSQL_* and DATABASE_URL match the dump's database name (shopdb_flask)
docker compose up -d db
```

Wait for the `db` container to report healthy (`docker compose ps`).

### Step 2: Load the database dump

```bash
gunzip -c shopdb-2026-07-10.sql.gz | \
  docker compose exec -T db mysql -u root -p"${MYSQL_ROOT_PASSWORD}" shopdb_flask
```

For an external MySQL:

```bash
gunzip -c shopdb-2026-07-10.sql.gz | mysql -h <host> -u <user> -p shopdb_flask
```

If the target database does not exist yet, create it as utf8mb4 first (matching
the schema charset):

```sql
CREATE DATABASE shopdb_flask CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### Step 3: Restore the instance directory

```bash
tar xzf instance-2026-07-10.tar.gz    # restores ./instance/
```

The default `docker-compose.yml` does NOT bind-mount `instance/` into the api
container (its only volume is `- ./plugins:/app/plugins:ro`, and the image never
copies `instance/`), so the container's Flask instance path is an empty
`/app/instance` and a restored host `./instance` is invisible to it. To make the
restored `instance/` visible, add a bind mount to the api service before starting
it:

```yaml
  api:
    volumes:
      - ./plugins:/app/plugins:ro
      - ./instance:/app/instance
```

Make sure `./instance` is present on the host before starting `api`.

### Step 4: Bring up the API and reconcile migrations

```bash
docker compose up -d api
docker compose exec api flask db upgrade
docker compose exec api flask plugin upgrade-all
```

For a non-docker deploy:

```bash
flask db upgrade
flask plugin upgrade-all
```

`flask db upgrade` is a safety net: if the dump predates the current code, this
applies only the core Alembic chain. `flask plugin upgrade-all` then applies any
newer per-plugin migrations (each bundled plugin owns its own chain, ADR-008);
without it, plugin-owned tables stay un-migrated. If the dump is at the same
version both are no-ops.

### Step 5: Verify

- Log in with a known account.
- Confirm the floor map renders (branding and map blueprints resolve from
  `instance/`).
- Spot-check a few asset records and the audit log.
- `curl -s -X POST -H "Content-Type: application/json" -d '{}' http://localhost:5001/api/auth/login | jq .`
  should return a `VALIDATION_ERROR`, not a 500.

## Windows sites (installer-built)

On a server installed from the Windows installer, everything above is wrapped by
the operator console. Do not run mysqldump by hand:

```powershell
cd C:\shopdb-flask
.\shopdb-admin.ps1 backup            # C:\ProgramData\ShopDB-Flask\backups
.\shopdb-admin.ps1 backup D:\backups
```

The dump is verified complete before it is reported as good; a truncated one is
deleted rather than left to be discovered when it is needed. An upgrade takes its
own backup automatically before touching the schema, and restores from it if a
migration fails.

Two Windows-specific notes:

- The backup directory is locked to Administrators and SYSTEM, because a dump
  contains every row including user password hashes. Keep it that way.
- `mysqldump` must be present. It ships with the bundled-database option; a site
  using a remote MySQL needs `mysqlclient\` in its installer bundle, or the
  pre-upgrade backup is skipped. `shopdb-admin.ps1 check` reports this.

Restoring is the standard `mysql < dump.sql`, then
`.\shopdb-admin.ps1 restart`. Also restore `C:\shopdb-flask\instance\` if you are
rebuilding a server - it holds uploaded branding and map blueprints, which the
database does not.

See [OPERATE-WINDOWS.md](OPERATE-WINDOWS.md).

## See also

- [DEPLOY.md](DEPLOY.md) - first-time deploy
- [INSTALL-WINDOWS.md](INSTALL-WINDOWS.md) - Windows Server install
- [UPGRADE.md](UPGRADE.md) - upgrade procedure (back up first)
- [CONFIG.md](CONFIG.md) - environment variables and Setting keys