# Installation & First-Time Setup

Install the Windows service and tray app, optionally enable HTTPS, and tune configuration in application.properties.

## System requirements

| Requirement             | Minimum                                       |
| ----------------------- | --------------------------------------------- |
| Operating System        | Windows 10 or Windows 11 (64-bit)             |
| Available disk space    | 250 MB                                        |
| Network port            | TCP 9099 must be free                         |
| Privileges              | Administrator account required during install |
| Browser (for dashboard) | Chrome 90+ or Edge 90+                        |

## Installing the Local middleware

1. Grab the latest version of the Nami Local Middleware from the link : [Nami Local Middleware](https://drive.google.com/file/d/1z6Z7M44d_wwY8EriBPo5mA70Uq4pJUcA/view?usp=sharing)
2. Right-click **Nami-Middleware-Setup.exe** and choose **Run as administrator**.
3. Click **Next** through the wizard screens and accept the license.
4. Leave the installation folder as the default (`C:\Program Files (x86)\Nami Middleware`) unless you have a specific reason to change it.
5. Click **Install** and wait — the installer takes about 30–60 seconds while it:
   * Installs a bundled Java runtime (JRE 21) — no separate Java install needed
   * Installs USB drivers for Android-based terminals (Android 9 and 13)
   * Registers and starts the **NamiMiddleware** Windows service
   * Grants the current user permission to start/stop the service without UAC prompts
   * Opens firewall port 9099
   * Launches the tray app in the system tray
6. When the wizard offers to open the Health Dashboard, click **Yes** (or visit `http://localhost:9099` later).

> 📘 The one-time UAC prompt is expected
>
> A UAC prompt appears once when the installer runs. This is normal — the service and firewall rule require admin rights. After installation, daily use does not require admin access.

## HTTPS (optional)

By default the middleware serves plain HTTP on port 9099 — no browser certificate warnings, and no extra setup. Most integrations don't need HTTPS.

If you need HTTPS (e.g. your POS application requires it), open the dashboard at `http://localhost:9099`, go to **Diagnostics → Service Health**, and click **Switch to HTTPS** under the Service card. This:

* Flips `server.ssl.enabled=true` in `application.properties`,
* Generates a self-signed certificate for `localhost` on first use,
* Restarts the **NamiMiddleware** service (\~10 seconds), and
* Reloads the dashboard at `https://localhost:9099`.

After switching, your browser may show "Your connection is not private" the first time:

**Chrome / Edge**

1. Click **Advanced** → **Proceed to localhost (unsafe)**.
2. The warning will not appear again on that browser/machine.

**Postman**

1. Go to Postman **Settings → General**.
2. Turn off **SSL certificate verification**.

> 📘 The self-signed certificate is safe
>
> The certificate is for `localhost` only and never leaves your machine, so it is not a security risk. You can switch back to HTTP at any time using the same toggle.

## The tray app

After installation, a **Nami** icon appears in the Windows system tray (bottom-right corner near the clock).

| Icon colour | Meaning                                 |
| ----------- | --------------------------------------- |
| Green       | Service running — terminal connected    |
| Amber       | Service running — no terminal connected |
| Red         | Service stopped                         |

**Right-click the tray icon** for these options:

| Option          | What it does                                       |
| --------------- | -------------------------------------------------- |
| Open Dashboard  | Opens the health dashboard in your default browser |
| Start Service   | Starts the Windows service if it is stopped        |
| Restart Service | Stops then restarts the service                    |
| Stop Service    | Stops the Windows service                          |
| Exit Tray       | Closes the tray app (service continues running)    |

**Left-click** the tray icon to open the dashboard directly.

The tray app starts automatically when Windows starts (a registry entry under `HKCU\...\Run` is created during install). If you close it, you can relaunch it from the Start menu.

## Upgrading from a previous version

Simply run the new **Nami-Middleware-Setup.exe** as administrator over the existing installation. The installer will:

1. Stop and unregister the old service automatically.
2. Replace the JAR files.
3. Re-register and restart the service.

> 👍 Your settings are preserved
>
> Your `application.properties` configuration file is **not overwritten** during an upgrade.

## Uninstalling

1. Open **Windows Settings → Apps** (or **Control Panel → Programs and Features**).
2. Find **Nami Middleware** and click **Uninstall**.
3. The uninstaller stops the service, removes the SSL certificate from Trusted Root, removes the firewall rule, and deletes all installed files.

> 📘 What uninstall leaves behind
>
> Log files in `C:\Program Files (x86)\Nami Middleware\logs\` and your `application.properties` are not deleted during uninstall.

## Configuration (optional)

The service reads its settings from `application.properties` in the installation folder. You can edit this file in Notepad to change the following:

| Setting                           | Default | Description                                                                                                                                        |
| --------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `server.port`                     | `9099`  | Port the middleware listens on                                                                                                                     |
| `cors.urls`                       | `*`     | Allowed CORS origins for API calls                                                                                                                 |
| `ecr.transaction.timeout.seconds` | `30`    | How many seconds to wait for a terminal response                                                                                                   |
| `simulator.tcp.port`              | `8888`  | Port used by the built-in simulator                                                                                                                |
| `com.reconnect.timeout.minutes`   | `2`     | Minutes a lost COM connection is labeled "Reconnecting..." before switching to "Disconnected" (background auto-reconnect keeps running either way) |

After editing, restart the service from the tray app for changes to take effect.