From 7d643dde178c504c6fd9fd754059d1834ff20e59 Mon Sep 17 00:00:00 2001
From: Cyd <cyd@falloutshelterarcade.com>
Date: Wed, 1 Jul 2026 12:48:38 -0500
Subject: [PATCH] Add local WSL test-stack setup tooling

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 dev/README.md      | 42 +++++++++++++++++++++++++++++++
 dev/setup-local.sh | 63 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 105 insertions(+)
 create mode 100644 dev/README.md
 create mode 100644 dev/setup-local.sh

diff --git a/dev/README.md b/dev/README.md
new file mode 100644
index 0000000..2a4024d
--- /dev/null
+++ b/dev/README.md
@@ -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.
diff --git a/dev/setup-local.sh b/dev/setup-local.sh
new file mode 100644
index 0000000..5233c81
--- /dev/null
+++ b/dev/setup-local.sh
@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+#
+# PQS local test-stack setup (WSL2 Ubuntu / Debian).
+#
+# Stands up a throwaway PHP + MariaDB stack that mirrors the venue server
+# (Debian-family) closely enough to test PQS before deploying.
+#
+# Run once from inside WSL:
+#     bash dev/setup-local.sh
+#
+# It will prompt for your sudo password (to install packages + start the DB).
+# Safe to re-run; it is idempotent.
+
+set -euo pipefail
+
+# Resolve repo root from this script's location (dev/ is one level down).
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+DB_NAME="pqs"
+DB_USER="pqs"
+DB_PASS="pqs"          # matches includes/config.php; fine on an air-gapped/local box
+SCHEMA="$REPO_ROOT/docs/pqs.sql"
+
+echo "==> Repo root: $REPO_ROOT"
+
+echo "==> Installing php-cli, php-mysql, mariadb-server ..."
+sudo apt-get update -y
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y php-cli php-mysql mariadb-server
+
+echo "==> Starting MariaDB ..."
+sudo service mariadb start || sudo service mysql start
+
+echo "==> Creating database '$DB_NAME' and user '$DB_USER' ..."
+sudo mariadb <<SQL
+CREATE DATABASE IF NOT EXISTS \`$DB_NAME\`;
+CREATE USER IF NOT EXISTS '$DB_USER'@'localhost' IDENTIFIED BY '$DB_PASS';
+GRANT ALL PRIVILEGES ON \`$DB_NAME\`.* TO '$DB_USER'@'localhost';
+FLUSH PRIVILEGES;
+SQL
+
+echo "==> Loading schema from $SCHEMA ..."
+sudo mariadb "$DB_NAME" < "$SCHEMA"
+
+echo "==> Verifying ..."
+php -r 'echo "PHP ".PHP_VERSION." / mysqli ".(extension_loaded("mysqli")?"ok":"MISSING")."\n";'
+mysql -u "$DB_USER" -p"$DB_PASS" "$DB_NAME" -e "SHOW TABLES;" 2>/dev/null
+
+cat <<EOF
+
+==> Done. To serve the app (from the repo root, so URLs keep the /pqs/ prefix):
+
+    cd "$(dirname "$REPO_ROOT")"
+    php -S 0.0.0.0:8080 -t "$(dirname "$REPO_ROOT")"
+
+  then open  http://localhost:8080/$(basename "$REPO_ROOT")/callsign.php
+
+  (The app has some hardcoded /pqs/ redirect URLs; serving the PARENT of the
+   repo means http://localhost:8080/PQS/... resolves those. On /mnt/c the
+   filesystem is case-insensitive so /pqs and /PQS both work.)
+
+  If MariaDB isn't running after a WSL restart:  sudo service mariadb start
+EOF