# Upgrade Guide

How to safely update an existing SocietyHub Pro installation to this release.

## 1. Back up the database and uploads

**Admin → Settings → Backup & Restore → Create Backup → Complete.** Download it and keep a copy
somewhere off-server. This is the single most important step — everything else here is reversible if
this one is done first.

If you'd rather back up manually instead of (or in addition to) using the built-in tool: export the
database with `mysqldump`, and copy `storage/app/public/` (uploaded media) somewhere safe.

## 2. Check current status

**Admin → Status** and **Admin → Settings → Updates** — confirm the app is currently healthy and note
the installed version before you touch anything.

## 3. Upload the new release

Upload this package's files, replacing the existing application code but **not**:

- `.env`
- `storage/` (uploaded media, backups, logs)
- `public/storage` (the symlink itself — don't overwrite it with an uploaded copy; re-run
  `php artisan storage:link` afterward if it ends up broken, see step 6)

If your host's file manager or deploy process doesn't cleanly exclude these, upload to a fresh directory
and manually copy `.env` and `storage/` across afterward, rather than overwriting in place.

This package already includes production `vendor/` and a compiled `public/build/` — no `composer
install` or `npm run build` is needed unless you're upgrading from your own source checkout instead of
this pre-built package (see the note in `INSTALL.md` §3).

## 4. Run migrations

```bash
php artisan migrate --force
```

**Never run `migrate:fresh`** on a real installation — it drops every table. All migrations in this
release are additive; see `CHANGELOG.md` for anything version-specific worth knowing before you run
them (this release's "Notes for upgraders" section, for example, explains that existing media is left
untouched until you explicitly choose to migrate it).

## 5. Re-sync permissions

Safe to run any time — idempotent, and existing role customizations for permissions that already
existed are untouched:

```bash
php artisan tinker --execute="(new Database\Seeders\PermissionCatalogSeeder)->run();"
```

## 6. Verify with Deployment Center

**Admin → Settings → Deployment Center → Re-check.** Confirm everything reads Ready. Pay particular
attention to **Storage Link** — if the upload process touched `public/storage`, re-run
`php artisan storage:link` if it now shows Failed.

## 7. Confirm the scheduler is still wired up

This release adds a new scheduled task (`media:process-pending`, every 5 minutes) alongside the
existing reminders/backup entries. If you're on Option A (shell cron running `php artisan schedule:run`)
in `INSTALL.md` §13, nothing further is needed — it picks up the new task automatically. If you're on
Option B (individual HTTP cron entries), add the new `POST /cron/media-process` entry shown there.

## 8. Clear and re-cache configuration

```bash
php artisan config:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

## 9. Test the application

Log in, confirm the dashboard loads, and spot-check the areas this release actually touched (see
`CHANGELOG.md`): Events, Community Updates, the admin Media Library's new processing status, and
messaging (including sending a voice note, if you were affected by the fix in this release).

## Optional: optimize

Once you're confident the upgrade is stable, **Admin → Settings → Deployment Center → Optimize
Application** caches config/routes/views for production performance (equivalent to step 8, run from the
admin UI). This signs everyone out — expected, see `docs/TROUBLESHOOTING.md`.

## If something goes wrong

Restore the backup from step 1: **Admin → Settings → Backup & Restore**, find it in the history table,
**Restore**. This replaces current data with the backup's contents — confirm you mean it before
proceeding. If the app itself won't load to reach that screen, restore the database dump manually
against your MySQL server and roll the application files back to the previous release.