Documentation

Before you start

Rafnivo runs on a PHP/MySQL hosting environment. The installer checks the server before creating any tables.

Use the folder containing index.php as the application root. A domain, subdomain or subfolder is supported. Keep the folder structure intact.

If vendor/autoload.php is missing, install PHP dependencies using the command below. If your host has no terminal, prepare vendor/ on a compatible PHP 8.2 machine and upload it.

composer install --no-dev --optimize-autoloader

Node.js is needed only on a development/build machine when rebuilding browser assets. A normal installation can use the included built assets.

Configure .env.php

Copy .env.example.php to .env.php in the application root, then edit the copy in a text editor. This file holds settings that change between your computer and your hosting server, so you do not need to edit application code.

It is a PHP file returning an array, not a plain KEY=value file. Keep quotes, commas and the final ];. Edit these entries in the copied file; retain its other entries.

<?php
return [
    'DEBUG' => false,
    'APP_NAME' => 'Rafnivo',
    'APP_URL' => 'https://example.com/rafnivo',
    'TIMEZONE' => 'Africa/Cairo',
    'LANGUAGE' => 'en',
    'LOCALE' => 'en_US',
    'ALLOW_REGISTRATION' => false,
    'DB_CONNECTION' => 'mysql',
    'DB_HOST' => '127.0.0.1',
    'DB_PORT' => '3306',
    'DB_NAME' => 'your_database',
    'DB_USER' => 'your_database_user',
    'DB_PASSWORD' => 'your_database_password',
    // Keep the remaining mail settings from .env.example.php.
];

'MAILER_METHOD' => 'smtp',
'MAIL_HOST' => 'smtp.example.com',
'MAIL_PORT' => '587',
'MAIL_SECURE' => 'tls',
'MAIL_USERNAME' => 'your_smtp_user',
'MAIL_PASSWORD' => 'your_smtp_password',
'MAIL_FROM_NAME' => 'Your Store',
'MAIL_FROM' => 'noreply@example.com',
'MAIL_DEBUG' => 0,
'MAIL_ALLOW_SELF_SIGNED' => false,

Validate the file with php -l .env.php. Keep your real environment file private, out of the public download package and version control. Do not replace it with the example during an upgrade.

Run the setup wizard

Open https://example.com/rafnivo/install, replacing the base address with yours. The wizard has three main stages; Configure contains three small steps.

1. Requirements

All checks must show Ready. If the database check fails, correct DB_* in .env.php first. Choose Continue to database.

2. Database

Choose Create database tables on a new, empty database. Setup creates the schema and records the bundled migrations; no manual SQL import is needed.

3a. Installation mode

Choose your language. Use Start with an empty system for your own business, or Import demo data to explore sample data. Click Next: Site & company.

3b. Site & company

Fill in site name, company name, description, email, phone and address. Choose country, currency and barcode type. Set the low-stock threshold and optionally enable the online store, then continue.

3c. Super administrator

Enter your full name, username and email. Choose and confirm a strong password of at least 8 characters. Click Finish setup, then sign in with that account. Completed installations redirect away from the installer.

After signing in, review Main Settings, company details, currency and mail delivery before adding real stock or accepting orders. Configuration screenshots use empty preview forms; they contain no real account data.

Developer guide

Run commands from the application root, where composer.json and package.json are located. Use a supported Node.js LTS on your build machine.

PHP dependencies

composer install --no-dev --optimize-autoloader
composer check-platform-reqs --no-dev

install uses the shipped composer.lock. To intentionally update libraries, do it on a development copy, test it, then ship the updated lock file.

composer update vendor/package --with-dependencies
composer audit

Replace vendor/package with the package you are updating. A full composer update resolves all allowed dependencies; it is not the normal install or deployment command.

Browser libraries & build

npm ci
npm run build
npm run test:assets

npm ci installs from package-lock.json. The build reads bin/vendor-assets.json and writes browser libraries to views/themes/inventory/assets/dist/, including a manifest. Ship that entire folder. Production pages do not load files from node_modules/.

npx --yes --package=sass sass views/themes/inventory/assets/scss/custom.scss views/themes/inventory/assets/css/custom.css --style=compressed

Upgrade an existing installation

1. Back up the database, storage/, .env.php and any custom code.
2. Deploy the new application files and built assets. Preserve the existing environment file and uploaded files.
3. Install the locked PHP dependencies and apply only pending migrations:

composer install --no-dev --optimize-autoloader
composer migrate

Check sign-in, inventory, sales/POS and uploads. Do not run the fresh installer against an existing database. Use a separate test database for composer test; the suite includes database integration checks.

Reference: Composer install / update · npm ci.

Quick troubleshooting

For support, include the failing step, PHP version and a screenshot with private values removed. Never send database passwords, SMTP passwords or your full .env.php.