Ubuntu and Debian
Installing HWD POS on Ubuntu Server 22.04/24.04 and Debian 12, including installs from the .zip package.
Ubuntu Server 24.04 LTS is the recommended system for HWD POS. Ubuntu 22.04 LTS and Debian 12 are also supported and use the same installer, install-ubuntu.sh.
Recommended: network install
On Ubuntu and Debian the network install detects apt automatically and runs install-ubuntu.sh for you:
curl -fsSL https://3r.com.pa/hwdpos_inst/bootstrap.sh | sudo bashWhat the installer sets up on Ubuntu
| Component | Details |
|---|---|
| Web server | Uses Apache or Nginx, whichever is already installed. If neither is present, it installs Apache. The site configuration points the document root to /var/www/HWDPOS/public. |
| PHP-FPM + CLI | PHP 8.3 by default (PHP_VER=8.2 is also supported), with all the extensions listed in the requirements. |
| MariaDB | Creates the hwd_pos database and the hwdpos_manager user with a generated password, saved in /var/www/HWDPOS/deploy/DB-CREDENTIALS.txt. |
| Printing | CUPS and Google Chrome from its official .deb package (amd64), unless WITH_PRINTING=no. |
| Background services | hwpos-print and hwpos-plugins, enabled at boot. |
| Firewall | Opens the site port in ufw. |
| Server panel | The hwdpanel command. |
| Permissions | The code belongs to the web user www-data, which can write to storage/ and public/uploads/. www-data is added to the lp (USB printers) and lpadmin (IPP queues) groups. |
Why Google Chrome and not chromium-browser
On Ubuntu, chromium-browser is only a bridge to the Snap package. Without snapd (containers, many VPS and LXC setups) the command exists but does not run. That is why the installer installs Google Chrome from its official .deb, and why the summary checks it by running it as the web user rather than looking for the command.
Installing from the .zip package
Use this method when the server has no internet access to download the system, or when your vendor gives you a specific package. Copy the .zip to the server (via USB or SCP) and run the installer for your system family.
The installation scripts are not included in the package. Get them separately and copy them all into the same folder (for example /root/hwdpos-inst/). The installer copies its three companions to /var/www/HWDPOS/deploy/; without them, the background services and hwdpanel are not installed.
| File | Required |
|---|---|
install-ubuntu.sh | Yes. |
install-workers.sh | Yes: installs the two background services. |
hwdpanel.sh | Yes: the server panel. |
check.sh | Recommended: diagnostics and repair. |
Extract the package to /var/www (this creates /var/www/HWDPOS):
cd /var/www && sudo unzip -q /root/HWDPOS-v1.5.0.zipRun the installer, pointing it to the code:
sudo APP_DIR=/var/www/HWDPOS bash /root/hwdpos-inst/install-ubuntu.shRead the final summary and open the address it shows to continue with the setup wizard.
Without APP_DIR, an installer that is not inside the code folder uses /var/www/HWDPOS, and it refuses to work on a system folder (/, /tmp, /var…). If a companion script is missing and the server has no internet, the summary says so and does not offer hwdpanel.
Alternatively, if the server does have internet, bootstrap.sh with HWPOS_ZIP extracts the package and downloads the installer for you:
curl -fsSL https://3r.com.pa/hwdpos_inst/bootstrap.sh | sudo HWPOS_ZIP=/root/HWDPOS-v1.5.0.zip bashActivation needs internet even when the code comes from a .zip.
Customizing the installation
Any installer variable can be placed before the command. For example:
sudo DOMAIN=pos.mystore.com PHP_VER=8.3 WITH_PRINTING=no bash /var/www/HWDPOS/deploy/install-ubuntu.shWith the official .zip, the deploy/ folder is created by the first installation. Before that, use bootstrap.sh with HWPOS_ZIP or the copy in /root/hwdpos-inst/.
Ubuntu-specific notes
- Repository label change. If
apt-get updatefails with a message likeRepository '…ondrej/php…' changed its 'Label' value, the scripts already handle it with--allow-releaseinfo-change. To fix it by hand, runsudo apt-get update --allow-releaseinfo-change. - PHP extension checks. The scripts detect the PHP-FPM version actually in use and check packages with
dpkg -s phpX.Y-<extension>, so the result does not depend on whichphpversion your terminal points to. - Changing the port by hand. See Web server. Running the installer again with
WEB_PORT=is simpler.
Checking the installation
sudo bash /var/www/HWDPOS/deploy/check.shSee check.sh diagnostics.