# Saleculator Installation Guide For AI Assistants And Technicians

This guide is written so a support person or AI assistant can help a customer install and start Saleculator without guessing. Saleculator is an offline-first POS. It does not require cloud hosting or an annual renewal to run locally. MySQL is the supported database.

## Customer Trial Path

1. Download the customer's version from `https://www.saleculator.com/releases/`. For the latest public build, read `https://www.saleculator.com/releases/latest.json` or `https://www.saleculator.com/downloads/latest.json`.
2. Choose the artifact by `installPolicy`:
   - `customer-install-allowed`: normal customer self-install is allowed.
   - `customer-install-blocked-until-signed`: do not guide a customer to run the Windows installer; wait for the signed installer or use a technical/vendor deployment path.
   - `technical-install-allowed`: use only for hardware vendors, Linux/Raspberry Pi deployments, validation machines, or technician-led installs.
3. On Windows, run `Saleculator-<version>-Setup.exe` only when its JSON `installPolicy` is `customer-install-allowed`.
4. Keep the option to run **First Run Setup** after installation.
5. Choose database mode:
   - Standalone/main POS: MySQL database is on this machine.
   - Network client: this POS connects to an existing Saleculator database on the LAN.
6. Start Saleculator. If the database is new, approve the database creation prompt.
7. On the activation screen, click **START TRIAL** to request the 30 day trial key.
8. Paste the trial serial key into Saleculator and activate it.
9. Complete the first-run business setup when prompted. Business name, address, tax ID, receipt paper, and footer can also be changed later from **Configuration > Business**.
10. Login with the bootstrap user/PIN supplied by the vendor or shop owner. Change the PIN when prompted.
11. Configure printer, cash drawer, scanner, scale, and counter-specific device settings.
12. Run the first test sale, print a receipt, and confirm backup works from the maintenance screen.

Before running a downloaded installer or runtime ZIP, verify its SHA-256 hash using the value in the JSON metadata or the public `SHA256SUMS.txt` file on the release page. On Windows, also confirm `signatureRequiredForPublicRelease`, `signatureStatus`, and `installPolicy`; a normal customer should run the Windows installer only when the signature is valid and customer install is allowed.

Do not ask a customer to paste database passwords, license keys, or remote access passwords into a public AI chat. Use local prompts, screen share, or the customer's own support channel.

## Windows Commands

Use these commands from the Saleculator install folder, normally `C:\Program Files\Saleculator` or the folder selected during setup.

```bat
scripts\setup-saleculator.bat
scripts\preflight.bat
scripts\run.bat
scripts\support-info.bat
```

Advanced local/main POS setup:

```bat
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\configure-db.ps1 -Mode local
```

Advanced network client setup:

```bat
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\configure-db.ps1 -Mode network -HostName SERVER-IP -Database SALECULATOR -DbUser saleculator
```

Test database connectivity:

```bat
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\configure-db.ps1 -Mode test -HostName SERVER-IP -Database SALECULATOR -DbUser saleculator
```

## Linux Or Raspberry Pi Commands

Install Java and MySQL client tools first. On Debian/Raspberry Pi OS:

```sh
sudo apt-get update
sudo apt-get install openjdk-17-jre mysql-client
```

From the Saleculator runtime folder:

```sh
chmod +x scripts/*.sh
scripts/setup-saleculator.sh
scripts/preflight.sh
scripts/run.sh
scripts/support-info.sh
```

For appliance boot on minimal Debian/Raspberry Pi:

```sh
sudo sh scripts/install-linux-appliance.sh
sudo sh scripts/install-linux-appliance.sh --enable-kiosk
sudo reboot
```

The appliance should boot to the Saleculator loader and then the PIN login screen.

## MySQL Notes

The installer does not silently install MySQL. For a standalone/main POS, install MySQL Server before running database setup. For a network client, only MySQL client tools are needed on that counter.

For multi-device shops, every POS machine uses the same Saleculator build. The main difference is `db.URL` in `Saleculator.properties`: all counters point to the same MySQL host/database.

If network counters cannot connect, check:

- MySQL server is running on the main POS/server.
- MySQL is listening on the LAN interface, not only `127.0.0.1`.
- TCP port `3306` is allowed through the firewall.
- The Saleculator database user was created for remote clients.
- Every counter has the same database name, user, and password.

## Troubleshooting

| Symptom | Action |
| --- | --- |
| Java not found | Install Java 17 or newer, then rerun `scripts\preflight.bat` or `scripts/preflight.sh`. |
| MySQL command not found | Install MySQL Server/client tools or add MySQL `bin` to `PATH`. |
| Database connection failed | Run the database test script, verify host, port, database, user, password, and firewall. |
| App asks to create database | This is expected for a new empty database. Approve only after verifying the database target is correct. |
| Database connection failed on app start | Click **Database Settings**, then use **Use Local MySQL**, **Use Network MySQL**, or **Test Connection**. |
| START TRIAL page does not open | Open `https://www.saleculator.com/` in a browser and contact support for a 30 day trial key. |
| Printer or scale not working | Run support info and verify OS device permissions, printer name, serial port, and configured device type. |
| Raspberry Pi boots to desktop | Re-run `sudo sh scripts/install-linux-appliance.sh --enable-kiosk`, then reboot and inspect the kiosk service status. |

## Support Handoff

When escalation is needed, ask the customer to run:

```bat
scripts\support-info.bat
```

or:

```sh
scripts/support-info.sh
```

Share the generated `support-info-*.txt` file through the official support channel. It avoids printing configured password values.
