# Legacy migration runbook

This procedure preserves the supplied Modesy 2.7 IDs, database rows, slugs, passwords, order numbers, and upload paths.

## Browser installer (recommended for cPanel)

1. Upload the application and set the domain document root to the project's `public/` directory.
2. Create the MySQL database and user, grant all privileges on that database, and import `modernstore.sql` with phpMyAdmin.
3. Copy `.env.example` to `.env`, set `APP_ENV=production`, `APP_DEBUG=false`, `APP_URL`, and temporarily set `INSTALLER_ENABLED=true`.
4. Generate `APP_KEY` with `php artisan key:generate`; without terminal access, generate the key locally before upload.
5. Visit `/install`. The guarded wizard checks PHP/extensions/permissions, tests the database, audits the legacy schema, applies additive migrations, configures the administrator/company, and validates the WebMarket license endpoint.
6. Finish the wizard, then set `INSTALLER_ENABLED=false` and run `php artisan optimize`.

The SQL dump is deliberately not uploaded through the wizard because browser and PHP execution limits can interrupt large imports. The wizard never drops or re-imports legacy tables. Its lock is stored at `storage/app/private/installed`; remove it only for intentional recovery and keep the installer disabled otherwise.

The production middleware validates the configured license endpoint, caches successful checks for `WEBMARKET_LICENSE_CACHE_MINUTES`, and permits temporary license-server outages only within `WEBMARKET_LICENSE_GRACE_DAYS`. Explicit invalid/revoked responses are not placed into the outage grace path.

## Before starting

1. Back up the live database and complete legacy `uploads` directory.
2. Create a new empty database and import `modernstore.sql` with phpMyAdmin or the MySQL command line.
3. Extract WebMarket into a separate release directory. Do not overwrite the existing live application.
4. Configure `.env` with the imported database, production URL, mail service, payment secrets, and WebMarket license values.
5. Set `LEGACY_APPLICATION_ROOT` to the absolute extracted Modesy application directory that contains `uploads`.

## Windows verification

```powershell
composer install
php artisan key:generate
php artisan optimize:clear
php artisan webmarket:legacy-audit
php artisan webmarket:legacy-integrity
php artisan webmarket:deployment-check
php artisan webmarket:import-uploads "C:\absolute\path\to\modesy-2.7" --dry-run
php artisan migrate
php artisan webmarket:import-uploads "C:\absolute\path\to\modesy-2.7"
php artisan webmarket:import-uploads "C:\absolute\path\to\modesy-2.7" --verify
php artisan storage:link
php artisan route:list
php artisan test
```

The dry run reports executable or hidden files as blocked. Conflicting destination files cause failure and are not overwritten unless `--force` is deliberately supplied. A SHA-256 manifest is written to private application storage after a successful copy.

## Shared-hosting cutover

Run the same audit, integrity, migration, upload verification, storage-link, route-list, and test commands from cPanel Terminal. Point the domain document root to WebMarket's `public` directory only. Configure this cron entry:

```text
* * * * * cd /absolute/path/to/webmarket && php artisan schedule:run >> /dev/null 2>&1
```

After validation, set `APP_ENV=production`, `APP_DEBUG=false`, and run:

```text
php artisan optimize
```

Never run `migrate:fresh`, `db:wipe`, or destructive schema commands against the imported database.

## Acceptance checks

- Existing users can sign in without resetting their passwords.
- Product, blog, page, order, digital-sale, and license URLs resolve correctly.
- `/sitemap.xml`, `/robots.txt`, and `/feed.xml` respond successfully.
- A configured secondary language works under `/{locale}/...` and displays matching translated records.
- Old configurable product, category, blog, order, wallet, messages, downloads, refund, RSS, and ticket URLs redirect to canonical Laravel routes.
- Legacy images and downloads resolve through the preserved `uploads/...` path.
- Payment sandbox callbacks, webhook signatures, wallet operations, payout reservations, refunds, queued notifications, and scheduler execution are tested before DNS cutover.