# Upgrading an existing site

This is the procedure for moving a running shopdb-flask instance to a newer
version. For a first-time install use [DEPLOY.md](DEPLOY.md) instead.

Each site is single-tenant (ADR-004), so an upgrade touches only that site's
own stack. Read the ADRs added since your last update (`docs/adr/`) and the
`CHANGELOG.md` before starting; a breaking ADR may require coordinated work.

## Step 0: Back up first

Never upgrade without a fresh backup you have tested. Take a full database dump
and copy the `instance/` directory. See [BACKUP-RESTORE.md](BACKUP-RESTORE.md).

```bash
# Docker:
docker compose exec -T db mysqldump -u root -p"${MYSQL_ROOT_PASSWORD}" shopdb_flask | gzip > pre-upgrade-$(date +%F).sql.gz
cp -a instance/ instance-backup-$(date +%F)/
```

## Step 1: Get the new code / image

```bash
git pull origin main
```

The application is distributed through the internal GE Aerospace Gitea; pull
from there. There is no external image registry.

## Step 2: Rebuild

The Docker image builds the Vue frontend in-image, so a container rebuild picks
up frontend changes automatically:

```bash
docker compose build api
docker compose up -d api
```

Bare-metal / venv install: rebuild the frontend by hand and refresh Python
dependencies:

```bash
source venv/bin/activate
pip install -r requirements.txt
cd frontend && npm ci && npm run build && cd ..
```

## Step 3: Apply migrations

```bash
# Docker:
docker compose exec api flask db upgrade
# venv:
flask db upgrade
```

`flask db upgrade` applies any new migrations in the core Alembic chain. It is
idempotent; running it when already at head is a no-op.

## Step 4: Re-seed permissions and settings

New versions may add RBAC permissions or default Settings keys. Both seeders are
idempotent - they add anything missing and leave existing rows untouched, so
your site's customized values are preserved.

```bash
# Docker:
docker compose exec api flask seed permissions
docker compose exec api flask seed settings
# venv:
flask seed permissions
flask seed settings
```

## Step 5: Restart

```bash
docker compose restart api
# venv: restart your process manager, e.g. pm2 restart shopdb-flask-api shopdb-flask-ui
```

Confirm the app is healthy (login page renders, `/api/auth/login` returns a
`VALIDATION_ERROR` for an empty body rather than a 500).

## Version-specific notes

### Upgrading to v0.5.0 or later: bundled West Jefferson floor plan removed

Versions before 0.5 shipped the West Jefferson facility floor-plan PNGs as the
map default (`/static/images/sitemap2025-light.png` and `-dark.png`). v0.5+
removes those bundled PNGs and ships a generic placeholder SVG instead.

If your instance's `map_blueprint_light` / `map_blueprint_dark` Settings still
point at `/static/images/sitemap2025-*`, the map will 404 those images after the
upgrade. Re-upload your own floor plan in **Settings > Map**. Uploaded floor
plans are stored under `instance/` and survive upgrades, so a site that already
uploaded its own plan is unaffected. Only instances still using the old bundled
default need to act.

To check what your instance points at:

```bash
docker compose exec api flask shell -c "from shopdb.core.models.setting import Setting; print(Setting.query.filter(Setting.key.like('map_blueprint%')).all())"
```

## See also

- [BACKUP-RESTORE.md](BACKUP-RESTORE.md) - what to back up and how to restore
- [CONFIG.md](CONFIG.md) - environment variables and Setting keys
- [DEPLOY.md](DEPLOY.md) - first-time deploy runbook
- `CHANGELOG.md` - what changed in each release