════════════════════════════════════════════════════════════════ Simple Asset Tracker — macOS Installation Guide ════════════════════════════════════════════════════════════════ DOWNLOAD ──────────────────────────────────────────────────────────────── Latest version: https://downloads.simpleassettracker.com/latest/SAT-Mac-Package.tar.gz All packages and installation guides: https://simpleassettracker.com/install/ The same package installs on macOS (Apple Silicon and Intel) and Linux. Optional — check the download is complete and unmodified: shasum -a 256 ~/Downloads/SAT-Mac-Package.tar.gz The result must match the line for SAT-Mac-Package.tar.gz in https://downloads.simpleassettracker.com/latest/SHA256SUMS.txt WHAT'S IN THIS PACKAGE ──────────────────────────────────────────────────────────────── SAT-Mac-Package.tar.gz Distribution archive install.sh Installer script app-source.tar.xz Bundled application How to INSTALL-macOS.txt This file SYSTEM REQUIREMENTS ──────────────────────────────────────────────────────────────── • macOS 12 Monterey or later (Intel or Apple Silicon) • 2 GB RAM minimum (4 GB recommended) • 2 GB free disk space • tar (pre-installed on macOS) • Node.js 20+ is installed automatically if not present • sudo access required for Node.js installation • Install path must be on a local filesystem — NFS, SMB, AFP, and other network mounts are not supported (SQLite locking issues) INSTALLATION STEPS ──────────────────────────────────────────────────────────────── Step 1 — Open Terminal Finder → Applications → Utilities → Terminal Step 2 — Extract the package into your home folder Run: cd ~ tar xzf ~/Downloads/SAT-Mac-Package.tar.gz This creates ~/SAT-Mac-Package containing the installer script (install.sh), the bundled application (app-source.tar.xz) and these guides. Keep them together in that folder. Use your home folder — not Downloads, Desktop or Documents. macOS blocks background services from those three folders, so an app installed there can fail to start after a restart. (If you double-clicked the file in Finder instead, move the resulting SAT-Mac-Package folder into your home folder before continuing.) Step 3 — Navigate to the extracted folder Replace the path below with where you extracted the files: cd ~/SAT-Mac-Package Step 4 — Remove macOS quarantine flags macOS marks files downloaded from the internet as quarantined and Gatekeeper may block them. Run this once to clear the flags: xattr -d com.apple.quarantine SAT-Mac-Package.tar.gz 2>/dev/null || true xattr -d com.apple.quarantine install.sh 2>/dev/null || true xattr -d com.apple.quarantine app-source.tar.xz 2>/dev/null || true Step 5 — Make the installer executable chmod +x install.sh Step 6 — Run the installer ./install.sh You'll be asked which folder to install into (press Enter to accept the default, or type a different path). The installer will automatically: ✓ Check for required tools (tar) ✓ Install Node.js 20 LTS if not already present ✓ Extract and configure the application (PM2 process manager is bundled — no separate install needed) ✓ Set up the database ✓ Build the web interface (if not pre-built — first run only) ✓ Start the application ✓ Configure auto-start on system boot This takes approximately 5–10 minutes on a fresh system (the main step is building the web interface on first run). Do not close the Terminal while it is running. Step 7 — Installation complete When installation finishes you will see: "Simple Asset Tracker is running!" Your browser will open automatically. Re-running the installer (repair / upgrade): To upgrade, download the new SAT-Mac-Package.tar.gz, extract it in the same place as before (it replaces install.sh and the app archive), then run it again from ~/SAT-Mac-Package: chmod +x install.sh && ./install.sh The new version replaces the application files; your data, settings, saved ERP connections, sign-ins and HTTPS certificate are kept. If the upgrade fails part-way, the previous version is put back and restarted automatically. Re-running with the same package repairs a damaged install the same way. 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: System Settings → Network, or run: ipconfig getifaddr en0 Firewall: if the macOS firewall is switched on, the installer allows Node.js to accept connections so phones can reach the app. ⚠ 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 via the bundled PM2 process manager. It starts automatically every time the system boots. To manage it, open Terminal, navigate to the folder where you ran install.sh, then run: cd ~/SAT-Mac-Package # wherever you ran install.sh PM2="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 Tip — set a permanent alias so you can run these from anywhere: echo 'alias sat-pm2="node \"$HOME/SAT-Mac-Package/simple-asset-tracker/vendor/node_modules/pm2/bin/pm2\""' >> ~/.zshrc source ~/.zshrc sat-pm2 status To open the app again at any time: Open your browser and go to https://localhost:3000 CUSTOM PORT (OPTIONAL) ──────────────────────────────────────────────────────────────── The installer asks which folder to install into, then (on a fresh install) the setup wizard asks for port numbers. The defaults are: Frontend (browser): 3000 Backend API: 4000 If port 3000 is in use on your system, enter a different port number when prompted (e.g. 8080 for frontend, 8084 for backend). Leave at least 3 numbers between frontend and backend ports — the launcher also uses frontendPort+1 and frontendPort+2 internally. The wizard only appears on a fresh install (when no .env file exists yet). On subsequent runs it is skipped — existing config is preserved. After changing ports, access the app at: https://localhost: UNINSTALLING ──────────────────────────────────────────────────────────────── BACKUP YOUR DATA FIRST ───────────────────────────────────────────────────────────── All application data lives in one folder (relative to wherever you ran install.sh): simple-asset-tracker/backend/data/ 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 (Terminal): cp -r simple-asset-tracker/backend/data \ ~/SAT-Backup-$(date +%Y%m%d) To restore after a reinstall: copy the backed-up data/ folder back into the same path inside the new install before starting the app. 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 install.sh keeps all of this automatically.) ───────────────────────────────────────────────────────────── 1. Stop and remove the PM2 process: cd ~/SAT-Mac-Package # wherever you ran install.sh PM2="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 configuration (the installer registers it as a boot-time service so the app starts without anyone signing in): sudo launchctl bootout system/com.PM2 2>/dev/null sudo rm -f /Library/LaunchDaemons/pm2.$(whoami).plist 3. Delete the application folder: rm -rf simple-asset-tracker 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 Navigate to the folder where you ran install.sh, then: PM2="simple-asset-tracker/vendor/node_modules/pm2/bin/pm2" 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) Navigate to the folder where you ran install.sh, then: PM2="simple-asset-tracker/vendor/node_modules/pm2/bin/pm2" node "$PM2" restart simple-asset-tracker 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) Navigate to the folder where you ran install.sh, then: PM2="simple-asset-tracker/vendor/node_modules/pm2/bin/pm2" cd 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 ──────────────────────────────────────────────────────────────── 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 "permission denied" running install.sh → Run: chmod +x install.sh then try again. macOS Gatekeeper blocks the script or files The installer auto-removes quarantine flags, but if macOS still blocks it, use one of these methods: Method A — Remove quarantine via Terminal (recommended): xattr -d com.apple.quarantine install.sh xattr -d com.apple.quarantine app-source.tar.xz Then run ./install.sh again. Method B — Allow via System Settings: macOS 13+ (Ventura / Sonoma): Apple menu → System Settings → Privacy & Security → Scroll down to the Security section → You will see "install.sh was blocked..." → Click "Allow Anyway" → enter your password macOS 12 (Monterey): Apple menu → System Preferences → Security & Privacy → General tab → Click "Allow Anyway" Method C — Right-click to open: Right-click install.sh in Finder → Open → Click "Open" in the dialog that appears Enterprise Mac (MDM / company-managed): Ask your IT administrator to approve the script via your organisation's MDM profile (Jamf, Intune, etc.). Node.js installed but not in PATH after install → Close Terminal and open a new one, then re-run ./install.sh Port already in use → The installer only stops earlier Simple Asset Tracker processes. If another program holds a port, the installer stops, names it and leaves it running: stop that program, or change FRONTEND_PORT and PORT in simple-asset-tracker/backend/.env and run ./install.sh again. To see what holds a port after install: lsof -i :3000 Identify the blocking process and stop it, then restart SAT: node "$PM2" restart simple-asset-tracker Install path is on a network drive (NFS / SMB / AFP) → SQLite locking and PM2 startup do not work reliably over network file systems. Install to a local path (e.g. ~/SAT). Installer fails midway → Re-run ./install.sh — it resumes safely and preserves your data. → If you need to delete the app folder and start fresh: First back up: simple-asset-tracker/backend/data/ Then: rm -rf simple-asset-tracker and re-run ./install.sh 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 ════════════════════════════════════════════════════════════════