Add local WSL test-stack setup tooling

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-01 12:48:38 -05:00
parent 00d6ec148e
commit 7d643dde17
2 changed files with 105 additions and 0 deletions
@@ -0,0 +1,42 @@
+# dev/ — local test environment
+
+Tooling to run PQS locally for testing, **not** part of the deployed app.
+
+The venue server is Debian + PHP + MySQL. The closest local mirror on this
+machine is **WSL2 Ubuntu**, so we test there.
+
+## First-time setup
+
+From a WSL Ubuntu shell, in the repo root:
+
+```bash
+bash dev/setup-local.sh
+```
+
+This installs `php-cli`, `php-mysql`, and `mariadb-server`, creates the `pqs`
+database + `pqs`/`pqs` user, and loads `docs/pqs.sql`. You'll be asked for your
+sudo password. It's idempotent — safe to re-run.
+
+## Running the app
+
+```bash
+# serve the PARENT of the repo so the app's hardcoded /pqs/ URLs resolve
+php -S 0.0.0.0:8080 -t /mnt/c/VWE
+```
+
+Then browse:
+- Kiosk:        http://localhost:8080/PQS/callsign.php
+- Reg console:  http://localhost:8080/PQS/registration.php
+- Ops console:  http://localhost:8080/PQS/console.php
+- Queue wall:   http://localhost:8080/PQS/combinedqueue.php
+
+## Notes / caveats
+
+- **PHP version differs from the venue.** Ubuntu 24.04 ships PHP 8.3; the venue
+  box was PHP 5.4. We keep application code compatible with 5.5+ so it runs in
+  both, but PHP 8 is stricter — the legacy `mysql_*` calls in the original code
+  will fatal here until they're replaced (which is part of the improvement plan).
+- **MariaDB stands in for MySQL 5.5.** Fine for our purposes: InnoDB,
+  transactions, and the SQL this app uses are all equivalent.
+- After a WSL restart the DB is stopped; run `sudo service mariadb start`.
+- This is a throwaway DB with no real player data.