# BuiltPOS Windows Installers

Five signed `.exe` installers. Pick the one that matches what you want to run on the machine — or use the Suite installer if you want everything at once.

## Which installer to download

| Installer | Use when | What gets installed |
|---|---|---|
| **BuiltPOSSuite-X.Y.Z.exe** | One-box dev / demo setup | Pick any combination of the four apps |
| **BuiltPOS-X.Y.Z.exe** | Store terminal | Just the POS transaction terminal |
| **BuiltOFFICE-X.Y.Z.exe** | Back-office PC | Just the store ops + admin console |
| **BuiltAPI-X.Y.Z.exe** | Store server / local API box | Just the Node.js REST API + Windows service |
| **BuiltSync-X.Y.Z.exe** | Legacy MSSQL store | Just the BuiltSync agent (sync to cloud) |

All five share the same auto-update channel — upgrading is hands-off regardless of which one you start with.

## System requirements

- **Windows 10 22H2 or Windows 11** (x64)
- **8 GB RAM** minimum (4 GB for an API-only install)
- **Admin rights** during install (needed for service registration, firewall rules, and the `C:\Program Files` write)
- **Internet access** during install (for optional winget prereqs and the initial Prisma migration on the API)

The installers auto-detect what's missing and tick the right prerequisites for you — you don't need to pre-install Node.js, PostgreSQL, or Visual C++ Redistributable unless you already have them.

## How to install

1. **Download** the `.exe` that matches your role from the release page.
2. **Right-click → Run as administrator.** (Or double-click; you'll get a UAC prompt.)
3. **First screen: Components** — for the Suite installer, tick which apps you want. Standalone installers skip this screen.
4. **Second screen: Prerequisites** — tick any missing system components. Sensible defaults are already applied based on which app(s) you chose:
    - POS / Office: VC++ Redistributable (runtime for Flutter apps)
    - API: Node.js LTS + PostgreSQL 16 (auto-ticked if missing)
    - All: Daily auto-update check (ticked by default — untick to run updates manually)
5. **Install destination**: default is `C:\Program Files\BuiltPOS\`. Change if you want.
6. **Click Install**. The progress bar does three things in sequence:
    - Copies app files (~30 s, depending on disk)
    - Runs winget to install the ticked prerequisites (several minutes if Postgres/Node are fresh)
    - **If you installed the API**: pops up an elevated PowerShell window asking for your `postgres` superuser password (the one you set during PostgreSQL install), then automatically:
      - Creates the `builtpos` database + user
      - Generates a `.env` file with strong random secrets
      - Runs `prisma migrate deploy` to set up the schema
      - Opens Windows Firewall TCP 3000
      - Writes the LAN URL to `C:\ProgramData\BuiltPOS\api-url.txt` so POS + Office terminals on the same network auto-discover it
    - **If you installed BuiltSync**: pops up an elevated console to walk you through the sync config (store ID, cloud API endpoint, local MSSQL connection).
7. **Finish screen**: tick "Launch BuiltPOS" / "Launch BuiltOFFICE" if you want to start the app immediately.

## Verify the install worked

After install, open **Services.msc** and check:

- **BuiltPOS API** (only if you installed the API) — should be "Running", startup "Automatic"

Also:
- `http://localhost:3000/api/health` (API box) — should return `{"status":"ok"}`
- `http://localhost:9847` (BuiltSync box) — should show the BuiltSync dashboard
- POS + Office shortcuts on the desktop should launch with zero config — they auto-discover the local API via `C:\ProgramData\BuiltPOS\api-url.txt`

## Upgrading

You don't need to. Each installer registers a daily Scheduled Task `BuiltPOS\AutoUpdate` that runs at **3:00 AM** as SYSTEM, checks `api3.builtpos.com` for a new version, downloads + verifies SHA256, and runs the upgrade silently. No terminal downtime during trading hours.

To force an immediate update check:
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "C:\Program Files\BuiltPOS\update-check.ps1" -Force
```

Logs: `C:\ProgramData\BuiltPOS\update-check.log`.

To pin a terminal to a version (no auto-updates): `schtasks /Delete /F /TN "BuiltPOS\AutoUpdate"` (admin).

## Uninstalling

**Settings → Apps → BuiltPOS Suite → Uninstall** (or the individual product name for standalone installs).

The uninstaller:
1. Stops + unregisters the BuiltPOS API Windows service (if installed)
2. Removes the daily auto-update Scheduled Task
3. Removes application files from `C:\Program Files\BuiltPOS\`

**NOT removed** (these survive uninstall so you don't lose data):
- `C:\ProgramData\BuiltPOS\` — generated `.env`, API logs, `api-url.txt`, update logs
- PostgreSQL databases (`builtpos` database + its data)
- Installed winget prerequisites (Node.js, PostgreSQL, VC++ Redist) — these came from official sources and stick around

If you want a *clean* uninstall:
```powershell
Remove-Item -Recurse -Force C:\ProgramData\BuiltPOS\
# If you want to drop the DB too (DESTROYS DATA):
# psql -U postgres -c "DROP DATABASE builtpos;"
# psql -U postgres -c "DROP ROLE builtpos;"
```

## Silent install (for fleet deployment)

Every installer supports Inno Setup's standard silent flags:

```powershell
# Full silent install with default preset and no prereq ticks
BuiltPOSSuite-1.0.5.exe /VERYSILENT /NORESTART /SUPPRESSMSGBOXES

# Silent, specific components (Suite only), with Node.js auto-installed
BuiltPOSSuite-1.0.5.exe /VERYSILENT /COMPONENTS="pos,api" /TASKS="nodejs,autoupdate"

# Silent, custom install dir
BuiltPOS-1.0.5.exe /VERYSILENT /DIR="D:\BuiltPOS"
```

**Caveat**: silent API installs skip the interactive postgres password prompt. You'll need to run `configure.ps1` manually after install to create the database:
```powershell
& "C:\Program Files\BuiltPOS\API\configure.ps1"
```

## Troubleshooting

**SmartScreen blocks the installer.** The installer is unsigned until the code-signing cert lands. Click "More info" → "Run anyway". Once we have a cert, SmartScreen will warm up after a few thousand installs.

**Installer says "The API service registration will fail".** You ticked the API but not Node.js, and Node.js isn't on PATH. Either tick the Node.js prereq or install Node.js manually first, then re-run setup.

**API installed but service won't start.** Check `C:\ProgramData\BuiltPOS\API\logs\configure-*.log`. Most common cause: PostgreSQL wasn't reachable when `prisma migrate deploy` ran. Fix the DB, then run `configure.ps1` manually.

**POS / Office can't find the API.** They read `C:\ProgramData\BuiltPOS\api-url.txt` on startup. If the API is on a different PC, create that file manually:
```powershell
# On the POS/Office PC:
mkdir C:\ProgramData\BuiltPOS -Force
'http://<api-pc-ip>:3000' | Out-File -Encoding ASCII C:\ProgramData\BuiltPOS\api-url.txt
```

**BuiltSync dashboard (http://localhost:9847) doesn't load.** Check `Services.msc` for the "BuiltSync" service. If it's stopped, start it. If it's missing, run `"C:\Program Files\BuiltPOS\BuiltSync\builtsync.exe" install-service` from an admin terminal.

**Auto-update never runs.** Check `schtasks /Query /TN "BuiltPOS\AutoUpdate"`. If missing, the task wasn't created — you can re-register it with:
```powershell
schtasks /Create /F /SC DAILY /ST 03:00 /RL HIGHEST /RU SYSTEM /TN "BuiltPOS\AutoUpdate" /TR "powershell.exe -NoProfile -ExecutionPolicy Bypass -File ""C:\Program Files\BuiltPOS\update-check.ps1"""
```

## More docs

- **[AUTO-UPDATE.md](AUTO-UPDATE.md)** — operator runbook for publishing new releases to the update server
- **[BuiltPOSSuite.iss](BuiltPOSSuite.iss)** — Inno Setup source for the unified installer
- **[build-suite.ps1](build-suite.ps1)** — how the `.exe` is built end-to-end
