PQS/install/DEPLOYMENT-WALKTHROUGH.md

# PQS on XAMPP Lite 8.5 — verified deployment walkthrough

This is a full record of an **actual deployment** performed on 2026-07-01, with
the exact commands and the results observed. Stack verified:

- **Apache** serving **PHP 8.5.5** (Thread-Safe, `php8apache2_4.dll` module)
- **MariaDB 11.4.10**
- App served from `www\pqs`, reachable at `http://localhost/pqs/...`
- **Result:** registration, all console/wall pages, and the Commit-Mission
  transaction all worked; **zero PHP 8.5 warnings/deprecations** from app code.

There are two ways to run it: the **operator method** (GUI control panel — what
you'd do at a venue) and the **headless method** (exact commands, for scripting /
on-demand automation). Both end at the same place.

---

## 0. Stack layout

```
xampp_lite_8_5\
  XL-Control-Panel.x64.exe
  apps\apache\bin\httpd.exe          Apache
  apps\apache\conf\httpd.conf        Listen 127.0.0.1:80 ; DocumentRoot ${XAMPP_LITE_ROOT}/www
  apps\mysql\bin\mysqld.exe          MariaDB server
  apps\mysql\bin\mysql.exe           MariaDB client
  apps\mysql\bin\my.ini              port 3306
  apps\mysql\data\                   datadir (already initialized)
  apps\php\php.exe                   PHP 8.5.5
  www\                               document root
```

Apache's config resolves two environment placeholders that the control panel
normally sets. For the headless method you set them yourself:

- `XAMPP_LITE_ROOT` = the stack root, forward slashes, e.g. `C:/VWE/PQS/xampp_lite_8_5`
- `SRVROOT`         = `${XAMPP_LITE_ROOT}/apps/apache`

Default ports: Apache `127.0.0.1:80`, MariaDB `3306`. Confirm they're free first
(`Get-NetTCPConnection -State Listen -LocalPort 80,3306`).

---

## 1. Deploy the application into the web root

Copy the PQS app into `www\pqs`, excluding the XAMPP stack itself, the `.7z`
archive and `.git`:

```powershell
robocopy C:\VWE\PQS C:\VWE\PQS\xampp_lite_8_5\www\pqs /E `
  /XD C:\VWE\PQS\xampp_lite_8_5 C:\VWE\PQS\.git /XF *.7z
```
(robocopy exit codes 0–7 mean success.)

---

## 2. Start MariaDB

**Operator:** click **Start** next to MySQL in `XL-Control-Panel.x64.exe`.

**Headless:**
```powershell
$x = "C:\VWE\PQS\xampp_lite_8_5"
Start-Process -FilePath "$x\apps\mysql\bin\mysqld.exe" `
  -ArgumentList "--defaults-file=`"$x\apps\mysql\bin\my.ini`"","--datadir=`"$x\apps\mysql\data`"" `
  -WindowStyle Hidden
```
Verify it's up (root has no password):
```powershell
& "$x\apps\mysql\bin\mysql.exe" -u root -h 127.0.0.1 -e "SELECT VERSION();"
# -> 11.4.10-MariaDB-log
```

---

## 3. Provision the database (one time)

```powershell
$mysql = "$x\apps\mysql\bin\mysql.exe"
cmd /c "`"$mysql`" -u root -h 127.0.0.1 < `"C:\VWE\PQS\install\pqs_install.sql`""
```
Verify:
```powershell
& $mysql -u pqs -ppqs -h 127.0.0.1 pqs -e `
 "SELECT (SELECT COUNT(*) FROM pqs_mechinfo) mechs,
         (SELECT COUNT(*) FROM pqs_mapinfo)  maps,
         (SELECT numpods  FROM pqs_gameconfig) numpods;"
# -> mechs=63  maps=26  numpods=6   (10 tables, all InnoDB)
```
> The installer is **not** safe to re-run (seed inserts duplicate / hit the
> `gameconfig` unique key). To redo it: `DROP DATABASE pqs;` then reload.

---

## 4. Start Apache

**Operator:** click **Start** next to Apache in the control panel.

**Headless** (must set the two env vars in the *same* shell that launches httpd):
```powershell
$x = "C:\VWE\PQS\xampp_lite_8_5"
$env:XAMPP_LITE_ROOT = ($x -replace '\\','/')
$env:SRVROOT         = "$($x -replace '\\','/')/apps/apache"

# optional sanity check:
& "$x\apps\apache\bin\httpd.exe" -t -f "$x\apps\apache\conf\httpd.conf"   # -> Syntax OK

Start-Process -FilePath "$x\apps\apache\bin\httpd.exe" `
  -ArgumentList "-f","`"$x\apps\apache\conf\httpd.conf`"" -WindowStyle Hidden
```

---

## 5. Verify end-to-end

```powershell
# register a player through the kiosk
Invoke-WebRequest -UseBasicParsing `
  "http://localhost/pqs/callsign.php?submit=yes&callsign=XamppTest&mech=41&wclass=Assault"
# -> 200, page contains "entered into the queue"

& $mysql -u pqs -ppqs -h 127.0.0.1 pqs -e "SELECT CallSign,Mech,MissionID FROM pqs_queue;"
# -> XamppTest  Atlas  1
```
Observed in this deployment:
- `callsign.php`, `registration.php`, `console.php`, `combinedqueue.php`,
  `includes/getqueue.php` → all HTTP **200**, no `Fatal error`.
- Commit Mission (`console.php?submit=Commit+Mission&nummercs=1`) moved the
  player to `pqs_currentmission` + `pqs_pastmissions`, emptied the queue, and set
  `pqs_mission.Completed=1` — the transaction path works on MariaDB 11.4.
- Apache error log (`tmp\apache_logs\apache_error.log`): **no PHP
  warnings/deprecations from app code.** (An `xdebug` load notice can appear from
  the CLI `php.exe` only; it does not occur under Apache and is harmless.)

Screens:
- Kiosk http://localhost/pqs/callsign.php
- Reg console http://localhost/pqs/registration.php
- Ops console http://localhost/pqs/console.php
- Queue wall http://localhost/pqs/combinedqueue.php
- phpMyAdmin http://localhost/phpmyadmin (bundled)

---

## 6. Stop / teardown

**Operator:** Stop both in the control panel.

**Headless:**
```powershell
Get-Process httpd, mysqld -ErrorAction SilentlyContinue | Stop-Process
```
The database persists in `apps\mysql\data`. To wipe the app's data for a fresh
event, `DROP DATABASE pqs;` and re-run the installer (§3), or use the
`docs/Clear Code.txt` truncates to clear just the live queue/mission tables.

---

## 7. One-command launcher

`install\start-pqs.bat` bundles §2 + §4 and provisions the DB on first run
(§3) if it doesn't exist yet. Copy it to the XAMPP Lite root (next to
`XL-Control-Panel.x64.exe`) and double-click, or run it from a prompt.