════════════════════════════════════════════════════════════════ Simple Asset Tracker — Windows Desktop Installation Guide ════════════════════════════════════════════════════════════════ DOWNLOAD ──────────────────────────────────────────────────────────────── Latest version: https://downloads.simpleassettracker.com/latest/SAT-Setup-Windows.zip All packages and installation guides: https://simpleassettracker.com/install/ Right-click the downloaded zip → Extract All. Optional — check the download is complete and unmodified: Get-FileHash .\SAT-Setup-Windows.zip -Algorithm SHA256 (PowerShell) The result must match the line for SAT-Setup-Windows.zip in https://downloads.simpleassettracker.com/latest/SHA256SUMS.txt WHAT'S IN THIS PACKAGE ──────────────────────────────────────────────────────────────── SAT-Setup-Windows.zip contains: SAT-Setup.exe Windows desktop installer (GUI) How to INSTALL-Windows.txt This file SYSTEM REQUIREMENTS ──────────────────────────────────────────────────────────────── Supported operating systems: • Windows 10 (64-bit) • Windows 11 (64-bit) • Windows Server 2016, 2019, 2022 or 2025 with Desktop Experience (full GUI installed — if you have Server Core / no desktop, use SAT-Server-Package.zip and How to INSTALL-Windows-Server.txt) Hardware: • 2 GB RAM minimum (4 GB recommended) • 3 GB free disk space on the install drive • 1 GB free disk space on the system temp drive (C:\Windows\Temp) • No internet connection required — all components are bundled • Administrator privileges INSTALL PATH RULES (important): • Maximum path length: 100 characters (node_modules nesting adds ~150 more — Windows limit is 260 total) Good: C:\SAT or D:\SimpleAssetTracker Bad: C:\Users\JohnSmith\AppData\Local\Programs\Company\SimpleAssetTracker • Must be a local drive (C:\, D:\, etc.) • No UNC paths (\\server\share) and no mapped network drives (Z:\) • Paths with spaces, parentheses, and special characters are supported PORT RULES: • Use ports 1024–65535 (ports below 1024 are reserved by Windows) • Frontend and backend ports must be different • Leave at least 3 numbers between them (e.g. 3000 and 4000) (the launcher also reserves frontendPort+1 and frontendPort+2 internally) • Default: frontend 3000, backend 4000 NOT SURE WHICH INSTALLER TO USE? • If SAT-Setup.exe opens a graphical window — use this guide. • If SAT-Setup.exe shows a blank screen or crashes — your machine has no display driver. Use SAT-Server-Package.zip and follow How to INSTALL-Windows-Server.txt instead. INSTALLATION STEPS ──────────────────────────────────────────────────────────────── Step 1 — Run the installer Extract SAT-Setup-Windows.zip (right-click → Extract All), then double-click SAT-Setup.exe in the extracted folder. ── Windows SmartScreen (blue warning dialog) ────────────────── If you see "Windows protected your PC": → Click "More info" → Click "Run anyway" ── Windows Smart App Control (Windows 11 only) ──────────────── Smart App Control may block the file entirely with no "Run anyway" option. Use ONE of the following methods: Method A — Unblock the file (easiest): 1. Right-click SAT-Setup.exe → Properties 2. At the bottom, check the "Unblock" box 3. Click OK 4. Double-click SAT-Setup.exe again Method B — Temporarily disable Smart App Control: 1. Open Windows Settings 2. Go to Privacy & Security → Windows Security 3. Click App & Browser Control 4. Under Smart App Control, select "Off" 5. Run SAT-Setup.exe 6. Re-enable Smart App Control after installation if desired Method C — Run from an elevated Command Prompt: 1. Press Win + X → select "Windows Terminal (Admin)" 2. Type the full path to SAT-Setup.exe and press Enter e.g. "C:\Users\YourName\Downloads\SAT-Setup.exe" Step 2 — Accept the License Agreement Read and accept the license terms to continue. Step 3 — Choose an install location (optional) The default location is: C:\Program Files\SimpleAssetTracker You may change this to any folder — including on a different drive (D:\, E:\, etc.) — as long as the path is under 100 characters and on a local drive. Step 4 — Wait for installation to complete The installer will automatically: ✓ Install Node.js 20 LTS ✓ Extract and configure the application ✓ Set up the database ✓ Build the web interface ✓ Start the application ✓ Configure auto-start on Windows boot This takes approximately 5–10 minutes. Do not close the installer window while it is running. Step 5 — Installation complete When you see "Installation Complete", the app is running. Your browser will open automatically. Re-running the installer (repair / upgrade): You can re-run SAT-Setup.exe at any time. It resumes safely — your existing data and configuration are preserved. ACCESSING THE APPLICATION ──────────────────────────────────────────────────────────────── From this machine: https://localhost:3000 From another machine on the same network: https://:3000 To find this machine's IP address: Open Command Prompt and run: ipconfig Look for "IPv4 Address" under your network adapter. FIREWALL — the installer opens the port for you Setup adds a Windows Firewall rule named "Simple Asset Tracker" that lets phones and computers on the SAME local network reach the app (never the internet). If another device still cannot connect: • It must be on the same network (office Wi-Fi / LAN), not mobile data. • Check the rule exists (PowerShell as Administrator): Get-NetFirewallRule -DisplayName "Simple Asset Tracker" • A company firewall, antivirus firewall or VPN may also block it. ⚠ CERTIFICATE WARNING Your browser will show a security warning because the app uses a self-signed HTTPS certificate. This is normal. To proceed: Chrome / Edge: Click "Advanced" → "Proceed to localhost (unsafe)" Firefox: Click "Advanced" → "Accept the Risk and Continue" Safari: Click "Visit Website" FIRST LOGIN ──────────────────────────────────────────────────────────────── Username: simpleadmin Password: simpleadmin@123 ⚠ Change this password immediately after your first login. Go to: Settings → Users → simpleadmin → Set Password MANAGING THE APPLICATION ──────────────────────────────────────────────────────────────── The application runs as a background service and starts automatically every time Windows boots (no login required). To manage it, open PowerShell as Administrator and run: (default install path shown — substitute yours if you chose a different location during setup) $env:PM2_HOME = 'C:\ProgramData\SimpleAssetTracker\pm2' $pm2 = "C:\Program Files\SimpleAssetTracker\simple-asset-tracker\vendor\node_modules\pm2\bin\pm2" Check status: node $pm2 status View logs: node $pm2 logs simple-asset-tracker Stop: node $pm2 stop simple-asset-tracker Restart: node $pm2 restart simple-asset-tracker Start: node $pm2 start simple-asset-tracker To check that the auto-start task is registered: schtasks /Query /TN "SimpleAssetTracker-PM2" UNINSTALLING ──────────────────────────────────────────────────────────────── BACKUP YOUR DATA FIRST ───────────────────────────────────────────────────────────── All application data lives in one folder: C:\Program Files\SimpleAssetTracker\simple-asset-tracker\backend\data\ (substitute your install directory if you chose a different location) This folder contains: • simple-asset-tracker.db — your SQLite database (all assets, users, audit logs, verification history) • app-config.json — your port and organisation settings Option A — Use the built-in backup feature (recommended): Log in → Settings → Backup → Create Backup This downloads a .zip of the database to your Downloads folder. Option B — Copy the folder manually (PowerShell): Copy-Item -Recurse ` "C:\Program Files\SimpleAssetTracker\simple-asset-tracker\backend\data" ` "C:\SAT-Backup-$(Get-Date -Format 'yyyyMMdd')" To restore after a reinstall: copy the backed-up data\ folder back into the same path inside the new install before starting the application. Also keep a copy of simple-asset-tracker\backend\.env — the saved SAP / Oracle / Zoho passwords are encrypted with a key stored in it. Copy it back over the new install's backend\.env when restoring; without it, re-enter the ERP credentials under Integrations. (Upgrading by re-running the installer keeps all of this automatically.) ───────────────────────────────────────────────────────────── 1. Open PowerShell as Administrator and stop the service: $env:PM2_HOME = 'C:\ProgramData\SimpleAssetTracker\pm2' $pm2 = "C:\Program Files\SimpleAssetTracker\simple-asset-tracker\vendor\node_modules\pm2\bin\pm2" node $pm2 stop simple-asset-tracker node $pm2 delete simple-asset-tracker node $pm2 save --force node $pm2 kill 2. Remove the auto-start task: schtasks /Delete /TN "SimpleAssetTracker-PM2" /F 3. Delete the install folder: Remove-Item -Recurse -Force "C:\Program Files\SimpleAssetTracker" (replace with your chosen install directory if different) 4. Remove the firewall rule the installer added: Remove-NetFirewallRule -DisplayName "Simple Asset Tracker" 5. Remove the PM2 service data: Remove-Item -Recurse -Force "C:\ProgramData\SimpleAssetTracker" 6. Optionally remove Node.js: Windows Settings → Apps → Node.js → Uninstall FORCE RESTART / PARTIAL LAUNCH ──────────────────────────────────────────────────────────────── The application runs three internal services under a single PM2 process (start.js): a proxy, the frontend, and the backend. PM2 may show "online" even when one or more of those services has crashed internally. How to tell if a service is down Check the logs for crash-loop messages: node $pm2 logs simple-asset-tracker --lines 100 Look for lines like: [launcher] x backend is crash-looping - giving up [launcher] x frontend is crash-looping - giving up [launcher] x proxy is crash-looping - giving up Browser shows "connection refused" but PM2 shows "online" The mux proxy (port 3000) may have failed to bind while the frontend is still running on its internal port. Try: https://localhost:3001 If that loads, only the proxy is down — a restart fixes it. Force restart (restarts all three services — safe, no data loss) Open PowerShell as Administrator and run: $env:PM2_HOME = 'C:\ProgramData\SimpleAssetTracker\pm2' $pm2 = "C:\Program Files\SimpleAssetTracker\simple-asset-tracker\vendor\node_modules\pm2\bin\pm2" node $pm2 restart simple-asset-tracker Substitute the path above if you chose a custom install location. Restart from the browser (if the frontend is still reachable) Go to Settings and use the Restart button. This triggers a clean stop-and-start of all internal services without touching your data or configuration. If PM2 itself is unresponsive (process not running at all) Open PowerShell as Administrator and run: $env:PM2_HOME = 'C:\ProgramData\SimpleAssetTracker\pm2' $pm2 = "C:\Program Files\SimpleAssetTracker\simple-asset-tracker\vendor\node_modules\pm2\bin\pm2" Set-Location "C:\Program Files\SimpleAssetTracker\simple-asset-tracker" node $pm2 start start.js --name simple-asset-tracker Decision tree App unreachable? node $pm2 status shows "errored" or "stopped" -> node $pm2 restart simple-asset-tracker Status shows "online" but browser fails -> Try https://localhost:3001 Loads -> proxy port conflict -> restart Fails -> check logs for crash-loop messages backend crash-looping -> check .env, port 4000 frontend crash-looping -> check certs, port 3001 Nothing helps -> node $pm2 stop simple-asset-tracker node $pm2 start simple-asset-tracker TROUBLESHOOTING ──────────────────────────────────────────────────────────────── Windows blocks the installer (Smart App Control / SmartScreen) → See Installation Step 1 above for detailed workarounds. → Enterprise machines managed by IT: ask your IT administrator to whitelist SAT-Setup.exe via Group Policy or Intune. "Install path is too long" error → Choose a shorter install path (e.g. C:\SAT or D:\SAT). → Paths over 100 characters cause failures deep in node_modules. "UNC/network paths are not supported" error → The install path must be on a local drive (C:\, D:\, etc.). → Network drives (\\server\share or mapped Z:\ drives pointing to a network share) are not supported — SQLite and PM2 do not work reliably over network file systems. "Mapped network drive" error → Same as above — even if the drive shows a letter (Z:\), if it points to a network share it will not work. → Choose a path on a physical local drive instead. "Ports below 1024" or "ports are adjacent" error → Choose ports between 1024 and 65535. → Frontend and backend must be different and at least 2 apart. → Default recommendation: frontend 3000, backend 4000. App won't open in browser → Make sure the service is running: node $pm2 status → Try restarting: node $pm2 restart simple-asset-tracker → Check logs for errors: node $pm2 logs simple-asset-tracker Other machines on the network cannot reach the app → See FIREWALL in ACCESSING THE APPLICATION (the installer adds the rule). → Confirm the service is running locally first. Port already in use → The installer only stops earlier Simple Asset Tracker processes. If another program holds a port, it names that program and leaves it running. Stop that program, or go back in the installer and choose different ports (for example 3100 and 4100). SAT-Setup.exe shows a blank screen or crashes immediately → Your machine has no graphical display driver. → Use the server installer instead: extract SAT-Server-Package.zip and follow How to INSTALL-Windows-Server.txt. nvm-windows warning during install → nvm may reactivate an older Node.js version after reboot, causing the application to fail to start. → Open an admin terminal and run: nvm use 20.18.3 → Then restart the SAT service. App does not start after Windows reboot → Check the auto-start task exists: schtasks /Query /TN "SimpleAssetTracker-PM2" → If missing, re-run SAT-Setup.exe to re-register it. Installer fails midway → Re-run SAT-Setup.exe — it resumes safely and preserves your data. → If you need to delete the install folder and start fresh: First back up: C:\Program Files\SimpleAssetTracker\simple-asset-tracker\backend\data\ Then delete the install folder and re-run. Forgot the master admin password → Open: https://localhost:3000/reset-master-password → Enter your application license key and set a new password. Need help? → Contact your software vendor for support. ════════════════════════════════════════════════════════════════ Simple Asset Tracker — simpleassettracker.com ════════════════════════════════════════════════════════════════