You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit c7582b8
Browse filesBrowse the repository at this point in the historyBrowse files
The CLI test dependencies install into `tests/vendor/`, leaving the main application `vendor/` directory unchanged.
52
52
53
+
On Windows PowerShell, set the Composer config and run the same suite with:
54
+
55
+
```powershell
56
+
Set-Location tests
57
+
$env:COMPOSER = 'composer.cli-tests.json'
58
+
composer install
59
+
Set-Location ..
60
+
php tests/vendor/bin/phpunit -c phpunit.xml.dist
61
+
```
62
+
63
+
CLI or Dashboard UI changes must remain compatible with macOS, Linux, and native Windows. Before submitting such changes, run:
64
+
65
+
```bash
66
+
php bin/qi doctor
67
+
php bin/qi help
68
+
```
69
+
70
+
On Windows, also smoke-test the supplied launcher from PowerShell or Command Prompt:
71
+
72
+
```powershell
73
+
.\bin\qi.cmd help
74
+
```
75
+
76
+
Windows-specific changes should cover drive-letter paths, paths containing spaces, Command Prompt and PowerShell execution, and the `ui:start`/`ui:status`/`ui:stop` lifecycle. GitHub Actions runs the PHPUnit suite and launcher smoke test on native Windows.
77
+
53
78
## :computer: Make something great
54
79
55
80
1. Create a new branch in your repository before doing any work. It should be based off the `develop` branch:
phpBB boards require a web server running PHP and one of the following database management systems.
@@ -59,26 +59,29 @@ phpBB boards require a web server running PHP and one of the following database
59
59
60
60
## QuickInstall CLI
61
61
62
-
QuickInstall now includes a Docker-based CLI for creating local phpBB test boards. It writes generated state to `.qi/` and leaves the legacy web UI unchanged. The QuickInstall CLI requires PHP 8.0 or newer for the `php bin/qi` command.
62
+
QuickInstall now includes a cross-platform, Docker-based CLI and local Dashboard UI for creating phpBB test boards. They work on macOS, Linux, and native Windows and write generated state to `.qi/` without changing the legacy web application.
The QuickInstall CLI targets phpBB 3.2+ installer-based boards. phpBB 3.0/3.1 remain legacy-web-app territory and are not planned for the QuickInstall CLI.
70
77
71
-
Downloaded extensions can be unzipped into `customisations/` and mounted into boards:
78
+
If you prefer a browser workflow, start the QuickInstall Dashboard UI:
72
79
73
80
```bash
74
-
php bin/qi ext:mount test customisations/vendor/extname
81
+
php bin/qi ui:start
75
82
```
76
83
77
-
Downloaded styles can be unzipped into `customisations/` and mounted into boards:
78
-
79
-
```bash
80
-
php bin/qi style:mount test customisations/stylename
81
-
```
84
+
The examples use `php bin/qi`, which works on every supported operating system when PHP is in `PATH`. Windows users can alternatively use `.\bin\qi.cmd` from either Command Prompt or PowerShell.
82
85
83
86
See the complete [QuickInstall CLI docs](docs/sandbox-cli.md).
Copy file name to clipboardExpand all lines: docs/sandbox-cli.md
+155-6Lines changed: 155 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -48,6 +48,44 @@ If you ever need help with commands, run:
48
48
php bin/qi help
49
49
```
50
50
51
+
If you prefer a browser workflow, start the QuickInstall Dashboard UI:
52
+
53
+
```bash
54
+
php bin/qi ui:start
55
+
```
56
+
57
+
Then open the URL printed by the command:
58
+
59
+
```text
60
+
http://127.0.0.1:8079/
61
+
```
62
+
63
+
## Commands by OS
64
+
65
+
The examples in this guide use the portable command form:
66
+
67
+
```bash
68
+
php bin/qi <command>
69
+
```
70
+
71
+
It works on macOS, Linux, and Windows when PHP is available in `PATH`.
72
+
73
+
Windows also includes a `qi.cmd` launcher. From PowerShell:
74
+
75
+
```powershell
76
+
.\bin\qi.cmd <command>
77
+
```
78
+
79
+
From Command Prompt:
80
+
81
+
```batch
82
+
bin\qi.cmd <command>
83
+
```
84
+
85
+
Arguments and options are identical with every launcher. Run commands from the QuickInstall project root. Windows drive-letter paths, UNC paths, backslashes, spaces, and case-insensitive filesystem paths are supported.
86
+
87
+
Docker Desktop on Windows must use its WSL 2 or Hyper-V Linux-container backend rather than Windows containers.
88
+
51
89
## Common Recipes
52
90
53
91
Create a small empty board:
@@ -207,6 +245,12 @@ By default, extension sources must live under `customisations/`. To mount a trus
The QuickInstall Dashboard UI provides a local browser interface for the same workflows exposed by the CLI. It is served by PHP's built-in web server and backed by the same `.qi/` workspace. The Dashboard UI can be started, checked, restarted, and stopped on macOS, Linux, or native Windows.
387
+
388
+
Start the UI:
389
+
390
+
```bash
391
+
php bin/qi ui:start
392
+
```
393
+
394
+
The default URL is:
395
+
396
+
```text
397
+
http://127.0.0.1:8079/
398
+
```
399
+
400
+
Use a different local port:
401
+
402
+
```bash
403
+
php bin/qi ui:start --port 8088
404
+
```
405
+
406
+
Check or stop the tracked Dashboard UI server:
407
+
408
+
```bash
409
+
php bin/qi ui:status
410
+
php bin/qi ui:stop
411
+
```
412
+
413
+
Restart it:
414
+
415
+
```bash
416
+
php bin/qi ui:restart
417
+
```
418
+
419
+
Supported Dashboard UI server hosts are loopback-only:
|`.qi/runtime/ui.json`| Tracked Dashboard UI server state |
438
+
|`.qi/runtime/ui.log`| Dashboard UI server output log |
439
+
|`.qi/runtime/ui.log.err`| Windows Dashboard UI server error log |
440
+
|`.qi/cache/`| Cached update-check metadata |
344
441
345
442
User-managed drop zone:
346
443
@@ -355,13 +452,42 @@ customisations/
355
452
-`board:create` rejects ports already registered to another board or already in use on the host.
356
453
-`ext:mount` and `style:mount` only use `customisations/` unless `--allow-external` is used.
357
454
- Custom Git source URLs require `--allow-external`; only use trusted forks.
455
+
- The Dashboard UI server only accepts loopback hosts (`127.0.0.1`, `localhost`, or `::1`) and rejects non-local requests.
456
+
-`ui:start` refuses ports already in use on the selected loopback host.
457
+
- Dashboard UI form submissions use CSRF tokens and only accept local origins or referrers.
358
458
359
459
## Troubleshooting
360
460
461
+
If QuickInstall starts but a command is not working as expected, run the environment check from the project root:
462
+
463
+
```bash
464
+
php bin/qi doctor
465
+
```
466
+
467
+
On Windows PowerShell, you can use the Windows launcher instead:
468
+
469
+
```powershell
470
+
.\bin\qi.cmd doctor
471
+
```
472
+
473
+
Every check should report `OK`; failures identify the missing or unavailable requirement.
474
+
475
+
#### QuickInstall does not start on Windows
476
+
477
+
First, check whether PHP is available:
478
+
479
+
```powershell
480
+
php --version
481
+
```
482
+
483
+
If Windows does not recognize `php`, install PHP 8 or newer and add the directory containing `php.exe` to the Windows `PATH`. Open a new terminal, confirm `php --version` works, then run `.\bin\qi.cmd doctor` again.
484
+
361
485
#### Docker command fails
362
486
363
487
Check that Docker Desktop is running and that the docker command works in this terminal.
364
488
489
+
On Windows, also confirm Docker Desktop is using Linux containers. `php bin/qi doctor` reports `Linux containers: OK` when configured correctly.
490
+
365
491
#### Composer command fails
366
492
367
493
QuickInstall uses composer from PATH first, then `composer.phar` from the project root. Restore `composer.phar` or install Composer if both are missing.
@@ -383,3 +509,26 @@ Use this when a board's files, database, or generated Docker runtime are no long
0 commit comments