# Installation, updates and migration

## Small update procedure

1. Identify the package and exact target paths. A filename suffix such as `(1)` reflects a download copy, not the deployed PHP name.
2. Download the latest server files being replaced. Compare with the package's source/version notes so recent fixes are not overwritten.
3. Back up data when the update changes persistence or schema; for broader releases take file and database backups.
4. Apply on staging if available. Merge package contents into existing folders; do not replace whole directories with a changed-files-only ZIP.
5. Run native PHP lint on changed PHP files using the domain's PHP version. In a hosting terminal, `php -l filename.php` checks syntax, but the terminal PHP may differ from the website PHP. Ask the host for the matching executable if needed.
6. Test the changed feature and affected neighbours. Inspect PHP logs. Refresh changed assets with Ctrl+Shift+R or a versioned asset URL.
7. Deploy, repeat essential checks, record the change and accept the verifier baseline only when appropriate.

A standalone PHP syntax parser is useful but does not validate MySQL queries, PHP extensions, include paths, emails or browser behavior. The old guide says PHP 8.3 was selected; confirm the current domain setting rather than treating that as permanent.

## Package map

| Package | Where it belongs |
| --- | --- |
| Legacy modernization | Merge supplied root, plates, songbook and where files; retain media/config |
| Songbook link fix | Root `/showpage.php` only, never the actual viewer path |
| Password kit | Local HTML/JS stays on computer; only the reviewed bootstrap and generated password PHP go to siteadmin |
| Plate lightbox | `/plates/plates-lightbox.js` plus one script include in the latest gallery |
| Encoding audit | `/siteadmin/encoding.php`; no data conversion |
| Kennel leaderboard/menu fix | `/where/awhere_kennel_leaderboard.php` |
| Where menu | `/where/awhere_menustrip.php` |
| This documentation release | Merge its siteadmin contents; open `/siteadmin/docs.php` |

If multiple packages include the same file, use the latest combined version or merge the changes. Do not sequentially upload an older full package after a newer targeted fix.

## Hosting migration

Inventory domains, redirects, PHP settings, databases, private configuration, assets, mail delivery, installed cron jobs and backups. Confirm whether the two configured databases are actually distinct. Export and restore into the new host, set database grants, and update configuration privately.

Transfer the shared presentation files and all dependent assets. Review `.htaccess` for host-specific PHP handlers, HTTPS and old redirects; do not transplant those blindly. Recreate private backup/verification storage and any confirmed cron schedule. Test using a host preview or controlled staging setup before DNS changes, including certificate coverage for intended hostnames.

Retain a rollback window and the old host until verified. Coordinate a final data copy or editing pause so account updates made during migration are not lost. Test mail verification/recovery and all file downloads from the new host.

## Release checks

- Homepage/header/footer and mobile navigation; logged-out versus logged-in Where menu.
- Directory location search, club edit/save/reload and international characters.
- Account login/logout, profile change with password blank, counts, hare selections and races.
- Lists/maps; aliases such as Burma/Myanmar without changing stored selection positions.
- Bio links, kennel leaderboard filters/totals/ties and menu highlighting.
- Plates search/lightbox and original image fallback.
- Songbook PDF/scans, missing-page response and old root viewer link.
- Backups, fresh verification database results and this documentation viewer.

Test the new PDF/CSV export and continent workflows described below. Confirm the actual link-monitor implementation before documenting its scheduled operation.

## Install the real-continent feature

1. Back up the current travel database and affected PHP files.
2. In phpMyAdmin select the actual database used by the travel configuration.
3. Import `migration/add-real-continent.sql` from the feature package. Do not
   import the original full reference-table export over live tables.
4. Upload the corrected `/siteadmin/country_continents.php` using pdb settings.
5. Review pending and initial assignments in the editor.
6. Upload the latest combined `/where/awhere_milestones.php` and desired world-map
   badge update. v2.1 is visible on the prepared milestones card.
7. Test a known account and preserve the resulting assignments in a backup.

The additive migration checks whether the column exists and seeds only blank
values. MySQL DDL can auto-commit; a transaction does not replace a backup.
The script requires appropriate ALTER/UPDATE grants. If the column was added
but seeding failed, diagnose the error and rerun; do not drop the table.

## Install the fun certificate

Upload `/where/certificate-fonts/` first, then the latest `/where/awhere_export.php`.
Both fonts are required. No new SQL import is needed if real continents are
already installed. Test preview, PDF download, CSV, long names, all seven
continents and pending classifications. The host's logo/GD support needs its
own check. Restore the prior export PHP file to roll back.

## Install this documentation edition

Merge the enclosed siteadmin folder into the existing siteadmin folder. It
replaces `docs.php` and guide files, not authentication, config or the dashboard.
Open `/siteadmin/docs.php`; select the new-user guide, site description and
admin guide. Test editable-source downloads. Keep old or newer dashboard
customizations when adding any links.

For offline reading, extract the ZIP and open OPEN-GUIDES.html. Each guide can
be printed or saved as PDF using the browser. The documentation ZIP does not
install the continent or certificate features themselves.