Skip to content

B-2 · Installing HousingOS and Keeping It Updated

Book B — Agency Administrator Guide · draft v2 (2026-09-11)

Part A — What gets installed where

  • HousingOS (front end) — the program each user runs. The installer places it in C:\HousingOS\ by default, but it can live in any folder (▸ Part E). Beside it sits a Libs\ folder that carries the program icon and the update launcher (Launcher.exe); the launcher keeps itself up to date and HousingOS restores the icon if it goes missing. No admin rights needed for the program itself.
  • Microsoft Access Runtime — required if the workstation has no full Access; the installer detects and installs it (this step elevates).
  • The backend — your agency's single data file on the server (…\HousingOS\Data\‹agency›.accdb or as agreed). Every front end links to it. Back it up (▸ B-14).
  • Word templates — a shared templates folder on the server (▸ B-7).
  • Project folders — a shared Projects folder where each project's numbered subfolders are created (▸ B-8).

Two deployment styles are supported: workstation install (each PC runs its own front end against the shared backend — recommended) or server-hosted (one front end per user on a terminal server). Both use the same backend.

Files beside the program

File What it is Who maintains it
HousingOS.accde The program The installer, then each update
Libs\Launcher.exe The small program that downloads and installs an update Itself — it checks for a newer launcher at the start of every update
Libs\favicon.ico The program icon shown on forms HousingOS itself, at every start
UpdateLog.txt A plain-text log of every update and repair Written automatically
Download\ Holds the previous version as HousingOS_‹version›.bak Written automatically
BackendLocation.txt Which backend this copy points to Set on first launch; never touched by updates

You never need to copy anything into Libs\. The launcher updates itself whenever it runs an update, and HousingOS restores a missing icon at the next start; both note what they did in UpdateLog.txt. If the launcher itself is missing, HousingOS says so when you click Update Now — rerun Setup to put it back.

Part B — Installing on a workstation

  1. Run HousingOS Setup (HousingOS-Setup-‹version›.exe from the download link in your setup PDF). Accept the defaults; the installer places the program, the launcher and the desktop/Start-menu shortcut, and registers the trusted location so Access doesn't block macros.
  2. Launch HousingOS. On first start it asks for the backend: Browse to the agency's data file and click Reconnect ("Please select a valid backend database file." if you pick the wrong file). The location is remembered per workstation in BackendLocation.txt beside the program — don't copy that file between PCs; each PC points itself.
  3. Sign in with the user's HousingOS account (▸ B-3), then Edit User Information ▸ Microsoft sign-in so calendar and email work.
  4. Check icons show on the forms. Blank icons used to mean a missing Libs\favicon.ico; HousingOS now restores that file on start, so if icons stay blank the program folder is probably read-only (▸ Watch-outs).

Part C — Updates

  • HousingOS checks for a new version at every start (comparing its version with the published Version.txt). If one exists the user sees Update available — Update Now downloads the new front end and relaunches; Remind Later postpones. Some releases are forced (no Remind Later) because the backend changed.
  • The update replaces the copy that was running, wherever it is. Nothing else on the PC is touched. The previous version is kept in Download\ beside the program until the next update.
  • The version is in the title bar (e.g. v 2.26.08.07 = year.month.day). Support will ask for it.
  • "Backend update required" (or features that silently do nothing after an update) means the release added tables or columns: run the Backend Updater first — ▸ B-2a — then let the front ends update.
  • Updates never touch your data, templates or project folders.
  • The launcher program updates itself at the start of an update whenever a newer one is published, and a new program icon installs itself the first time a new version starts. There is nothing for you to do for either. The launcher only ever runs when someone clicks Update Now.

Part D — Server-hosted installs

Each user gets their own copy of the front end (never share one .accdb between users); shortcuts open files with the server's default programs, so make sure Word/Excel/PDF associations exist on the server. Web panels (dashboard, maps, portal) need WebView2 on the server. Each user's copy updates itself independently and keeps its own UpdateLog.txt.

Part E — Installing somewhere other than C:\HousingOS

HousingOS works from any folder: a different drive, a per-user folder on a terminal server, or a second copy kept for testing. Everything it needs (icon, download area, log) is created beside the program on first start; only the launcher has to be placed once.

  1. Copy HousingOS.accde into the folder you want, and put Launcher.exe (from any existing install's Libs\ folder, or from Housing Programs) into a Libs\ subfolder beside it.
  2. Add that folder as a trusted location in Access (File ▸ Options ▸ Trust Center ▸ Trusted Locations). The installer does this only for the folder it installs to; a folder you choose yourself needs the entry added once, or Access shows a yellow security bar.
  3. Start the program. The icon and log files are created beside it and the backend prompt runs as in Part B.

Each copy is independent: its own backend pointer, its own updates, its own log. Two copies in two folders can even point at two different backends, which is how a test copy is normally set up.

Watch-outs

  • Never open the backend file directly in Access on a workstation — it locks it for everyone. Use HousingOS.
  • "My change reverted" — someone has a backup copy of the front end open pointing at an old backend, or two backends exist. One backend, one location.
  • Antivirus / web filters can block the update download and the web panels (▸ B-15, A-7). The download comes from housingosfiles.blob.core.windows.net; ask IT to allow it. If antivirus quarantines Libs\Launcher.exe (Norton reports it as IDP.Generic and may quarantine Access along with it), ask IT to restore both, exclude Libs\Launcher.exe, and tell Housing Programs so the file can be submitted to the antivirus vendor as a false positive. The file is code-signed by Housing Programs Software.
  • Trusted location — if Access shows a yellow security bar, the trusted-location entry for that folder is missing; rerun Setup, or add the folder by hand (▸ Part E).
  • Read-only program folder — if UpdateLog.txt shows write FAILED lines, the user cannot write to the folder the program is in. Updates and icon repair both need write access there.
  • Update seems stuck — after Update Now the program closes and a small "Updating HousingOS" window shows the download progress; the new version opens on its own. The very first run of a newly published launcher can pause for up to a minute while antivirus inspects it. If nothing opens after two minutes, send UpdateLog.txt from the program folder to support (▸ B-15).

Screenshot shot list

Shot What
B02-01 Setup wizard first page
B02-02 Reconnect Backend dialog
B02-03 Update available prompt
B02-04 Trust Center ▸ Trusted Locations with a second folder added

Open items for John

  • Confirm the backend file naming you recommend, and whether Runtime install is bundled or a separate download.
  • Is there a Help ▸ About / version screen beyond the title bar?
  • Should the installer offer a "choose folder" page now that any folder works, or stay fixed at C:\HousingOS\?