# InventoryPlus ServiceAgent - Linux End-User Installation & Operational Manual

This manual provides clear, step-by-step instructions for end users and system administrators on how to install, configure, verify, and troubleshoot **InventoryPlus ServiceAgent** on Linux machines (Ubuntu, Debian, Linux Mint, Fedora, Raspberry Pi OS, etc.).

---

## 📋 Prerequisites & Hardware Requirements

Before installing, ensure the Linux system has:
1. **Printer Driver / CUPS Installed**:
   - Ensure your printer (Thermal Receipt Printer, Laser, Inkjet, or Barcode Label Printer) is connected via USB or Local Network.
   - Standard printing service (`CUPS`) must be installed:
     ```bash
     sudo apt-get update
     sudo apt-get install -y cups
     ```
2. **Headless Web Browser for PDF Generation**:
   - InventoryPlus uses a system browser to render bills, invoices, and barcode labels into crisp vector PDFs.
   - Install Chromium or Google Chrome:
     ```bash
     sudo apt-get install -y chromium-browser
     # OR
     sudo apt-get install -y google-chrome-stable
     ```

---

## 🛠️ Step-by-Step Installation Guide

### Option A: One-Command Automatic Installation

1. Copy the `Output_Linux` folder to your Linux computer (e.g., Desktop or Downloads).
2. Open a Terminal inside the `Output_Linux` directory.
3. Run the installer script with root privileges:
   ```bash
   sudo bash install_linux.sh
   ```

The script will automatically:
- Detect whether your system is **Intel/AMD 64-bit (`x64`)** or **Raspberry Pi / ARM64 (`arm64`)**.
- Deploy application binaries to `/opt/inventoryplus/serviceagent/`.
- Register and launch a background `systemd` daemon (`inventoryplus-agent.service`).
- Configure auto-start on system boot and auto-restart on crash.

---

## 🔒 Registering & Trusting the Local HTTPS Certificate

Because web browsers (Chrome, Edge, Firefox) enforce strict security for local communication with PWAs, you must trust the local HTTPS certificate once.

### Step 1: Export the Localhost Certificate
Run the following command in terminal:
```bash
sudo mkdir -p /usr/local/share/ca-certificates/aspnet
sudo dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEM 2>/dev/null || true
```

### Step 2: Update System Certificate Trust Store
```bash
sudo update-ca-certificates
```

### Step 3: Import into Browser Security Database (`NSSDB`)
Linux browsers (Chrome, Edge, Firefox) use their own internal security databases.

1. **Install NSS Security Tools**:
   ```bash
   sudo apt-get install -y libnss3-tools
   ```

2. **Register Certificate for Chrome / Chromium / Edge**:
   ```bash
   certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n "localhost-dotnet" -i /usr/local/share/ca-certificates/aspnet/https.crt
   ```

3. **Register Certificate for Firefox Profiles**:
   ```bash
   for certDB in $(find $HOME/.mozilla/firefox/ -name "cert9.db"); do
       certDir=$(dirname $certDB)
       certutil -d sql:$certDir -A -t "P,," -n "localhost-dotnet" -i /usr/local/share/ca-certificates/aspnet/https.crt
   done
   ```

---

## ✅ Verifying Installation & Service Health

1. **Check Service Status**:
   ```bash
   sudo systemctl status inventoryplus-agent
   ```
   *You should see `Active: active (running)` in green.*

2. **Test Health Endpoint in Web Browser**:
   Open Chrome/Firefox and visit:
   - `https://localhost:9123/healthcheck` (or `http://localhost:9122/healthcheck`)

   *Response:* `{"status":"Healthy","version":"1.0.0"}`

3. **Test Local Printer Discovery**:
   Visit: `https://localhost:9123/print/printers`
   *Response:* List of all connected CUPS printers and raw devices (e.g., `/dev/usb/lp0`).

---

## ⚙️ Service Control Commands

| Task | Command |
|---|---|
| **Check Service Status** | `sudo systemctl status inventoryplus-agent` |
| **Start Service** | `sudo systemctl start inventoryplus-agent` |
| **Stop Service** | `sudo systemctl stop inventoryplus-agent` |
| **Restart Service** | `sudo systemctl restart inventoryplus-agent` |
| **View Live Logs** | `journalctl -u inventoryplus-agent -f` |

---

## 🗑️ How to Uninstall

To cleanly remove ServiceAgent from your Linux machine:
```bash
sudo systemctl stop inventoryplus-agent
sudo systemctl disable inventoryplus-agent
sudo rm -f /etc/systemd/system/inventoryplus-agent.service
sudo systemctl daemon-reload
sudo rm -rf /opt/inventoryplus/serviceagent
```
