← All downloads

Installation guide

Install on Linux

Ubuntu, Debian, RHEL / Rocky / AlmaLinux, Fedora. Terminal installer; systemd service.

════════════════════════════════════════════════════════════════
  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://<this-machine-ip>: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:<your-chosen-port>


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
════════════════════════════════════════════════════════════════