Install on web hosting

This page shows how to put POSMaster on a real server so your staff can use it from anywhere. There are two common cases:

• Shared hosting with cPanel (the cheapest and easiest).
• A VPS or dedicated server with Nginx or Apache.

Read Requirements first. Your host must offer PHP 8.2 or newer and MySQL or MariaDB.

Tip: No terminal on your hosting plan? You can still install. Use Install by importing SQL, which only needs phpMyAdmin and a file manager.

#Install on cPanel shared hosting

Tip: No terminal? Use the web installer: upload the files, open the site in your browser and follow the steps. The steps below are the manual way with a terminal.

#1. Choose the PHP version

1. In cPanel, open Select PHP Version (or MultiPHP Manager).
2. Pick PHP 8.2 or 8.3 for your domain.
3. In Extensions, tick pdo_mysql, mbstring, gd, intl, zip, fileinfo and bcmath.

#2. Upload the files

The safest layout keeps the app outside the public web folder. Only the public folder is visible on the internet.

1. Open File Manager.
2. Go to your home folder (for example /home/USER), not public_html.
3. Upload the ZIP of the laravel-project folder, or upload it by FTP. Rename the folder to posmaster so you have /home/USER/posmaster.
4. If you uploaded a ZIP, right-click it and choose Extract.

Note: Make sure the vendor folder arrived. If it did not, you need a terminal to run composer install --no-dev -o.

#3. Point the website to the public folder

You have two options. Use the first one if your host allows it.

Option A: change the document root. In cPanel open Domains (or Addon Domains), edit your domain, and set the document root to posmaster/public. Nothing else to do.

Option B: use public_html.

1. Move everything inside posmaster/public into public_html. Include the hidden file .htaccess.
2. Open public_html/index.php and change the two paths so they point to the app folder:

require __DIR__.'/../posmaster/vendor/autoload.php';
$app = require_once __DIR__.'/../posmaster/bootstrap/app.php';

Also check the line that loads the maintenance file. If it exists in your copy, change it to:

if (file_exists($maintenance = __DIR__.'/../posmaster/storage/framework/maintenance.php')) {
    require $maintenance;
}

Warning: If you install in a sub-folder of public_html, such as public_html/shop, adjust the ../ parts to match. One ../ too many or too few gives a blank page or a 500 error.

#4. Create the database

1. In cPanel, open MySQL Databases.
2. Under Create New Database, type a name and click Create Database.
3. Under MySQL Users, create a user with a strong password.
4. Under Add User To Database, add the user to the database and give it All privileges.

Write down the full names. cPanel adds a prefix, so they look like cpuser_posmaster and cpuser_pos.

#5. Create the .env file

In File Manager, go to posmaster, copy .env.example to .env, and edit it. See Production .env values below for the full list.

#6. Run the installer

If you have a terminal (cPanel Terminal, or SSH), run these in the app folder:

cd ~/posmaster
php artisan pos:install

The installer asks for your Super Admin name, email and password. To load demo data instead, run php artisan pos:install --demo.

Warning: Do not use --demo on a real shop. It wipes the database.

If you have no terminal, follow Install by importing SQL. You import a ready-made database in phpMyAdmin, so no commands are needed.

#7. Check the storage link

The installer creates public/storage, which shows uploaded pictures. If you moved the files into public_html (option B), the link must be recreated there.

• With a terminal: php artisan storage:link works only if the public folder is still the original one. For option B, create the link by hand instead:

ln -s /home/USER/posmaster/storage/app/public /home/USER/public_html/storage

• Without a terminal, ask your host's support to create a symbolic link named storage in public_html that points to posmaster/storage/app/public.

#8. Set permissions

The web server must be able to write to two folders. See Folder permissions.

#9. Add the cron job

See Cron for the scheduler.

#10. Turn on HTTPS

In cPanel, open SSL/TLS Status and run AutoSSL for your domain. Then make sure APP_URL in .env starts with https://.

#Install on a VPS with Nginx

These steps are for Ubuntu 22.04 or newer. Other systems are similar.

1. Install PHP, a database, Nginx and the extensions:

sudo apt update
sudo apt install nginx mariadb-server unzip php8.3-fpm php8.3-mysql php8.3-mbstring php8.3-gd php8.3-intl php8.3-zip php8.3-bcmath php8.3-xml

2. Create the database and a user:

sudo mariadb

CREATE DATABASE posmaster CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'posmaster'@'localhost' IDENTIFIED BY 'use-a-long-random-password';
GRANT ALL PRIVILEGES ON posmaster.* TO 'posmaster'@'localhost';
FLUSH PRIVILEGES;
EXIT;

3. Upload the app to /var/www/posmaster and give it to the web user:

sudo mkdir -p /var/www/posmaster
sudo unzip laravel-project.zip -d /var/www/posmaster
sudo chown -R www-data:www-data /var/www/posmaster

4. Create the Nginx server block /etc/nginx/sites-available/posmaster:

server {
    listen 80;
    server_name shop.example.com;
    root /var/www/posmaster/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;
    charset utf-8;
    client_max_body_size 20M;

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

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

5. Enable it and reload Nginx:

sudo ln -s /etc/nginx/sites-available/posmaster /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

6. Create .env, then run the installer as the web user:

cd /var/www/posmaster
sudo -u www-data cp .env.example .env
sudo -u www-data nano .env
sudo -u www-data php artisan pos:install

#Install on a VPS with Apache

1. Install Apache, PHP and the extensions, and turn on mod_rewrite:

sudo apt install apache2 libapache2-mod-php8.3 mariadb-server unzip php8.3-mysql php8.3-mbstring php8.3-gd php8.3-intl php8.3-zip php8.3-bcmath php8.3-xml
sudo a2enmod rewrite

2. Create the database and user as shown in the Nginx section.
3. Upload the app to /var/www/posmaster.
4. Create /etc/apache2/sites-available/posmaster.conf:

<VirtualHost *:80>
    ServerName shop.example.com
    DocumentRoot /var/www/posmaster/public

    <Directory /var/www/posmaster/public>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/posmaster-error.log
    CustomLog ${APACHE_LOG_DIR}/posmaster-access.log combined
</VirtualHost>

5. Enable the site and reload:

sudo a2ensite posmaster
sudo systemctl reload apache2

6. Create .env and run php artisan pos:install as the web user, as in the Nginx section.

Note: AllowOverride All is needed so the .htaccess file in public can rewrite URLs. Without it, every page except the home page gives a 404 error.

#Turn on HTTPS with Let's Encrypt

HTTPS keeps passwords private and is required for camera barcode scanning on phones and tablets.

On a VPS, use Certbot. Your domain must already point to the server.

sudo apt install certbot python3-certbot-nginx     # for Apache use: python3-certbot-apache
sudo certbot --nginx -d shop.example.com           # for Apache use: --apache

Certbot renews the certificate automatically. After it finishes, set APP_URL=https://shop.example.com in .env and run php artisan optimize.

#Folder permissions

The web server user needs to write to storage and bootstrap/cache. On a VPS:

cd /var/www/posmaster
sudo chown -R www-data:www-data storage bootstrap/cache
sudo find storage bootstrap/cache -type d -exec chmod 775 {} \;
sudo find storage bootstrap/cache -type f -exec chmod 664 {} \;

On cPanel, use File Manager: select storage and bootstrap/cache, choose Permissions, and set 755 (or 775 if you still get errors). Apply to sub-folders too. Never use 777 on a public server.

#Cron for the scheduler

POSMaster has a scheduler. It runs the nightly demo reset on a public demo and any future scheduled jobs. A normal shop does not need it, but it is safe to add. Create one cron entry that runs every minute.

On cPanel, open Cron Jobs and add:

* * * * * cd /home/USER/posmaster && php artisan schedule:run >> /dev/null 2>&1

On a VPS, run sudo crontab -u www-data -e and add:

* * * * * cd /var/www/posmaster && php artisan schedule:run >> /dev/null 2>&1

Note: On some cPanel hosts the PHP command needs a version number, such as /usr/local/bin/ea-php83 instead of php. Ask your host if the cron job does not run.

#Production .env values

Edit .env and set these for a live shop:

APP_NAME=POSMaster
APP_ENV=production
APP_DEBUG=false
APP_URL=https://shop.example.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=cpuser_posmaster
DB_USERNAME=cpuser_pos
DB_PASSWORD=your-database-password

SESSION_DRIVER=database
LOG_LEVEL=error

POS_DEMO_LOCK=false
POS_DEMO_RESET_NIGHTLY=false

If your host runs MySQL on a different machine, ask for the correct DB_HOST. It is often localhost.

#Speed up the app

After the installation and after every change to .env, run:

php artisan optimize

This saves the configuration, routes and views so pages load faster. If you change .env later and nothing happens, run php artisan optimize:clear and then php artisan optimize.

#Final checks

1. Open your address. You should see the sign-in page.
2. Sign in and open Settings → Business. Check the timezone.
3. Upload a logo. If it does not show, check the storage link.
4. Follow First steps after installing.
5. Set up regular backups: Update, backup and restore.