fix(installer): pre-mark setup wizard complete on successful install#1026
Merged
Lightheartdevs merged 1 commit intoLight-Heart-Labs:mainfrom Apr 27, 2026
Conversation
After a fresh install, the dashboard setup wizard overlays every
route on every page load because routers/setup.py::setup_status
reads ${SETUP_CONFIG_DIR}/setup-complete.json and returns
first_run=true whenever the file is absent. The installer never
wrote it, and it is only written by POST /api/setup/complete at
the end of the wizard — so a user who never clicked through the 6
steps saw the wizard forever.
Write the marker from all three installers (Linux phase 13, macOS
install-macos.sh phase 6, Windows install-windows.ps1 phase 9) after
the success card is shown and services are up. Payload matches the
one written by POST /api/setup/complete: {"completed_at":"<ISO-8601
UTC>","version":"1.0.0"}.
Host path: ${INSTALL_DIR}/data/config/setup-complete.json
Container path: /data/config/setup-complete.json (via the
./data:/data bind mount in docker-compose.base.yml).
Failure to write the marker is non-fatal (logged as a warning);
wizard reappearing is cosmetic. The contract test in
tests/contracts/test-installer-contracts.sh asserts all three
installers emit the write.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
All three installers now write
setup-complete.jsonafter a successful install, so the setup wizard does not reappear on first dashboard load.Why
routers/setup.py::setup_statusreturnsfirst_run=truewhenever${SETUP_CONFIG_DIR}/setup-complete.jsonis absent. The file was only ever written byPOST /api/setup/complete— the final step of the wizard UI. A user who installed normally but never clicked through all six wizard steps saw the overlay on every page load indefinitely.How
Write the marker from all three installers immediately after the success card is displayed and services are confirmed up:
installers/phases/13-summary.sh): added inside theif ! $DRY_RUNblock aftershow_success_card. Usesdate -u +%Y-%m-%dT%H:%M:%SZ(BSD/GNU-safe).installers/macos/install-macos.sh): added in Phase 6 betweenconfigure_perplexicaandshow_success_card, past the dry-run exit at L1051. Uses BSD-safedate -u +"%Y-%m-%dT%H:%M:%SZ".installers/windows/install-windows.ps1): added afterWrite-SuccessCard, wrapped intry/catch. UsesJoin-Path,New-Item -Force,ConvertTo-Json -Compress,Set-Content -Encoding UTF8.tests/contracts/test-installer-contracts.sh): static-grep assertion that all three installers emit the write.Payload matches what
POST /api/setup/completewrites:{"completed_at":"<ISO-8601 UTC>","version":"1.0.0"}Host path:
${INSTALL_DIR}/data/config/setup-complete.jsonContainer path:
/data/config/setup-complete.json(via./data:/databind mount indocker-compose.base.yml).Failure to write the marker is non-fatal — logged as a warning; the worst outcome is the wizard reappearing.
Testing
bash -nclean on Linux and macOS installer files; shellcheck shows no new warnings (reductions only); contract test passes (tests/contracts/test-installer-contracts.sh).${INSTALL_DIR}/data/config/setup-complete.jsonexists with correct JSON.install-macos.sh.install-windows.ps1to completion → same dashboard check → verify file at${INSTALL_DIR}/data/config/setup-complete.json.Platform Impact
install-macos.shPhase 6 writes the marker using BSD-safedate -usyntax.installers/phases/13-summary.shwrites the marker in theif ! $DRY_RUNblock.install-windows.ps1writes the marker via PowerShellSet-Content -Encoding UTF8.Known Considerations
Set-Content -Encoding UTF8under PowerShell 5.1 writes a UTF-8 BOM. This is moot for this use case becauserouters/setup.pyonly calls.exists()on the file path — the file content is not parsed on the read path. PowerShell 7+ writes BOM-free UTF-8 by default.lint-powershell.ymlis the gate.