AssetHub Documentation

Overview

AssetHub is a complete IT asset management system built with Laravel 11, Vue 3, and Tailwind CSS. It helps organizations track equipment lifecycle, manage assignments, schedule maintenance, calculate depreciation, and generate detailed reports.

Server Requirements

• PHP 8.2 or higher
• MySQL 5.7+ or MariaDB 10.3+
• Composer 2.x
• Node.js 18+ and npm 9+
• Web server: Apache or Nginx

Required PHP Extensions

• OpenSSL, PDO, PDO_MySQL, Mbstring, Tokenizer, XML, Ctype, JSON, GD, Fileinfo

Disk space

~ 200 MB minimum. Allow extra space for asset photos and document attachments.

Installation

Option A — Web Installer (Recommended)

1. Upload the project files to your web server.
2. Point your domain document root to public/.
3. Set permissions: storage/ and bootstrap/cache/ must be writable (chmod 775).
4. Copy .env.example to .env and run php artisan key:generate.
5. Visit https://yourdomain.com/install in your browser.
6. Follow the wizard — Requirements → Database → Migrate → Admin Account → Done.

Option B — CLI Installation

# 1. Install dependencies
composer install --no-dev --optimize-autoloader
npm install
npm run build

# 2. Configure environment
cp .env.example .env
php artisan key:generate

# 3. Edit .env to set DB credentials
# DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD

# 4. Create database tables and seed initial data
php artisan migrate --seed

# 5. Create storage symlink for uploads
php artisan storage:link

# 6. Cache config for production
php artisan config:cache
php artisan route:cache
php artisan view:cache

# 7. Mark as installed
echo "Installed" > storage/installed.lock

Wizard Step 2 — Database Configuration

When the wizard reaches Step 2, you must enter the MySQL connection details for the database you created in your hosting panel. The database must already exist (it can be empty — the next wizard step will create the tables).

Where to find these credentials by hosting panel

• Hostinger: hPanel → Databases → Management → click your database. The page shows name, username, and a "Show password" button.
• cPanel: cPanel → MySQL Databases. The database list shows names; users are listed below. Use "Change Password" if needed.
• Plesk: Plesk → Databases → click the database name. The detail page shows credentials and offers a password reset.
• DirectAdmin: DirectAdmin → MySQL Management → click the database. Credentials and password reset are on the database detail page.
• External / managed DB: AWS RDS, DigitalOcean Managed Database, etc. Use the custom hostname, port (often 3306 but verify), DB name, user, and password from your cloud console. Make sure the server's IP is whitelisted in the DB firewall.

Common errors and how to fix them

Localhost (Local Development)

Quick guide to run AssetHub on your computer for testing or development before deploying to production. Pick the environment that matches your operating system.

Option 1 — Laravel Herd (Recommended, macOS & Windows)

Laravel Herd is the official local environment from the Laravel team — free, native, no Docker. Bundles PHP 8.2/8.3/8.4, Nginx, and (in Herd Pro) MySQL/Redis.

1. Download and install Laravel Herd from herd.laravel.com.
2. Place the AssetHub project folder inside ~/Herd/ (macOS) or %USERPROFILE%\Herd\ (Windows). Herd auto-creates a .test domain — e.g. http://assethub.test.
3. Open Herd → Sites and confirm PHP version is 8.2 or 8.3. Right-click the site → Secure to enable HTTPS (needed for QR scanner).
4. Create a MySQL database. With Herd Pro, use Services → MySQL → Open in TablePlus. Otherwise install MySQL Community or use SQLite (DB_CONNECTION=sqlite, touch database/database.sqlite).
5. Copy .env.example to .env, fill in DB credentials, then run php artisan key:generate from the project root.
6. Open http://assethub.test/install in your browser and follow the installer wizard.

Option 2 — XAMPP (Windows, macOS, Linux)

XAMPP bundles Apache, MySQL/MariaDB, and PHP. Free and cross-platform. Make sure to pick a version with PHP 8.2 or newer.

1. Download XAMPP 8.2+ from apachefriends.org and install it.
2. Copy the AssetHub project into C:\xampp\htdocs\AssetHub\ (Windows) or /Applications/XAMPP/htdocs/AssetHub/ (macOS).
3. Open XAMPP Control Panel and start Apache and MySQL. If the ports are busy, use Config → service.conf to switch Apache to 8080.
4. Go to http://localhost/phpmyadmin → New → create a database named assethub with utf8mb4 collation.
5. In the project folder: copy .env.example to .env, set DB_DATABASE=assethub, DB_USERNAME=root, leave DB_PASSWORD empty (XAMPP default). Run php artisan key:generate.
6. Visit http://localhost/AssetHub/public/install to run the installer wizard.

Option 3 — Laragon (Windows)

Laragon is a portable Windows stack designed for Laravel — auto vhosts, pretty URLs, MySQL/MariaDB, and bundled HeidiSQL.

1. Download Laragon Full from laragon.org and install it.
2. In Laragon: Menu → PHP → Version — switch to PHP 8.2 or 8.3.
3. Copy the AssetHub project into C:\laragon\www\AssetHub\.
4. Click Start All. Laragon auto-creates the vhost: http://assethub.test (pointing to the public/ folder).
5. Open HeidiSQL (bundled) → create a database assethub. Default credentials: user root, password empty.
6. Edit .env with the DB credentials, run php artisan key:generate, then visit http://assethub.test/install.

Option 4 — Built-in PHP server (no web server needed)

The simplest option: Laravel ships with artisan serve, which starts a development PHP server. No Apache or Nginx required. Best for quick testing.

# Install dependencies and configure
cd /path/to/AssetHub
composer install
cp .env.example .env
php artisan key:generate

# Run migrations and seed initial data
php artisan migrate --seed

# Start the development server
php artisan serve
# Then visit: http://127.0.0.1:8000/install

Common localhost gotchas

QR scanner camera doesn't open on http://

Browser camera APIs require HTTPS, with one exception: http://localhost and http://127.0.0.1 are treated as secure contexts. If you access AssetHub via your LAN IP (e.g. http://192.168.1.10), the camera will refuse. Use localhost for dev, or enable HTTPS via Herd / mkcert.

Permission denied on storage (macOS / Linux)

If you see write errors when the app tries to log or cache, fix permissions: chmod -R 775 storage bootstrap/cache. On Windows this isn't usually needed.

Port already in use

If port 8000 is taken by another app, use a different port:

php artisan serve --port=8001

Testing emails locally

Real SMTP isn't available on most localhost setups. Two safe options: (1) set MAIL_MAILER=log in .env — emails are dumped to storage/logs/laravel.log instead of being sent; or (2) use Mailtrap / MailHog to capture outgoing mail in a fake inbox.

MAIL_MAILER=log
# All emails are written to storage/logs/laravel.log

Frontend assets (Vite / Tailwind)

AssetHub's Vue/Tailwind frontend is pre-built in the package. If you edit Vue components or Tailwind config you'll need Node.js 18+:

npm install
npm run dev    # Hot-reload during development
npm run build  # Production build (run before deploying)

Deploying to Hostinger Single (Shared Hosting)

This is the recommended path for users without VPS or technical experience. AssetHub is fully compatible with the cheapest Hostinger Single Web Hosting plan (~$2.99/month). No SSH, no Composer, no command line needed — Single includes native cron jobs, PHP 8.3, and free SSL out of the box.

Step 1 — Prepare your hosting

1. Login to Hostinger hPanel.
2. Go to Hosting → Manage for your domain.
3. Set PHP version to 8.2 or 8.3 via Advanced → PHP Configuration.
4. Make sure these PHP extensions are enabled (usually default):
   • OpenSSL, PDO, PDO_MySQL, Mbstring, GD, Tokenizer, XML, Ctype, JSON, Fileinfo

Step 2 — Create MySQL database

1. In hPanel, go to Databases → MySQL Databases.
2. Click Create New Database.
3. Note these 3 values:
   • Database name — e.g. u123_AssetHub
   • Username — e.g. u123_admin
   • Password — auto-generated, keep it safe

Step 3 — Upload files

1. Go to Files → File Manager in hPanel.
2. Navigate to public_html/ (this is your domain's root).
3. Delete any default index.html or default.php in that folder.
4. Click Upload Files and upload the entire source.zip from the package.
   Or upload the contents of /source/ folder directly via FTP if you prefer.
5. If you uploaded a ZIP, right-click → Extract. After extraction, all files should be at the root of public_html/.
6. Verify public_html/ contains: app/, public/, vendor/, .htaccess, index.php (in public/), .env, etc.

Step 4 — Run the installer

1. Open your browser and go to https://yourdomain.com/install.
2. You'll see the AssetHub Installer.
3. Step 1: Requirements — All checks should pass (green). If any fail, contact Hostinger support to enable the missing PHP extension.
4. Step 2: Database — Enter the credentials from Step 2 above:
   • Host: localhost
   • Port: 3306
   • Database: u123_AssetHub
   • Username: u123_admin
   • Password: (the one Hostinger generated)
5. Step 3: Migrate — Click "Run Migrations & Seed". Takes ~10 seconds. Don't refresh.
6. Step 4: Admin — Create your administrator account. Use a strong password.
7. Done! — You'll see the Cron URL (save this!) and a button to login.

Step 5 — Setup automatic email alerts via Hostinger Cron

AssetHub uses Laravel's scheduler for background tasks: warranty alerts, maintenance reminders, document expiry, depreciation refresh, and overdue checkouts. Set up one cron job in hPanel and Laravel decides which task to run when.

1. In hPanel, go to Advanced → Cron Jobs.
2. Click Create Cron job.
3. Select type: Custom (not "PHP" — we need to pass an argument).
4. For the command, enter (replace uXXXXXX with your Hostinger account username):

   /usr/bin/php /home/uXXXXXX/public_html/artisan schedule:run

   Tip: open File Manager, locate the artisan file (root of your project), right-click → Properties to copy the full path.
5. Set schedule to Every minute — all five fields (Minute, Hour, Day, Month, Day of week) set to *.
6. Click Save.

That's it — AssetHub now sends overdue checkout reminders, maintenance alerts, document expiry alerts, warranty alerts, and refreshes asset depreciation values automatically. Laravel internally schedules each job at its correct frequency (daily 08:00, monthly, etc.).

Step 6 — Configure email (SMTP)

Hostinger provides email accounts with each plan. To use them for AssetHub notifications:

1. In hPanel, go to Emails → Email Accounts and create one (e.g. noreply@yourdomain.com).
2. Edit the .env file in public_html/ via File Manager:

   MAIL_MAILER=smtp
   MAIL_HOST=smtp.hostinger.com
   MAIL_PORT=587
   MAIL_USERNAME=noreply@yourdomain.com
   MAIL_PASSWORD=your_email_password
   MAIL_ENCRYPTION=tls
   MAIL_FROM_ADDRESS=noreply@yourdomain.com
   MAIL_FROM_NAME="Your Company Name"

3. Save the file.
4. Login to AssetHub → Settings → Email tab → Send Test Email. If you receive it, you're done.

Common issues on Hostinger Single

"500 Internal Server Error" after upload

• Verify .htaccess exists at public_html/ root and contains the rewrite rules.
• Verify PHP version is set to 8.2 or 8.3 in hPanel.
• Check storage/logs/laravel.log via File Manager for the actual error.

"Permission denied" on uploads

Hostinger usually sets correct permissions, but if not:

• Right-click storage/ in File Manager → Permissions → set to 755 recursively.
• Same for bootstrap/cache/.

QR code scanner camera doesn't open

Browser camera APIs require HTTPS. Hostinger provides free SSL via Let's Encrypt — enable it in hPanel under SSL → Manage.

Scheduled emails aren't being sent

• In hPanel → Cron Jobs → check the Last run column on your cron entry. If empty, the cron isn't firing — verify the artisan path is correct.
• Test the command manually: open Terminal in hPanel (if available) and run the cron command. If it errors, the error message will pinpoint the issue (wrong PHP version, wrong path, etc.).
• Verify SMTP is correctly configured (Settings → Email → Send Test).
• Check storage/logs/laravel.log for scheduler errors.

Slow performance

Hostinger Single has shared CPU/RAM. If your team is more than 20 users, consider:

• Upgrading to Premium (~$3.99/month) — faster servers, more resources, multiple databases.
• Or Business (~$5.99/month) — dedicated resources, daily backups, staging environment.

Configuration

.env File

In-app Settings

Most non-sensitive options are configurable from Admin → Settings:

• General: company name/email/phone, asset tag prefix
• Email: send a test email to verify SMTP
• Notifications: warranty alert thresholds, maintenance reminder window
• Localization: timezone, date format, currency

Multi-Language Support

AssetHub ships with 10 languages out of the box, including RTL Arabic. Users switch language via the flag dropdown in the top-right header.

Shipped languages

How to switch language

1. Click the flag icon in the top-right header to open the dropdown.
2. Pick your language from the list.
3. The page reloads; all UI labels, dates, and currency formats switch.
4. Your choice is saved in both your user account and a cookie (1 year).

Adding a custom language (admin)

Admin → Settings → Translations:

• Click "Add Locale" — provide a code (e.g. th for Thai), display name, native name, flag, direction, and a base locale to copy translations from.
• Edit translations inline in the Translation Editor, or via CSV import/export.
• DB-stored translations automatically override file translations.

Per-user default locale

Each user has a locale column. Email notifications are automatically sent in the recipient's preferred language thanks to Laravel's HasLocalePreference contract.

Feature List

Users & Roles

AssetHub ships with 5 pre-configured roles:

Permissions are stored as Spatie roles — administrators can fine-tune per-permission via the database.

Asset Management

Creating Assets

1. Navigate to Assets → New Asset.
2. Fill in name, category, brand, model, serial number.
3. Add purchase date and price (required for depreciation).
4. Upload images (multiple files supported, max 5 MB each).
5. Save — asset tag and QR code are auto-generated.

Asset Tag Format

Default: {PREFIX}-{YEAR}-{NNNN}, e.g. AS-2026-0001. Configurable via Settings → General → Asset Tag Prefix.

Bulk Import

1. Click Import on the Assets page.
2. Download the Excel template.
3. Fill in your data — required columns: name, category_name.
4. Upload the file.

QR Codes

Every asset automatically receives a QR code on creation. The QR encodes the asset's URL, so scanning takes the user directly to the asset detail page.

Printing Labels

• Single label: Click the printer icon on any asset row.
• PDF format: A4, 2 labels per row, includes asset tag, name, brand, serial.

Scanning

Click Scan QR on the Assets page. Allow camera permission. The scanner uses html5-qrcode and works on any modern browser. Note: camera access requires HTTPS or localhost.

Workflows

Asset Assignment

1. Open an asset detail page.
2. Click Assign (visible if asset is available).
3. Pick a user, optional return date, notes.
4. Submit — transaction is created and email notification sent.

Asset Requests

Employees can submit requests for assets they need. Requests have 4 statuses: pending → approved → fulfilled, or rejected. Approval emails are sent automatically.

Check-in / Check-out

For shared assets (cameras, projectors, vehicles). Bookings have date ranges; the system prevents overlapping checkouts. Calendar view shows all bookings at a glance.

Depreciation

AssetHub calculates asset depreciation using one of three methods:

Defaults are inherited from the asset's category. Schedule entries are generated monthly. Asset's current_value is auto-updated on the 1st of each month.

Custom Fields

Admin → Custom Fields lets you add unlimited custom attributes to assets:

• Types: text, number, date, select (dropdown), textarea, file, checkbox
• Scope: apply to all categories or specific category
• Reorder: drag-and-drop the grip handle
• Required fields are validated on asset save

Reports

Eight built-in reports, accessible from the Reports menu:

1. Asset Summary — totals by status, condition, category, department
2. Depreciation — value loss per category, top depreciated assets
3. Transactions — assignment, return, transfer activity over time
4. Maintenance Cost — spending by month, category, type
5. Warranty Expiry — assets needing attention in 30/60/180 days
6. Department Assets — asset distribution & budget utilization by department
7. Assets by Source — distribution across procurement, project, donation, transfer sources
8. Inventory Audit Summary — discrepancies across periodic audit cycles

All reports support Excel and PDF export via buttons in the page header.

Webhooks

AssetHub can notify external services on key events.

Available Events

• asset.created, asset.updated, asset.deleted
• asset.assigned, asset.returned, asset.transferred
• request.created, request.approved, request.rejected, request.fulfilled
• maintenance.scheduled, maintenance.started, maintenance.completed
• checkout.created, checkout.returned

Payload Format

{
  "event": "asset.assigned",
  "timestamp": "2026-05-05T08:00:00+00:00",
  "data": {
    "asset_id": 1,
    "asset_tag": "AS-2026-0001",
    "asset_name": "HP EliteDesk 800",
    "to_user_id": 4,
    "transaction_id": 12
  }
}

Signature Verification

If a secret is configured, requests include header X-AssetHub-Signature containing HMAC-SHA256 of the payload body. Verify on your end:

$expected = hash_hmac('sha256', $rawBody, $secret);
if (hash_equals($expected, $request->header('X-AssetHub-Signature'))) {
  // valid
}

Retry Policy

Failed deliveries retry 3 times with 200 ms delay. After 10 consecutive failures, the webhook is auto-disabled.

Scheduled Tasks

AssetHub uses Laravel's scheduler for background jobs. You only need one cron entry — Laravel internally dispatches each job at the right time.

Hostinger / Shared hosting (hPanel Cron Jobs UI)

See the Hostinger Setup → Step 5 section for screenshots-style instructions. In short: Advanced → Cron Jobs → Custom, command:

/usr/bin/php /home/uXXXXXX/public_html/artisan schedule:run

Schedule: every minute (* in all five fields).

VPS / dedicated server (crontab)

Run crontab -e as your web user (often www-data) and add:

* * * * * cd /path/to/AssetHub && php artisan schedule:run >> /dev/null 2>&1

Fallback: external URL pinger

If your host has no cron at all, use the in-app Cron URL (Settings → System tab) with cron-job.org (free, every 15 min).

Jobs that run automatically

Troubleshooting

"Permission denied" on storage

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

QR code scanner doesn't open camera

Browser camera APIs require HTTPS. Either install an SSL certificate or use localhost for testing.

Emails not arriving

Check storage/logs/laravel.log for errors. Use Settings → Email → Send Test Email to verify SMTP credentials. Make sure your SMTP server allows the sending IP.

Reset installation

Delete storage/installed.lock and visit /install again. Existing data will be erased if you re-run migrations.

Performance — slow asset list

Run php artisan optimize to cache config, routes, views. Ensure MySQL has indexes on assets.asset_tag, assets.serial_number, assets.status (created automatically by migrations).

Changelog

v1.0.0 — Initial Release (2026-05)

• Asset CRUD with QR code auto-generation
• 5 user roles (Admin, IT Manager, Accountant, Supervisor, Employee) with granular permissions
• Asset Source tracking (centralized procurement, decentralized procurement, investment project, donation, internal transfer)
• Assignment, return workflows with email notifications
• Transfer Approval Workflow (pending → approved/rejected) with permission gating
• Asset request approval flow
• Check-in/check-out with calendar view
• Maintenance scheduling with auto-renewal
• Document attachments with expiry alerts
• Depreciation with 3 calculation methods + end-of-life alerts
• Inventory Audit module — periodic stocktake with discrepancy tracking
• Custom fields with 7 input types and drag-drop sort
• 8 reports with charts, Excel and PDF export (incl. Assets by Source, Inventory Audit Summary)
• Audit log via Spatie Activitylog with diff viewer
• Webhooks with HMAC signing and auto-retry
• Multi-language UI: 10 locales (en, vi, es, fr, de, zh, ja, pt-BR, ru, ar with RTL)
• Settings UI for company, email, notifications, localization, translations
• Web-based installation wizard
• Dark mode with emerald-teal brand palette

Credits

Open-source libraries used

• Laravel 11 — MIT
• Vue 3 — MIT
• Inertia.js — MIT
• Tailwind CSS — MIT
• Spatie Permission, Media Library, Activitylog — MIT
• Phosphor Icons — MIT (duotone weight)
• ApexCharts — MIT
• html5-qrcode — Apache 2.0
• Simple QrCode — MIT
• Laravel Excel — MIT
• Laravel DomPDF — MIT