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:

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:

$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):

& "$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)

$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:

& $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):

$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

# 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:

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.