Point a vhost at public/, open the URL, and follow three screens. Anything not ready to serve lands here: no configuration, half a configuration, or a configuration with no way to sign in. Loghound never answers a request by printing a configuration error and stopping.
Both call the same code in src/Setup/ to decide which log files to read, how to grade a format, how to provision the indexes, what a valid password is and what happens next — so a configuration written by one is indistinguishable from one written by the other. You can start in the browser and finish in the shell, or the reverse.
The shell installer hands over to the shell wizard by default. Pass --skip-setup to stop once the machine is ready and configure here instead; the final report then prints the URL and the command that reads the setup token.
sudo ./install/install.sh --skip-setup
Each one writes its answers straight into config/loghound.php as you go. There is no hidden wizard state: reload, change browser, or switch to the shell wizard, and you pick up exactly where you were.
Figure 1 — the installer flow. The status page is readable without the token, deliberately, because you have to be able to see a permission problem in order to fix it; nothing can be saved until the token is entered.
1 · Access logs
Loghound works out the format in three rungs, in this order: from your web server configuration, then by scoring real lines against the built-in format library, then by proposing a pattern generated from your log. Whichever rung it lands on, you see the file, where the format came from, the confidence percentage, the token-to-field mapping, and five real lines rendered as parsed records.
If a value is in the wrong column, the format is wrong, and confirming it would fill your index with nonsense. Nothing is ever ingested with a silently guessed format. The screen also lists what your format does not log and what each gap costs you — the rules that will stay silent. The recommended LogFormat closes all of them.
You can also name a file by hand. It must sit inside allowed_log_roots (/var/log by default); the installer refuses anything outside it and will not widen that list for you, because it is a security control. A custom pattern is checked for catastrophic backtracking before it is stored, not the first time the daemon meets a hostile line.
2 · Storage
One answer: Loghound provisions and manages its own two indexes on your Opensolr account. Enter the account email and the API key, and the installer reads your account once and shows you three things before you choose anything — how many indexes it holds and how many the plan allows, the pairs already on the account that you can join instead, and anything left over from a run that stopped half way.
3 · Sign-in
A username and a password of at least ten characters, stored as a hash, plus the choice between the browser’s own password prompt and Loghound’s own sign-in page. Both are real options with a real trade-off rather than a default you discover later — signing in has the comparison. You can change the mode later without setting the password again.
Finishing takes you to the dashboard, which then asks you to sign in for the first time.
Provisioning two Opensolr indexes takes tens of seconds, and PHP-FPM will not hold a request open that long. So the slow parts — credential checks, index creation, configset uploads, connectivity tests and log detection — run as jobs: a list of small named steps whose state lives in var/setup/. The browser advances them a budget at a time and polls, so you see which step is running, how long it has been going and what it is doing.
- Refreshing mid-provision reattaches to the running job rather than starting a second one. Two indexes are never created because somebody double-clicked.
- “Try again” starts a new job, it does not resume the failed one. That is safe because every step is idempotent against work an earlier attempt did: index creation finds the name already taken, asks Opensolr whether your account is the one holding it, and reuses it; configset upload simply re-uploads and reloads. So a retry shows every step running again with most of them saying “already done”.
- If Opensolr cannot be reached at the moment the retry needs to ask who owns a name, the step stops with that as the reason and changes nothing. Guessing wrong there is what abandons an index you are paying for.
These screens need JavaScript and say so. The shell wizard runs the identical steps with no JavaScript involved.
The moment config/loghound.php exists, carries a username and a password hash, and names both indexes, every installer route is dead and the panel serves instead. There is no flag, no query parameter and no “re-run setup” button that gets past that check.
It runs before authentication, so anything that makes it true hands an unauthenticated visitor the installer. It therefore depends only on facts that mean “setup never finished”. It used to ask the configuration validator instead — which reports an error for a log directory it cannot resolve, the normal state of a panel process under open_basedir — so a correctly installed instance looked unconfigured forever and re-minted a live setup token on a machine where it had already been destroyed. Configuration problems that are not “setup never finished” show up as a warning banner inside the panel instead.
To change something afterwards, use Settings in the panel, or re-run bin/loghound-setup, where every prompt defaults to the current value. Deleting config/loghound.php brings the installer back with a fresh token — a deliberate escape hatch that needs shell access twice over. Resetting without deleting anything is the reinstall button.