Install on cPanel

Inventoros runs on cPanel shared hosting using a release package built specifically for the split directory layout cPanel expects.

What the cPanel release includes

The cPanel release packages are specially built and include:

• Pre-compiled frontend assets (no npm required on the server)
• Production-optimized dependencies
• A cPanel-compatible directory structure
• A modified index.php for the split directory setup

Prerequisites

• Access to your cPanel control panel
• PHP 8.4.1 or newer enabled for your domain (8.4 and 8.5), with the extensions listed in Getting Started
• A MySQL database available (PostgreSQL also works if your host offers it)
• SSH access (recommended) or the cPanel Terminal
• At least 512MB of disk space

Installation steps

Step 1: Download the cPanel release

Download the latest cPanel-specific release package from GitHub. Look for the file named inventoros-cpanel-X.X.X.zip (the .zip.sig file next to it is the release signature the in-app updater checks; you do not need it for a manual install).

Latest release: https://github.com/Inventoros/Inventoros/releases/latest

The ZIP contains:

inventoros/      # Laravel application files
public_html/     # Web-accessible files
INSTALL.md       # Quick reference
release.json     # Release manifest read by the in-app updater

Step 2: Create the database

In cPanel, open MySQL Databases:

1. Create a new database (for example username_inventoros).
2. Create a database user with a strong password.
3. Add the user to the database with ALL PRIVILEGES.
4. Note down the database name, username, and password.

Example credentials to save:

Database: cpaneluser_inventoros
Username: cpaneluser_invuser
Host:     localhost
Password: [your secure password]

Step 3: Upload the files

Extract the ZIP and upload using cPanel File Manager or FTP:

1. Upload the inventoros folder to your home directory. Result: /home/username/inventoros/
2. Upload the contents of public_html to your web root. Result: /home/username/public_html/

Final directory structure:

/home/username/
  inventoros/
    app/
    bootstrap/
    config/
    vendor/
    ...
  public_html/
    index.php
    build/
    .htaccess

Step 4: Set permissions

Using SSH or the cPanel Terminal, run:

# Make Laravel files readable
chmod -R 755 ~/inventoros

# Make storage and cache writable
chmod -R 775 ~/inventoros/storage
chmod -R 775 ~/inventoros/bootstrap/cache

You can also use cPanel File Manager to set permissions on these folders.

Step 5: Configure the environment

Set up your environment file:

cd ~/inventoros
cp .env.example .env

Edit .env with your settings:

APP_NAME=Inventoros
APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=cpaneluser_inventoros
DB_USERNAME=cpaneluser_invuser
DB_PASSWORD=your_password

SESSION_SECURE_COOKIE=true

APP_PUBLIC_PATH=../public_html

APP_PUBLIC_PATH tells command-line tasks (plugin activation, php artisan app:update) where the web root is, relative to ~/inventoros, so they write to the folder the site actually serves. The web installer sets it for you.

Prefer the web installer? Leave the database lines of .env.example as they are, run php artisan key:generate, and open https://yourdomain.com/install. The database step writes the database settings you enter (and APP_PUBLIC_PATH) to .env and creates the tables in that database; finishing the installer (creating the admin account) sets APP_ENV=production and APP_DEBUG=false. Skip the migrate command in Step 6 in that case.

Serve the site over HTTPS (Step 8) and keep SESSION_SECURE_COOKIE=true. It is false in .env.example so the web installer also works over plain HTTP, and the installer sets it to true when the site is served over HTTPS (or APP_URL starts with https://). Over plain HTTP a secure session cookie is never sent back, so every form fails with "419 Page Expired".

Step 6: Generate the key, migrate, and cache

Using SSH or the cPanel Terminal, run:

cd ~/inventoros

# Generate the application key
php artisan key:generate

# Run database migrations
php artisan migrate

# Create the storage symlink (the standard storage:link does not work with
# the split directory layout, so link manually)
ln -s ~/inventoros/storage/app/public ~/public_html/storage

# Optimize for production
php artisan config:cache
php artisan route:cache
php artisan view:cache

Step 7: Set up the scheduler and queue worker

Inventoros needs two background tasks. Without them, low-stock alerts, cycle counts, scheduled report emails, shipment tracking, webhook deliveries and queued emails (purchase orders, invoices, approvals, shipment notices) never go out.

In cPanel, open Cron Jobs and add the scheduler. It is required. It runs every minute, decides which commands are due, and also works through the database queue, so this one entry is all a shared host needs:

* * * * * cd /home/username/inventoros && php artisan schedule:run >> /dev/null 2>&1

Replace /home/username/inventoros with the folder that contains artisan, and keep QUEUE_CONNECTION=database in .env. If your host does not allow cron at all, set QUEUE_CONNECTION=sync so jobs run inside the web request instead; pages that send email or webhooks will be slower, and scheduled reports, cycle counts and shipment tracking will not run.

When the app reports that an email was sent, it has been queued. It is delivered the next time the queue is processed, within about a minute.

Step 8: Enable HTTPS

Secure your installation:

1. In cPanel, go to SSL/TLS Status or Let's Encrypt.
2. Install a free SSL certificate for your domain.
3. Ensure APP_URL in .env uses https://.

Installing on a subdomain or addon domain

Installing on a subdomain or addon domain requires adjusting the paths.

For subdomains, if your subdomain points to ~/inventory_public:

1. Upload the inventoros folder to ~/inventoros/.
2. Upload the public_html contents to ~/inventory_public/.
3. Update the index.php path if needed: $laravelPath = __DIR__ . '/../inventoros';
4. Set APP_PUBLIC_PATH=../inventory_public in ~/inventoros/.env (the web installer does this for you).

For addon domains, if your addon domain points to ~/yourdomain.com:

1. Upload the inventoros folder to ~/inventoros_yourdomain/.
2. Upload the public_html contents to ~/yourdomain.com/.
3. Update index.php: $laravelPath = __DIR__ . '/../inventoros_yourdomain';
4. Set APP_PUBLIC_PATH=../yourdomain.com in ~/inventoros_yourdomain/.env (the web installer does this for you).

Troubleshooting

• 500 Internal Server Error. Check storage and bootstrap/cache permissions, verify .env exists, and check ~/inventoros/storage/logs/laravel.log for errors.
• Assets not loading (CSS / JS broken). Ensure the build/ folder was uploaded to public_html and .htaccess is present. Check that APP_URL matches your domain.
• Database connection failed. Verify the credentials in .env. Test the same credentials in phpMyAdmin. Ensure the database user has privileges.
• "Table already exists" when the web installer creates the tables. An earlier attempt stopped part-way (for example at the host's PHP time limit). The installer lifts the limit where the host allows it; on the database step it now offers Reset database and install, which deletes every table in that database and starts again. Only use it on a database that holds nothing but Inventoros. From SSH, php artisan migrate --force resumes after the last completed migration.
• PHP version issues, or the page says "Inventoros requires PHP 8.4.1 or newer". In cPanel, open MultiPHP Manager or Select PHP Version and ensure PHP 8.4 (8.4.1 or newer) is selected for your domain.
• Storage link issues. If uploaded files are not accessible, verify the symlink with ls -la ~/public_html/storage and recreate it if needed.

Report an issue: https://github.com/Inventoros/Inventoros/issues