Testing Guide

On this page

What actually works right now
Prerequisites
Getting the runtime binaries
Running from source
Compiling to a standalone .exe
Test scenarios to try
Reporting what you find

1. What actually works right now

Light Host is early. Being honest about what's finished saves you from testing something that was never wired up in the first place.

Area	Status	Notes
Site registry	Working	Tested. Create, read, update, delete.
Hosts file editing	Working	Tested against a mock file. Only touches its own marked block.
Config generation	Working	nginx blocks and `wp-config.php` render correctly.
CLI commands	Working	All commands parse and dispatch.
Starting nginx / PHP / MariaDB	Untested	Code is written but has never run against real binaries. This is the main thing testers can help with.
Creating a WordPress site	Untested	Depends on the above plus WP-CLI.
Export to live server	Untested	Logic complete; needs a real database to run against.
HTTPS / local SSL	Not built	Planned via mkcert.
Graphical interface	Not built	CLI only for now.
macOS support	Not built	After Windows is solid.

The short version Everything that can be tested without Windows binaries has been tested and passes. Everything that shells out to nginx, PHP or MariaDB is written but unproven — which is exactly where fresh eyes on real machines are most useful.

2. Prerequisites

Windows 10 or 11, 64-bit
Node.js 18 or newer — only needed to run from source or compile the executable
Administrator access — editing the hosts file requires it
Ports 80 and 3306 free. If XAMPP, WAMP, Laragon, IIS or MySQL are already running, stop them first.

Test on a machine you can afford to break This is pre-release software that edits your hosts file and starts database and web server processes. A spare machine or a virtual machine is a much better idea than the laptop your client work lives on.

3. Getting the runtime binaries

Light Host doesn't ship the runtimes inside the repository — that would make it huge. They're downloaded separately into a binaries/ folder.

# clone and install
git clone https://github.com/Successfulsebunya/light-host.git
cd light-host
npm install

The install step fetches WP-CLI automatically and prints instructions for the rest. PHP, nginx and MariaDB are manual for now, because their Windows builds don't have stable download URLs and silently grabbing an unverified binary for a tool that runs with administrator rights is a bad trade.

Place them like this:

binaries/
  php/8.3/        # PHP 8.3 NTS x64, from windows.php.net
  nginx/          # nginx Windows zip, from nginx.org
  mariadb/        # MariaDB Windows ZIP (not the MSI installer)
  wp-cli/         # downloaded for you already

4. Running from source

Open a terminal as Administrator, then:

# start the shared database and web server
npm run cli -- start-engine

# create your first site
npm run cli -- create testsite

# see what exists
npm run cli -- list

If it worked, http://testsite.test loads WordPress in your browser, and http://testsite.test/wp-admin logs in with admin / admin.

5. Compiling to a standalone .exe

To hand Light Host to someone who doesn't have Node.js installed, compile it into a single executable.

# from the project folder, with dependencies installed
npm install
npm run build:exe

That produces dist/light-host.exe. Run it the same way as the CLI, minus the npm wrapper:

light-host.exe start-engine
light-host.exe create testsite
light-host.exe list

The .exe is not the whole program It bundles the Light Host code and Node.js runtime, but not PHP, nginx or MariaDB. Those still need to sit in a binaries/ folder next to the executable. A true single-file installer that carries everything is a later goal.

Building for other platforms

macOS builds can be cross-compiled from the same machine, though the macOS side of the project isn't finished, so they aren't useful yet:

npm run build:exe:all

If the build fails

Antivirus quarantines the output — unsigned executables built this way are often flagged. Add an exclusion for the dist folder.
Templates not found at runtime — the pkg.assets field in package.json controls what gets bundled. If you add new template files, add them there too.
Node version mismatch — the build targets Node 18. If your local Node is much newer and something behaves oddly, that's worth reporting.

6. Test scenarios to try

In rough order of usefulness:

Does the engine even start? Run start-engine and check whether MariaDB and nginx processes appear in Task Manager.
Does site creation complete? Run create testsite and watch for where it fails, if it does.
Does the site load? Open http://testsite.test. If the domain doesn't resolve, check your hosts file for the Light Host block.
Is it actually light? Check memory use in Task Manager with one site running, then with three. Report the numbers — this is the whole premise of the project.
Does stopping a site free resources? Run stop testsite and confirm its PHP process disappears.
Does export produce something usable? Run export testsite --url https://example.com and inspect the SQL and zip. Bonus points for importing them onto a real host.
Does deleting clean up properly? Run delete testsite, then check that the hosts file entry, database and site folder are all gone.
Conflict behaviour. Install alongside XAMPP or Laragon and see how gracefully it fails when ports are taken.

7. Reporting what you find

Open an issue on GitHub. Useful reports include:

Windows version and whether the machine is 64-bit
Node.js version (node -v), or that you used the compiled .exe
The exact command you ran and the full error text
Anything in data/logs/ that looks relevant
Whether other local server software is installed

Reports that it worked fine are just as valuable as bug reports — knowing which Windows versions and hardware are already fine narrows down where the real problems are.