Q-Putaway – Installation and deployment (Hostinger shared hosting)

This guide installs Q-Putaway on Hostinger shared hosting (Premium/Business/Cloud plans). The same steps work on any Apache/LiteSpeed host with PHP and MySQL.

1. Requirements

Check these in hPanel → Advanced → PHP Configuration (choose the PHP version and tick the extensions) before installing. The installer re-checks them.

2. Upload the files

Q-Putaway has no public/ folder. The project root is the web root.

1. hPanel → Files → File Manager → open public_html (or create a sub-folder such as public_html/wms).
2. Upload the release ZIP and Extract it there. The folder must then contain index.php, .htaccess, assets/, app/, config/, storage/ and so on.
3. Make sure the hidden .htaccess files were uploaded. They block web access to app/, config/, storage/, database/, tests/, cron/, tools/ and views/. Every one of these folders also contains its own Require all denied .htaccess.
4. Permissions: folders 755, files 644. config/ and everything under storage/ must be writable by PHP (on Hostinger they are by default).

Nginx (VPS only): .htaccess is ignored. Route all non-file requests to index.php?r=$uri, and deny ^/(app|config|storage|database|tests|cron|tools|views)/ plus dotfiles.

3. Create the database

hPanel → Databases → MySQL Databases: create a database and a user with all privileges on it. Note the names (Hostinger prefixes them, e.g. u123456789_wms). The host is localhost.

4. Enable SSL

hPanel → Security → SSL → install the free SSL certificate. Use the https:// address from now on.

5. Run the web installer

Open https://your-domain/ (or /wms/). You are redirected to /install:

1. System check: all required items must be green.
2. Database: host localhost, port 3306, name, user and password → Test connection & continue. The option "create database if it does not exist" works only if your account has that privilege. Existing databases are never dropped or overwritten.
3. Company: name, address, registration/tax IDs, currency, timezone, date format, fiscal year, contact email and the Application URL (https://…). Keep Clean URLs ticked. Tick Force HTTPS once SSL works.
4. Super Admin: name, email (sign-in ID) and password (≥ 10 characters with letters and digits).
5. Install: creates the schema, roles and permissions, reference data (units, reason codes, numbering, label templates) and Help Center articles. It then writes config/config.php (database credentials, the application encryption key, a separate backup encryption key and the cron token) and creates storage/installed.lock.

After installation /install returns 404.

Partial installation: if the installer stops (timeout, wrong password), open the site again. Re-running is safe: tables are created with IF NOT EXISTS, migrations already applied are skipped, seeding only adds missing rows, and existing users are kept.

6. Set up cron

hPanel → Advanced → Cron Jobs → Custom:

*/5 * * * *   /usr/bin/php /home/<USER>/domains/<DOMAIN>/public_html/cron/cron.php >/dev/null 2>&1

Adjust the path to where you uploaded Q-Putaway (Administration → Email & Schedules shows the exact command for your install). Cron runs scheduled reports, expiry/low-stock alerts (daily), forecast refresh (nightly), cleanup of expired tokens/temporary files, and the optional daily backup. A lock prevents overlapping runs.

If your plan has no cron, an external scheduler can call https://your-domain/jobs/run?token=<cron token from config/config.php> (at most once a minute). Keep the token secret. Without any cron, scheduled reports and alerts do not run; Q-Putaway never relies on page visits to run jobs.

7. First login checklist

Sign in as the Super Admin. The dashboard checklist guides you through:

1. Warehouses (system locations are created automatically).
2. Locations/bins (bulk generator in Masters → Locations).
3. Products, barcodes and packaging (or CSV import).
4. Suppliers and customers.
5. Barcode and label settings.
6. Opening stock (CSV import Opening stock, or a goods receipt of type Opening).
7. Users, roles and warehouse assignments.
8. Email (SMTP) and a test email.
9. First backup, plus retention and the daily backup setting.
10. Cron.

8. Hardening checklist

• [ ] HTTPS works, and Force HTTPS is on (in Settings or config/config.php → app.force_https).
• [ ] https://your-domain/config/config.php returns 403 (also test /storage/installed.lock and /app/bootstrap.php).
• [ ] config/config.php has 'debug' => false.
• [ ] 2FA is enabled for Super Admins (Profile → Two-factor authentication). Optionally require it for admins in Settings → Security.
• [ ] A backup was created and downloaded. Store a copy off-server, and store the backup key (backup.key in config/config.php) separately from the backups.
• [ ] Run the HTTP security smoke test from a computer with PHP: php tests/http/smoke.php https://your-domain admin@email 'password'.

9. Local development

php -S 127.0.0.1:8080 tools/dev-router.php        # mimics the .htaccess rules
QP_TEST_DB_PORT=3306 php tests/run.php             # unit/integration/security tests (uses a *_test database)
QP_TEST_DB_PORT=3306 php tests/concurrency/race.php

10. Moving or restoring an installation

Copy all files (including config/config.php and storage/uploads) and restore the latest backup through Administration → Backups (see docs/backup-restore.md). If the domain changes, update app.url in config/config.php.