Docs / Installation

Installer Wizard (8 Steps)

The installer will guide you through a complete first-time setup in 8 steps. You can follow the steps in order. If a step fails, check the on-screen message and see the FAQ & Troubleshooting page.

Before you start: Upload the project, point the domain to /public, and ensure folder permissions are correct (see Requirements).

Steps Overview

Installation Steps

1 Requirements
2 App Settings
3 Database Configuration
4 Migrations & Seeds
5 Channels
6 Admin Account
7 Branding
8 Finish

Keep the browser open during Steps 3-4 (database + migrations). Refreshing may interrupt the process on slow hosting.

Step 1 - Requirements

Screenshot (Optional)

Requirements step screenshot — Replace this screenshot with your Requirements step image.

The installer checks your server requirements and folder permissions. If everything is OK, proceed to the next step.

What it checks
PHP version, required extensions, and writable folders like storage and bootstrap/cache.

If it fails
Fix the missing extension/permission and reload this step. Shared hosting may need support ticket.

Step 2: App Settings

In this step, you will configure the basic identity, localization, and currency settings of your application. These settings define how your application appears to users and how data such as dates, time, and currency are formatted.

You can change most of these settings later from the main Settings panel. However, it is recommended to configure them correctly during installation.

1. Identity

Basic application branding and naming information.

App Name: The full name of your application. This name appears in page titles, emails, invoices, and system notifications.
Short Name: A compact version of the application name. Used in small UI areas such as sidebars, headers, or mobile layouts.
Description: A short summary of your application. This may be displayed in emails, dashboards, or metadata depending on configuration.

2. Localization

Configure how dates, times, and regional formats are displayed.

Timezone: Select your server/application timezone (e.g., Asia/Karachi, UTC). This affects booking times, logs, and scheduled tasks.
Locale: Defines the default language and regional formatting rules (e.g., en, fr, ar).
Time Format: Choose between 12-hour or 24-hour display format.
Date Format: Controls how dates are displayed (e.g., d M Y -> 09 Feb 2026).
App URL (Optional): The full base URL of your application (e.g., https://yourdomain.com). This is important for asset loading, email links, and redirects.

Ensure the App URL is correct. An incorrect URL may cause broken images, CSS issues, or incorrect redirect behavior.

3. Currency Settings

Define how monetary values appear across invoices and reports.

Currency Code: Standard 3-letter currency code (e.g., USD, PKR, EUR).
Currency Symbol: The symbol used when displaying prices (e.g., $, Rs, EUR).
Symbol Position: Choose whether the currency symbol appears before or after the amount (e.g., Rs 100 or 100 Rs).
Decimal Places: Number of digits displayed after the decimal point.
Thousand Separator: Select the character used to separate thousands (e.g., comma).

4. Maintenance Mode

Enable Maintenance Mode During Setup: When enabled, public access to the application will be temporarily restricted until installation is complete. This is recommended for production installations.

Tip: These settings establish the foundation of your system. Take a moment to verify timezone and currency values before proceeding. This can be adjusted later in the Settings module.

Step 3: Database Configuration

In this step, you will connect the application to your database. The installer will verify the connection and automatically prepare the database structure. Verification of the database connection is a prerequisite for the next step.

Make sure your database is created before continuing. On shared hosting, create the database first using cPanel. This portion is already covered in how to configure your database part of this guide.

1. Connection Settings

DB Driver: Select your database type. Most hosting providers use MySQL or MariaDB.
DB Host: Usually 127.0.0.1 for local installations. On shared hosting, this may be different (check your hosting provider).
DB Port: Default MySQL port is 3306. Change only if your server uses a custom port.
DB Name: The exact name of your database. On shared hosting, it may include a prefix (e.g., cpaneluser_dbname).

2. Credentials

DB Username: The database user created with access to the selected database.
DB Password: The password for the database user. Leave empty only if your environment does not require one.

Use a database user with full privileges for this database. Insufficient permissions may cause migration failures.

3. Test Connection

Click the Test Connection button to verify that the application can communicate with your database server.

If successful, you may proceed to the next step. If it fails, double-check your credentials and host settings.

4. Installer Actions

After clicking Save & Continue, the installer performs the following actions automatically:

Run Migrations (Required): Creates all necessary database tables.
Seed Required Data (Required): Inserts default system data such as roles, permissions, and base configuration. Roles and permissions are implemented by using Spatie Laravel Permission package. Buyer package licensing is summarized in the root LICENSE.md file, and release history is tracked in the documentation changelog.
Install Demo Content (Optional): Adds sample staff users, catalog records, purchases, stock outs, stock adjustments, and inventory activity for evaluation environments. Leave it unchecked for production-ready installs.

Tip: Always test the connection first. Step 3 writes the database credentials and passes the installer into the automated setup stage. A full reinstall is not exposed as an in-app settings action; use a fresh database and rerun the installer intentionally when you need a full rebuild.

Step 4: Database Setup (Migrations & Seeds)

This step prepares your database automatically in a safe, step-by-step manner. The installer verifies the runtime environment, generates an application key when needed, runs migrations, seeds the required baseline via InstallerRequiredSeeder, and only seeds demo content when that option was selected in Step 3.

Step 4 - Database Setup Screenshot — Figure 4.1 - Database Setup Progress (migrations + required data seeding)

Do not close or refresh this page while setup is running. On slower shared hosting, migrations and seeding may take a little longer.

How to Use This Step

Click Run Setup to start the database preparation.
Watch the Setup Progress indicator for completion.
Use the Live Logs box to monitor what is happening in real time.
Once all tasks are complete, click Continue to proceed.

Setup Tasks (Executed in Order)

1) Verify environment
Performs basic checks before starting database operations.
2) Generate app key
Ensures the application encryption key (APP_KEY) exists. If missing, the installer generates it automatically.
3) Run migrations
Creates all required database tables and structures.
4) Seed required data
Inserts the production-safe baseline such as default settings, essential roles and permissions, and measurement units.
5) Seed demo data (Optional)
Adds sample staff, categories, suppliers, products, purchases, stock-outs, stock adjustments, and inventory activity only when demo content was selected in the previous step. If not selected, this task may appear as Skipped.

Tip: If setup fails repeatedly on shared hosting, check your hosting limits (execution time / memory). If your product supports it, use the SQL fallback option or contact hosting support to increase limits temporarily.

Step 5: Notifications & Channels

In this step, you will configure how the application sends notifications. Email (SMTP) is the primary channel used for admin alerts, OTP, password reset, and system emails. Optionally, you can enable SMS and WhatsApp notifications via Twilio. If you do not need SMS/WhatsApp right now, you can skip them and update later from the Settings panel.

Recommended: Configure Email (SMTP) now so system emails work immediately. without configuring email smtp, the step will not proceed. Setting up of smtp server is covered in smtp setup section of this guide. SMS/WhatsApp is optional and can be enabled later.

1. Email (SMTP)

Used for admin alerts, OTP, password reset, and system notifications.

Mailer: Choose the email driver. Use smtp for production. Use log for local/dev testing (emails will be written to logs).
Host: Your SMTP server host (e.g., smtp.gmail.com, your hosting SMTP, or a provider like Mailgun/SendGrid SMTP).
Port: SMTP port (common: 587 for TLS, 465 for SSL).
Username: Your SMTP username (often your email address).
Password: Your SMTP password. For Gmail, use an App Password (recommended) instead of your normal login password.
Encryption: Select tls (recommended) or ssl depending on your SMTP provider.
Timeout (sec): Maximum time the system will wait for SMTP before failing the attempt.
Reply-To: The email address users will reply to (e.g., support@yourdomain.com).
From Email: Sender email address shown in outgoing emails (e.g., no-reply@yourdomain.com).
From Name: Sender name shown in outgoing emails (e.g., your company/app name).
Test To (Email): The email address where the installer will send a test message. Use Test Email to confirm delivery.

Tip: If you are testing locally, switch Mailer to log to avoid SMTP issues. For Gmail, use an App Password and ensure "Less secure apps" is not required.

2. SMS / WhatsApp (Twilio) - Optional

Enable only if you plan to send OTP and notifications via SMS/WhatsApp. If disabled, the system will continue using Email as the primary channel.

Enable SMS: Turns on SMS notifications (OTP, alerts) using Twilio.
Enable WhatsApp: Turns on WhatsApp notifications using Twilio WhatsApp sender.
Twilio SID: Your Twilio Account SID (starts with AC...).
Twilio Token: Your Twilio Auth Token (keep it private).
Country Code: Default country code used when formatting phone numbers (e.g., +92).
SMS From: Your Twilio sender number (e.g., +1XXXXXXXXXX).
WhatsApp From: Your Twilio WhatsApp sender (format: whatsapp:+1XXXXXXXXXX).

If you do not use Twilio, keep SMS/WhatsApp disabled and continue. You can enable these channels later from Settings.

Step 6: Create Admin Account

In this step, you will create the first administrator account for the system. This user will be responsible for managing the application after installation, including modules, settings, staff, and security options.

Use a strong password and a real email address. This account will be used to log in immediately after installation. You can update admin details later from the Settings module.

Admin Details

Required to log in after installation. Optional phone fields can be used later for phone login/OTP if enabled.

Full Name: The display name of the administrator account.
Email: The primary login email for the admin. Used for password reset, verification, and system alerts.
Phone (Optional): Optional phone number for future phone-based login or OTP workflows. You may leave this empty if not required.
WhatsApp (Optional): Optional WhatsApp number for future WhatsApp notifications (if enabled in Channels).
Password: Create a strong password (minimum 8 characters). It is recommended to use uppercase letters and numbers for better security.
Confirm Password: Must match the password exactly.

Default Role Assignment

Admin Role (Assigned Automatically): The user created in this step is automatically assigned the Admin role by default and receives full access to manage the system.

You can create additional staff users later and assign roles/permissions according to your organization's needs.

Security Options (Optional)

These settings are recommended for production installations and can be changed later.

Require 2FA setup after login: If enabled, the admin will log in once and then be redirected to set up 2FA (OTP/TOTP/Passkey) for stronger account security. For 2FA login, smtp needs to be setup correctly otherwise 2FA will not work and admin will be unable to log in. It is recommended to either setup smtp or disable 2FA setup in this step.
Mark Admin Email as Verified: If enabled, the admin email will be treated as verified immediately. If disabled, a verification process may be required on first login.

Note: 2FA method selection happens after login because it requires generating and confirming security secrets.

Step 7: Brand Assets & Appearance

In this step, you will upload your brand assets (logos, favicon, and default avatar) and configure the application's visual preferences such as primary/secondary colors, sidebar theme, and app mode. These settings help match the system to your brand identity. You can skip branding during installation and update everything later from the Settings module.

Figure 7.1 - Branding: logos, favicon, colors, theme, and login branding

Recommended: Upload your logos and favicon now for a polished first login experience. If you don't have assets ready, you can continue and update branding later.

1. Brand Assets

These files are used across the application UI, emails, and browser tab icon. Keep assets optimized for best performance.

Logo (Light): Used for light mode UI and emails. Recommended: 256x256 (PNG/SVG).
Logo (Dark): Used for dark sidebars / dark mode headers. Recommended: 256x256 (PNG/SVG).
Favicon: Small icon shown in the browser tab. Recommended: 32x32 or 64x64 (PNG/ICO).
Default Avatar: Fallback profile image used when a user has not uploaded an avatar.

Tip: Keep files small. SVG is best for logos (sharp and lightweight). Use a square favicon for best compatibility.

2. Colors & Layout

Set the application theme colors and layout preferences. These values affect buttons, highlights, and overall UI styling.

Primary Color: Main brand color used in buttons, links, highlights, and UI accents. You can pick from presets or enter a HEX value (e.g., #111827).
Secondary Color: Supporting color used for secondary elements, muted UI accents, and decorative highlights. You can pick from presets or enter a HEX value (e.g., #737373).
Sidebar Theme: Controls the sidebar style (Light / Dark). Useful when your logo is optimized for a specific background.
App Mode: Controls the overall application appearance (Light / Dark). Users may also switch later if supported.
Login Branding: When enabled, the login screen displays your app name and logo for a branded sign-in experience.

You can refine branding later from Settings. The installer simply sets safe defaults so the UI looks consistent immediately after installation.

Step 8: Installation Complete

Congratulations. Your application has been successfully installed. All required checks, database setup, and configuration steps have been completed. You can now secure the installer and start using the system.

Important: For security reasons, you must click Lock Installer before accessing the login page. This prevents unauthorized reinstallation attempts.

Refresh Database vs Reinstall

Refresh Database: an admin tool that clears catalog, transaction, and demo-account data while preserving settings and the current signed-in user.
Reinstall: a fresh installer run against an intentionally reset database and unlocked installer state.
Use Refresh Database for cleanup. Use a reinstall only when you actually need to rebuild the application from installation state.

System Status Summary

Status: Installed successfully.
Environment: Ready.
Database: Configured and migrated.
Next Step: Login.

Admin Account

Admin user created successfully.
For security reasons, the password is not displayed.

If you forget your password, use the "Forgot Password" option on the login page to reset it.

Quick System Checks

Storage directory is writable
Cache directories are available
Application key generated
All installer steps completed

What Should You Do Next?

Click Lock Installer to secure the installation.
Click Go to Login to access your dashboard.
Review Settings, Roles & Permissions, and basic system configuration.

Locking the installer is strongly recommended before moving to production.