Middleware installation: technician guide
Prepare an Ubuntu middleware computer, follow the installer stages, and verify the White Water deployment.
Start here
Use this guide for the Ubuntu middleware computer. IT leads the installation and selects the device role, release and site configuration. Site management coordinates lane availability and the handoff. The Galaxy Tab Active5 uses the separate tablet setup guide; do not run these Linux scripts on the tablet.
Already installed? Open the middleware command reference for logs, service checks, updates, certificates and cash commands.
This guide covers the modular Middleware-Installer/nxti.sh installer. The separate nxt-wash-install.sh and jet-install.sh are other entry points with different behavior. Their commands are not interchangeable.
Prepare Ubuntu first
For a new or repurposed PC, follow Flash a computer with Ubuntu 24.04 Desktop first. It covers USB media, the required third-party driver option, clean disk installation and recorded login. Then return here for NXT Wash software and configuration.
Prepare the installation
Have the following ready before starting:
| Item | What IT supplies or confirms |
|---|---|
| Device identity | Organization, site, role and terminal number. These build the hostname. |
| Computer access | The standard Ubuntu username nxtwash, its recorded password and sudo access. Middleware service paths in these scripts commonly assume /home/nxtwash. |
| Software | Full installer repository with its commands, config, lib and steps directories; the NXT Wash-selected middleware release and UIRM branch. |
| Credentials | Approved repository access and the site's environment values, entered locally or retrieved through the installer's Bitwarden prompts. |
| Network | Permanent middleware IP, applicable subnet and the site network plan. |
| Lane hardware | Replacement screen, scanner, recognition equipment and any cash hardware that actually belongs to this device. |
| Existing installation | Record its release and keep protected copies of environment files, application configuration, certificates and any local installer changes before replacement. |
White Water uses a replacement kiosk screen connected by HDMI, USB touch and screen power. Skip optional display-emulation setup when prompted. NXT Wash-related Wi-Fi names end in -N. See the White Water installation playbook for the physical conversion.
Approved browser
Use a Chromium-based browser, including Google Chrome or Chromium, for NXT Wash. Firefox is not approved. Select Chromium when using the installer’s browser option.
Start the modular installer
On the intended middleware computer, place the contents of middleware_installer.sh into /home/nxtwash/nxti.sh, then run:
bash /home/nxtwash/nxti.sh
That small bootstrap installs Git, asks for repository access, clones the full Middleware-Installer tree and starts its nxti.sh. Use the approved repository copy. The flat collection of uploaded helper files is reference material; it is not a replacement for the repository directory structure.
The bootstrap path above and /home/nxtwash/Middleware-Installer/nxti.sh are different files. Once the full repository is present, the latter is the command dispatcher.
Starting nxtwash without a command begins installation or resume work. Use nxtwash help when you only want help. Some prompts default to running the step when you press Enter; answer each prompt deliberately.
The installer can echo credentials while writing configuration and checkpoints. Keep its terminal output, .env, install.env and any configuration captures in the protected technician workspace.
Follow the installation stages
The filenames show the actual stage numbers. Some stages are skipped according to the machine account or the choices you make.
| Stage | What happens | What to decide or check |
|---|---|---|
| 01 · Device information | Detects the OS, collects organization/site/role/number, changes the hostname and collects repository and environment inputs. | Choose the correct machine role and NXT Wash-selected release. Use the site's actual RFID settings if applicable. |
| 02 · System preparation | Offers package updates, upgrades, network lookup repair and desktop changes. | Select only the steps required for this computer. Skip display emulation for White Water's physical screens. |
| 03–05 · Application and environment | Creates ~/POS_SERVER/NXTWashMiddleware, checks out the selected release, installs dependencies and writes .env. |
Confirm the right environment and account. The non-22.04 path asks about changing Python package handling; have IT resolve compatibility for the selected OS. |
| 06 · Recognition data | Supports the Jetson camera-data workflow. | This is a separate device role, not a routine middleware-PC step. |
| 07 · Service | Installs, enables and restarts NXTWashMiddleware.service on the middleware computer. |
Review the startup logs and selected release. |
| 08 · Certificates | Creates the local certificate authority and server certificate, configures nginx and restarts it. | Confirm the permanent IP, included middleware addresses and certificate validity period. |
| 09 · Local kiosk | Installs UIRM, with browser-removal and PM2 autostart choices. | Use where a local kiosk/display application is required; follow the selected device role. |
| 10 · Applications | Offers support tooling, IP scanner and Chromium installation/autostart. | Choose the applications required for the deployment. |
| 11 · Cash | Offers cash middleware installation. | Match the actual Fujitsu, ITL or Genmega hardware; skip on devices without cash equipment. |
| 12 · Ubuntu settings | Adjusts power mode, screen timeout, workspaces, keyboard behavior and optional extensions. | Confirm touch operation and desktop behavior on the replacement screen. |
| 15–16 · Jetson | Offers Rekor Scout installation and writes its ALPR configuration on the Jetson account. | Keep recognition-device commissioning separate from the middleware PC. |
| 99 · Finalize | Offers additional instances/timezone setup, restarts nginx, removes unused packages and the checkpoint, and creates the command alias. | It also disables the daily apt timers and release-upgrade prompts; IT must account for ongoing OS updates. |
Confirm the production release before accepting installer defaults.
Enable and identify the command shortcut
Finalization adds the nxtwash alias to the user's ~/.bashrc. Open a fresh Bash terminal, or reload the correct file:
source ~/.bashrc
type nxtwash
nxtwash help
For this guide, type nxtwash should point to Middleware-Installer/nxti.sh. If it points to the separate single-file installer, its available commands may differ.
If the alias is unavailable but the full modular checkout is present, call the dispatcher directly:
bash /home/nxtwash/Middleware-Installer/nxti.sh help
The alias is written to the user's home .bashrc; use that path if the finalization message displays a different one.
Certificates and tablet access
The certificate helper configures nginx HTTPS port 5443 → local middleware port 5000 and hosts the public CA certificate on HTTP port 80. Confirm the middleware's permanent IP before generating a certificate. If multiple middleware addresses are selected, verify the complete address list.
Use the tablet setup guide to install the appropriate public CA certificate on the Galaxy Tab Active5. The server's private key stays with the technician-managed server configuration.
Replacing an existing CA means clients may need the new CA installed. Plan that change with tablet access in mind. The command reference explains installation and distribution, including a limitation in the standalone distribution command.
Complete the handoff
Check the services and application before returning the lane to the team:
systemctl status NXTWashMiddleware.service --no-pager
systemctl status nginx.service --no-pager
nxtwash logs
Press Ctrl+C to leave the live log view; this does not stop middleware. Use the instance-specific commands in the reference if this computer hosts additional instances.
Confirm the replacement screen's picture and touch input, then verify the lane functions assigned to this device with the installer. For POS, the red Disconnected state under Scanning LP means the app is disconnected from middleware. Any other state in the open POS app means middleware is connected. Use the picture reference to identify it. That indicator establishes the middleware connection; check recognition, payment and wash sending separately where applicable.
Compare middleware log client counts with the devices/client sessions expected for this instance. The zero-client example shows how to spot a missing connection; an unexpectedly high count also needs investigation.
Record the hostname, IP, selected release, instance-to-lane mapping and result of the handoff. Keep secrets out of the site-facing record.
Interrupted installation
The installer saves its last stage and answers in ~/Middleware-Installer/install.env. A later installation run offers to resume. Because the file can contain credentials, treat it as protected configuration.
The manual checkpoint command rewrites the resume marker and immediately launches installation again. It is a recovery tool for IT, not a service check. The menu labels and file-stage numbers differ; use checkpoint details before choosing a starting point.