Web server

The installers configure the web server for you: they use Apache or Nginx if one is already installed, and install Apache if there is none. This page explains what they set up, for manual installations (for example on a control panel) or if you need to adjust something.

RequirementsCopy Anchor Link

• Apache 2.4 or Nginx 1.18+.
• PHP-FPM 8.2 or later, reached through its socket.
• The document root pointing to the public/ folder.
• All requests that are not a file routed to public/index.php (front controller).

Why public/ and not the project rootCopy Anchor Link

The project folder contains the configuration with the database password, the backups and the source code. With the document root on public/, none of that is reachable from the internet, even if someone guesses a file name.

As an extra layer, the configuration explicitly blocks files ending in .env, .sql, .md, .sh and .lock.

Reference configurationCopy Anchor Link

Replace the project path and the PHP-FPM socket with your own. The files are also available in the project as deploy/nginx-hwpos.conf and deploy/apache-hwpos.conf when the deploy/ folder is present.

server {
    listen 80;
    server_name _;                      # or your domain: pos.mystore.com
    root /var/www/HWDPOS/public;        # the project's public/ folder
    index index.php;
    client_max_body_size 32M;

    # Front controller: everything goes through public/index.php.
    location / { try_files $uri $uri/ /index.php?$query_string; }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;   # your PHP-FPM socket
        fastcgi_read_timeout 120;
    }

    # Block credentials, backups and source code (never serve them).
    location ~* \.(env|sql|md|sh|lock)$ { deny all; }
    location ~ /(storage|database|scripts|app|config)/ { deny all; }
    location ~ /\.(?!well-known) { deny all; }
}

On a control panel with Nginx (aaPanel / BaoTa), the only rewrite rule you need is:

location / { try_files $uri $uri/ /index.php?$query_string; }

Writable foldersCopy Anchor Link

The system writes to storage/ (configuration, license, backups, logs) and public/uploads/. Both must belong to the web server user: www-data on Ubuntu/Debian, apache on AlmaLinux, usually www on aaPanel/BaoTa.

sudo chown -R www-data:www-data /var/www/HWDPOS

On AlmaLinux, SELinux must also allow writing; re-run install-almalinux.sh rather than fixing it by hand. See AlmaLinux.

Changing the portCopy Anchor Link

The installer asks for the port (80 by default) and changes four things together: the VirtualHost (or Nginx listen), the server's Listen directive (the one usually forgotten, which leaves the site not listening), the firewall and the addresses in the final summary.

The simplest way to change it after installing is to re-run the installer with WEB_PORT=. It is safe to re-run and does not delete data.

To do it by hand:

sudo sed -i 's/<VirtualHost \*:80>/<VirtualHost *:8080>/' /etc/apache2/sites-available/hwpos.conf
sudo sed -i 's/^Listen 80$/Listen 8080/'                  /etc/apache2/ports.conf
sudo apache2ctl configtest && sudo systemctl restart apache2
sudo ufw allow 8080/tcp

Ports 22 (SSH), 3306 (MariaDB) and 8108 (search) are already used by the system and must not be used for the website.

Terminals and tablets must use the address with the port included (for example http://192.168.1.50:8080/). HWD POS itself needs no change: its internal links are relative.

HTTPSCopy Anchor Link

Publishing the server on the internet is not required: everything works on the local network. If you want to access it from outside the store, add HTTPS (for example with Let's Encrypt). The installers do not configure HTTPS; set it up on your web server or reverse proxy.