POS GROVE - installation
=======================

WINDOWS (10, 11, Server 2016 or newer)
  1. Unzip the package (right-click > Extract All). Do not run it from inside the zip.
  2. Double-click install.cmd and allow the administrator prompt.
  3. Answer the questions (press Enter to accept the suggestion in [brackets]).
  4. The browser opens the POS GROVE installation wizard. Finish it there.

LINUX (Ubuntu 20.04+, Debian 12, RHEL/Rocky/Alma 8+, Amazon Linux 2023, SUSE 15)
  1. tar -xzf pos-grove-*.tar.gz   (or unzip the .zip)
  2. cd pos-grove-*                 (the folder that holds install.sh)
  3. sudo sh install.sh
  4. Open the address it prints (http://<this computer>:3200/install) and finish the wizard.

macOS (12 Monterey or newer, Apple silicon or Intel)
  1. Double-click the .tar.gz (or .zip) to unpack it.
  2. Open Terminal, type "cd " (with a space), drag the unpacked folder into the window, press Enter.
  3. sudo sh install.sh
  4. The browser opens the installation wizard. Finish it there.

Unattended install: add --yes (Windows: install.cmd --yes, Linux/macOS: sudo sh install.sh --yes).
Other options: --dir <folder>   install folder (default C:\POSGrove or /opt/posgrove)
               --port <n>       web port (default 3200)
               --mongo-uri <u>  use an existing MongoDB server instead of installing one
               --no-firewall    do not open the firewall port
               --no-browser     do not open the browser at the end


WHAT THE INSTALLER DOES
  - Node.js: uses the copy in this package ("full" packages), or a suitable installed Node.js
    (20 or newer), or downloads Node.js from nodejs.org.
  - MongoDB: uses a MongoDB that is already running; starts an installed but stopped one; otherwise
    installs MongoDB Community Server (from this package or downloaded from mongodb.com) as a
    service that keeps its data in <install folder>/data.
  - Copies POS GROVE to the install folder and runs "npm ci --omit=dev" (needs internet: it
    downloads about 150 MB of packages from registry.npmjs.org).
  - Registers POS GROVE as a service that starts with the computer and restarts if it stops:
      Windows: service "POS GROVE" (PosGrove) and "POS GROVE Database (MongoDB)" (PosGroveMongoDB)
      Linux:   systemd units posgrove and posgrove-mongod (user "posgrove")
      macOS:   launchd daemons com.posgrove.app and com.posgrove.mongod
  - Opens the web port in the firewall (asks first) so tills and tablets on the network can connect.

UPDATING
  Run the installer of the new version. It finds the existing installation, stops POS GROVE,
  replaces the program files and keeps .env (settings), the license, uploads, backups, installed
  extensions and the database. The previous version stays in backend.previous until the next update.
  If anything fails during an update, the previous version is put back automatically.

AFTER INSTALLING (files in the install folder)
  status.cmd / status.sh        is everything running? last log lines
  restart.cmd / restart.sh      restart POS GROVE
  uninstall.cmd / uninstall.sh  remove POS GROVE (asks whether to keep the database and uploads)
  logs\                         setup.log, application and MongoDB logs
                                (Linux: also  journalctl -u posgrove)


IF NODE.JS CANNOT BE INSTALLED AUTOMATICALLY
  Windows: https://nodejs.org/en/download > "Windows Installer (.msi)", 64-bit, LTS. Run it with the
           default options, then run install.cmd again.
  macOS:   https://nodejs.org/en/download > "macOS Installer (.pkg)", or: brew install node@24
  Ubuntu/Debian:  curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
                  sudo apt-get install -y nodejs
  RHEL/Rocky/Alma: curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -
                  sudo dnf install -y nodejs
  Then run the installer again.

IF MONGODB CANNOT BE INSTALLED AUTOMATICALLY
  The installer prints the steps for your system and waits; you can also do it beforehand:
  Windows: https://www.mongodb.com/try/download/community > version 8.0, Windows x64, package "msi".
           Run it, choose "Complete", keep "Install MongoD as a Service" ticked.
  macOS:   brew tap mongodb/brew && brew install mongodb-community@8.0
           brew services start mongodb-community@8.0
  Linux:   https://www.mongodb.com/docs/manual/administration/install-on-linux/
           (install the mongodb-org package, then: sudo systemctl enable --now mongod)
  Older computers: MongoDB 5.0 and newer need a CPU with AVX. Without it, install MongoDB 4.4, or
  use a MongoDB server on another computer and run the installer with --mongo-uri.
  Then run the installer again (or press Enter in the waiting installer).


TROUBLESHOOTING
  "npm ci failed"         No internet or a proxy. With a proxy run, before installing:
                            npm config set proxy http://proxy:8080
                            npm config set https-proxy http://proxy:8080
                          Antivirus can also lock files: pause it and run the installer again.
  Wizard does not open    Run status.cmd / status.sh; open http://localhost:3200/install yourself.
  Another computer cannot connect   Check the firewall rule for port 3200 and use the address shown
                          by the installer (http://<ip>:3200). The setup code it shows is needed when
                          finishing the wizard from another computer.
  Port 3200 in use        Install with --port 3300 (or any free port).

Licenses: Node.js (MIT), MongoDB Community Server (SSPL, see runtime/mongodb), WinSW (MIT).
