════════════════════════════════════════════════════════════════ Simple Asset Tracker — Linux 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 Linux and macOS. Optional — check the download is complete and unmodified: sha256sum 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-Linux.txt This file SYSTEM REQUIREMENTS ──────────────────────────────────────────────────────────────── • Ubuntu 20.04+, Debian 11+, RHEL / Rocky / AlmaLinux 9 (SELinux enforcing is supported), Fedora 38+, or equivalent • 2 GB RAM minimum (4 GB recommended) • 2 GB free disk space • tar (pre-installed on all supported distributions) • 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 a terminal Press Ctrl+Alt+T, or search for "Terminal" in your applications menu. Step 2 — Extract the package In the folder you downloaded it to, run: cd ~/Downloads tar xzf SAT-Mac-Package.tar.gz This creates a SAT-Mac-Package folder containing the installer script (install.sh), the bundled application (app-source.tar.xz) and these guides. Keep them together in that folder. Step 3 — Navigate to the extracted folder Replace the path below with where you extracted the files: cd ~/Downloads/SAT-Mac-Package Step 4 — Make the installer executable chmod +x install.sh Step 5 — 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 6 — 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 ~/Downloads/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: Run: ip addr show or: hostname -I Firewall: if firewalld (RHEL, Rocky, AlmaLinux, Fedora) or ufw is running, the installer opens the port for you. Other firewalls, and cloud security groups, must allow TCP port 3000 separately. ⚠ 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" 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 a terminal, navigate to the folder where you ran install.sh, then run: cd ~/Downloads/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/Downloads/SAT-Mac-Package/simple-asset-tracker/vendor/node_modules/pm2/bin/pm2\""' >> ~/.bashrc source ~/.bashrc 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 ~/Downloads/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: node "$PM2" unstartup PM2 will print a command such as: sudo env PATH=$PATH:/usr/bin pm2 unstartup systemd -u yourname --hp /home/yourname Copy that exact command and run it with sudo. 3. Close the port the installer opened (only the one you use): sudo firewall-cmd --permanent --remove-port=3000/tcp && sudo firewall-cmd --reload sudo ufw delete allow 3000/tcp 4. 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. Node.js installed but not in PATH after install → Close the 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 (or: ss -ltnp | grep 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 ════════════════════════════════════════════════════════════════