Requirements
What HWD POS installs, which operating systems are supported, and the hardware and network you need.
HWD POS is a native PHP system: it does not use a framework, Composer, Node or Docker. That keeps the installation down to three required components and a few optional ones. The installers set everything up for you; this page explains what each piece is for, so you can plan the server and understand the installer's final summary.
Required components
| Component | Version | What it does in HWD POS |
|---|---|---|
| PHP | 8.2 or later (runs from 8.1, but the setup wizard requires 8.2) | This is the system itself. Two flavors of the same PHP are installed: FPM, which serves the pages the browser opens, and CLI, which runs the two background services (printing and plugins) and maintenance tasks. |
| MariaDB | 10.4 or later (or MySQL 8) | Stores everything: products, stock, customers, quotations, invoices, cash register, credit and the audit log. System updates use ADD COLUMN IF NOT EXISTS, which MySQL 5.x does not understand, so below 10.4 updates fail halfway. |
| Web server | Apache 2.4 or Nginx 1.18+ | Receives requests and hands the application's requests to PHP-FPM. Its document root must point to the public/ folder, never to the project root. |
Why public/ and not the project root
The project folder contains the configuration (with the database password), the backups and the source code. With the document root set to public/, none of that can be reached from the network, even if someone guesses a file name. The installers configure it this way and also explicitly block .env, .sql, .md, .sh and .lock files.
PHP extensions
The installers install all of these. The browser setup wizard checks them again and shows ✓ / ✗ before letting you continue.
| Extension | Required? | What stops working without it |
|---|---|---|
| pdo_mysql | Yes | Nothing works: it is the database connection. |
| mbstring | Yes | Text with accents and ñ gets cut or corrupted (customer and product names, searches). |
| curl | Yes | Everything that goes out to the internet: license activation, update checks, fiscal invoicing, Yappy, SMTP email and the help assistant. |
| zip | Recommended | Installing and updating plugins, applying system updates, importing customers and products from spreadsheets, and exporting to Excel. |
| gd | Recommended | The watermark on A4 documents and the customer's signature on deliveries. |
| xml | Recommended | Reading customer and product import spreadsheets. |
| opcache | Recommended | Nothing breaks, but the system is noticeably slower: every page is recompiled on every request. |
| sodium | Recommended | Verifies the license signature. If it is missing, the bundled fallback is used: it works the same, only slower. |
| pcntl (CLI only) | Recommended | Without it the two background services cannot pick up new code on their own after an update; you have to restart them by hand. |
Optional components
| Component | What it is for | If it is missing |
|---|---|---|
| CUPS | Printing on A4 printers (inkjet or laser) and network printers over IPP/AirPrint. | Thermal printers (ESC/POS, 80 mm and 58 mm) keep working: they do not go through CUPS. |
| Google Chrome (or Chromium) | Rendering the full A4 document (the designed invoice and quotation) to PDF. On Ubuntu/Debian (amd64) the installer installs Google Chrome from its official package, because Ubuntu's chromium-browser is only a bridge to Snap and does not work without snapd, even though the command exists. | Receipt-style printing still works; the designed A4 document cannot be generated. |
| Typesense | Typo-tolerant search across all searches. See Typesense search. | The usual SQL search is used. You do not need to configure it. |
With WITH_PRINTING=no the installer skips CUPS and Chrome/Chromium. Use it on a server that does not print, for example one that only hosts the database.
Background services
The installer leaves two services running:
| Service | What it does | How to check |
|---|---|---|
hwpos-print | Prints, one at a time, the documents the system puts in the queue. | systemctl status hwpos-print |
hwpos-plugins | Runs plugin background work (for example, sending an email to the customer from the server so the cashier does not have to wait). | systemctl status hwpos-plugins |
Both must be active and enabled (start automatically at boot). The installer's final summary checks them.
Supported operating systems
There is one installer per system family, with the same questions, the same modes and the same final summary.
| System | Versions | Installer |
|---|---|---|
| Ubuntu Server (recommended) | 24.04 LTS (recommended), 22.04 LTS | install-ubuntu.sh |
| Debian | 12 | install-ubuntu.sh |
| AlmaLinux | 9 (recommended), 8 | install-almalinux.sh |
| Rocky Linux / RHEL / CentOS Stream | 9, 8 | install-almalinux.sh |
Every system in the table works and ends up equally functional.
Even so, we recommend Ubuntu Server 24.04 LTS, because it is the system HWD POS is mainly configured and tested on. It ships PHP 8.3 in its official repositories, needs fewer manual steps and, if something goes wrong, is quicker to diagnose. The practical rule: if you can still choose the server's operating system, choose Ubuntu. If the server already exists and runs AlmaLinux, Rocky, RHEL or CentOS, install there without worry; it is supported and has its own installer. Read the AlmaLinux notes first.
Not supported: Windows Server (the system relies on systemd services, Linux printing paths and pcntl), and any Linux with PHP older than 8.1.
Hardware
| Minimum | Recommended (store with 3–8 terminals) | |
|---|---|---|
| CPU | 2 cores | 4 cores |
| Memory | 2 GB | 4 GB or more |
| Disk | 20 GB | 40 GB SSD |
| System | 64-bit | 64-bit |
Memory determines how many simultaneous sales the server can handle. The installer sizes the number of PHP processes at about 60 MB per process, with a minimum of 10 and a maximum of 80, and always keeps it below the database connection limit (300). With 2 GB you get about 33 processes; with 4 GB, about 68. You can review and adjust this later in System → Connection capacity (Sistema → Capacidad de conexiones) and with hwdpanel (option 19).
Disk usage grows mostly with three things: database backups, product photos and delivery photos and signatures. 40 GB gives room for years in a typical hardware store.
Virtual machines (Proxmox and similar)
- VM (KVM) or LXC container: an LXC container is lighter, but passing a USB printer into an LXC requires a privileged container plus a bind mount of
/dev/usb/lp0. In a VM you use USB passthrough (in Proxmox: Hardware → Add → USB Device). - Simplest option: network (IP) printers. They avoid USB passthrough entirely: the print service prints over socket 9100 (thermal) or an IPP/AirPrint queue (A4). Recommended for virtualized setups.
- Typical resources for one store: 2 vCPU, 2–4 GB RAM, 20 GB disk.
- Give the VM or container a fixed IP on the LAN so terminals and tablets can reach it.
Network
| Requirement | Details |
|---|---|
| Fixed IP on the local network | Terminals, tablets and printers point to the server by its IP. If it changes, you have to reconfigure them. Set it on the server or reserve it in the router. |
| Outbound internet access | Needed to activate the license, check for updates and send email. The server does not need to be reachable from the internet. |
| Site port open on the LAN | Port 80 by default. See Network install. |
| Port 3306 | Only if the database runs on another server. Open it only to the web server's IP. |
You do not have to publish the server on the internet: everything works on the local network. Publishing it is only needed if you want to access it from outside the store, and in that case you should add HTTPS (for example with Let's Encrypt). The installers do not configure HTTPS.
Before you install
- A clean server running one of the supported systems.
rootaccess or a user withsudo.- Internet access from the server (test with
ping -c2 3r.com.pa). - The activation key and customer code provided by your vendor.
Then continue with the network install.