Genius Support
Help Desk Platform

Introduction

Genius Support is a self-hosted help desk platform that lets your team receive, track, and resolve customer support requests from a single place. Customers can raise tickets through the web portal or by sending an email; your agents and admins manage everything from the Blade-based admin panel.

User Roles

Role	Where they work	Capabilities
Customer	Customer Portal	Create tickets, reply, view KB, rate resolutions, manage profile
Agent	Admin Panel	View ticket queues, reply, add internal notes, change status/priority, assign
Admin	Admin Panel	All agent rights + manage users, departments, settings, KB, reports

Installation

Genius Support is a self-hosted application that runs on a standard Linux server. Follow the steps below to install it from scratch on a fresh Ubuntu 22.04 VPS.

Server Requirements

Component	Minimum	Recommended
Operating System	Ubuntu 22.04 LTS	Ubuntu 22.04 LTS
CPU	1 vCPU	2–4 vCPU
RAM	2 GB	4–8 GB
Disk	20 GB SSD	80 GB SSD
PHP	8.2+	8.2+
MySQL / MariaDB	MySQL 8.0 / MariaDB 10.6	MySQL 8.0
Node.js (build only)	20+	20+
Web Server	Nginx	Nginx
Process Manager	Supervisor	Supervisor

Option A — Automated Install Script

The repository ships with a fully automated install script. Set three environment variables and run it as root:

# Clone the repository
git clone https://github.com/XgeniousLLC/Genius-support.git /var/www/helpdesk
cd /var/www/helpdesk

# Run the installer
DOMAIN=support.yourdomain.com \
DB_NAME=genius_support \
DB_USER=helpdesk \
bash deploy/install.sh

The script will:

• Install PHP 8.2, MySQL 8, Nginx, Supervisor, Composer, and Node.js 20.
• Create the database and a dedicated DB user.
• Install PHP and Node.js dependencies.
• Build the frontend assets.
• Run database migrations and seed the default admin account.
• Configure Nginx (HTTPS with Let's Encrypt) and Supervisor.
• Set up a nightly database backup cron job.

Option B — Manual Installation

1. Install System Packages

apt-get update
apt-get install -y php8.2-fpm php8.2-mysql php8.2-mbstring php8.2-xml \
  php8.2-curl php8.2-zip php8.2-bcmath php8.2-intl \
  mysql-server nginx supervisor curl unzip git

# Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt-get install -y nodejs

# Composer
curl -sS https://getcomposer.org/installer | php -- \
  --install-dir=/usr/local/bin --filename=composer

2. Clone the Repository

git clone https://github.com/XgeniousLLC/Genius-support.git /var/www/helpdesk
cd /var/www/helpdesk

3. Configure the Environment

cp .env.example .env

Open .env and set at minimum:

Variable	Example value	Notes
APP_URL	https://support.yourdomain.com	Full URL including https://
APP_ENV	production	Change from local
APP_DEBUG	false	Must be false in production
DB_HOST	127.0.0.1
DB_DATABASE	genius_support	Create this DB first
DB_USERNAME	dbuser
DB_PASSWORD	strongpassword
MAIL_HOST	smtp.yourdomain.com	SMTP for outbound email
REVERB_APP_KEY	random string	Generate: openssl rand -hex 16

4. Install Dependencies & Build Assets

composer install --no-dev --optimize-autoloader
npm ci
npm run build

5. Generate App Key & Run Migrations

php artisan key:generate
php artisan migrate --force
php artisan db:seed --class=AdminSeeder
php artisan db:seed --class=SiteSettingsSeeder
php artisan db:seed --class=EmailTemplateSeeder

6. Set File Permissions

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

7. Optimise for Production

php artisan config:cache
php artisan route:cache
php artisan view:cache

8. Configure Nginx

Copy and customise the template from deploy/nginx.conf:

sed 's/YOUR_DOMAIN/support.yourdomain.com/g' deploy/nginx.conf \
  > /etc/nginx/sites-available/helpdesk
ln -s /etc/nginx/sites-available/helpdesk /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

Then install an SSL certificate:

certbot --nginx -d support.yourdomain.com

9. Configure Supervisor

Copy the Supervisor config from deploy/supervisor.conf:

sed 's|/var/www/helpdesk|/var/www/helpdesk|g' deploy/supervisor.conf \
  > /etc/supervisor/conf.d/helpdesk.conf
supervisorctl reread
supervisorctl update
supervisorctl start helpdesk-queue:*
supervisorctl start helpdesk-reverb
supervisorctl start helpdesk-scheduler

Option C — Standard Linux Step-by-Step (Ubuntu 22.04 / Debian 12)

This guide walks through every command from a fresh server login to a live site — no shortcuts, no scripts. Suitable if you want full control or are installing on a shared server.

Step 1 — Connect & Update

ssh root@YOUR_SERVER_IP
apt-get update && apt-get upgrade -y

Step 2 — Install PHP 8.2 & Extensions

# Add Ondrej PPA (Ubuntu) for PHP 8.2
add-apt-repository ppa:ondrej/php -y
apt-get update

apt-get install -y \
  php8.2 php8.2-fpm php8.2-mysql php8.2-mbstring php8.2-xml \
  php8.2-curl php8.2-zip php8.2-bcmath php8.2-intl \
  php8.2-tokenizer php8.2-gd php8.2-fileinfo

Verify PHP is installed:

php -v
# PHP 8.2.x ...

Step 3 — Install MySQL 8

apt-get install -y mysql-server
systemctl enable mysql
systemctl start mysql

# Secure the installation (set root password, remove test DB, disallow remote root)
mysql_secure_installation

Create the database and user:

# Run as system root or prefix each command with: sudo mysql
mysql -u root

-- Inside MySQL prompt:
CREATE DATABASE genius_support
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

-- Use a strong password — save it; you need it in .env
CREATE USER 'gsuser'@'localhost' IDENTIFIED BY 'YourStrongPassword123!';
GRANT ALL PRIVILEGES ON genius_support.* TO 'gsuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Verify the user was created:

mysql -u gsuser -p'YourStrongPassword123!' genius_support -e "SELECT 1;"
# Should return: 1

Step 4 — Install Nginx

apt-get install -y nginx
systemctl enable nginx
systemctl start nginx

Step 5 — Install Composer

curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer
chmod +x /usr/local/bin/composer
composer --version

Step 6 — Install Node.js 20

curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt-get install -y nodejs
node -v    # v20.x.x
npm -v

Step 7 — Install Supervisor

apt-get install -y supervisor
systemctl enable supervisor
systemctl start supervisor

Step 8 — Clone the Project

mkdir -p /var/www
git clone https://github.com/XgeniousLLC/Genius-support.git /var/www/helpdesk
cd /var/www/helpdesk

Step 9 — Set Up the Environment File

cp .env.example .env

Open the file with nano:

nano .env

Replace or set all of the following values. Lines marked # CHANGE are mandatory. Others have sane defaults but should be reviewed:

APP_NAME="Genius Support"          # CHANGE to your brand name
APP_ENV=production                  # CHANGE from local
APP_DEBUG=false                     # CHANGE: must be false in production
APP_URL=https://support.yourdomain.com  # CHANGE to your full domain

LOG_CHANNEL=stack
LOG_LEVEL=warning                   # less noise than the default 'debug'

DB_CONNECTION=mysql                 # CHANGE from sqlite
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=genius_support          # CHANGE to match Step 3
DB_USERNAME=gsuser                  # CHANGE to match Step 3
DB_PASSWORD=YourStrongPassword123!  # CHANGE to match Step 3

SESSION_DRIVER=database
QUEUE_CONNECTION=database           # required for email and IMAP jobs
CACHE_STORE=database
BROADCAST_CONNECTION=reverb         # CHANGE from log

MAIL_MAILER=smtp
MAIL_HOST=smtp.yourmailprovider.com # CHANGE
MAIL_PORT=587
MAIL_USERNAME=support@yourdomain.com # CHANGE
MAIL_PASSWORD=your_mail_password     # CHANGE
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=support@yourdomain.com  # CHANGE
MAIL_FROM_NAME="Genius Support"

# --- Reverb (WebSocket) --- generate values in Step 12b below
REVERB_APP_ID=helpdesk
REVERB_APP_KEY=REPLACE_IN_STEP_12B
REVERB_APP_SECRET=REPLACE_IN_STEP_12B
REVERB_HOST=localhost
REVERB_PORT=8080
REVERB_SCHEME=https

# --- Frontend (baked into JS bundle at build time) ---
VITE_REVERB_APP_KEY="${REVERB_APP_KEY}"
VITE_REVERB_HOST="support.yourdomain.com"  # CHANGE: bare domain, no https://
VITE_REVERB_PORT=443
VITE_REVERB_SCHEME=https

Save and exit: Ctrl+O then Ctrl+X.

Step 10 — Install PHP Dependencies

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

Step 11 — Install Node Dependencies & Build Assets

npm ci
npm run build

Step 12 — Generate Application Key

php artisan key:generate

Step 12b — Generate Reverb Credentials

Generate secure random values for the WebSocket server, then paste them into .env:

echo "REVERB_APP_ID=$(openssl rand -hex 8)"
echo "REVERB_APP_KEY=$(openssl rand -hex 16)"
echo "REVERB_APP_SECRET=$(openssl rand -hex 32)"

Copy the three output lines and update .env (replace the REPLACE_IN_STEP_12B placeholders set in Step 9):

nano .env
# Update the three REVERB_ values with the output above, then save.

Step 13 — Run Migrations & Seed

php artisan migrate --force
php artisan db:seed --class=AdminSeeder
php artisan db:seed --class=SiteSettingsSeeder
php artisan db:seed --class=EmailTemplateSeeder

Step 14 — Set Permissions

chown -R www-data:www-data /var/www/helpdesk
chmod -R 755 /var/www/helpdesk
chmod -R 775 /var/www/helpdesk/storage
chmod -R 775 /var/www/helpdesk/bootstrap/cache
php artisan storage:link

Step 15 — Optimise Laravel for Production

php artisan config:cache
php artisan route:cache
php artisan view:cache

Step 16 — Configure Nginx Virtual Host

nano /etc/nginx/sites-available/helpdesk

Paste the following (replace support.yourdomain.com with your actual domain):

server {
    listen 80;
    server_name support.yourdomain.com;
    root /var/www/helpdesk/public;
    index index.php;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    charset utf-8;
    client_max_body_size 20M;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # WebSocket proxy for Reverb
    location /app/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 60s;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Enable the site and reload Nginx:

ln -s /etc/nginx/sites-available/helpdesk /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

Step 17 — Install SSL Certificate (Let's Encrypt)

apt-get install -y certbot python3-certbot-nginx
certbot --nginx -d support.yourdomain.com
# Follow the prompts. Choose to redirect HTTP → HTTPS.

Certbot auto-renews the certificate. Verify renewal works:

certbot renew --dry-run

Step 18 — Configure Supervisor (Queue + Reverb + Scheduler)

nano /etc/supervisor/conf.d/helpdesk.conf

Paste the following:

[program:helpdesk-queue]
command=php /var/www/helpdesk/artisan queue:work database --sleep=3 --tries=3 --timeout=90
directory=/var/www/helpdesk
autostart=true
autorestart=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/log/supervisor/helpdesk-queue.log

[program:helpdesk-reverb]
command=php /var/www/helpdesk/artisan reverb:start --host=0.0.0.0 --port=8080
directory=/var/www/helpdesk
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/log/supervisor/helpdesk-reverb.log

[program:helpdesk-scheduler]
command=php /var/www/helpdesk/artisan schedule:work
directory=/var/www/helpdesk
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/log/supervisor/helpdesk-scheduler.log

Load and start all processes:

supervisorctl reread
supervisorctl update
supervisorctl start helpdesk-queue:*
supervisorctl start helpdesk-reverb
supervisorctl start helpdesk-scheduler
supervisorctl status

Step 19 — Set Up Nightly Database Backup

crontab -e

Add this line:

0 2 * * * mysqldump -u gsuser -pYourStrongPassword123! genius_support | gzip > /var/backups/helpdesk-$(date +\%Y\%m\%d).sql.gz && find /var/backups -name "helpdesk-*.sql.gz" -mtime +14 -delete

Step 20 — Open Firewall Ports

ufw allow OpenSSH
ufw allow 'Nginx Full'
ufw enable
ufw status

Verify Everything is Running

# Nginx
systemctl status nginx

# PHP-FPM
systemctl status php8.2-fpm

# MySQL
systemctl status mysql

# Supervisor processes
supervisorctl status

# Check queue is processing jobs
php artisan queue:monitor database

Post-Install Checklist

1. Log in at /admin/login with admin@example.com / password and change the password immediately.

2. Go to Settings → Email / IMAP and enter your SMTP and IMAP credentials. Use the Send Test Email button to verify.

3. Go to Settings → Departments and create your team's departments and ticket categories.

4. Go to Settings → Branding and set the portal name and primary colour.

5. Go to Settings → Reverb Status and confirm the green indicator is showing.

6. Share the portal URL https://support.yourdomain.com/portal with your customers.

Upgrading

To deploy a new version:

cd /var/www/helpdesk
git pull origin main
composer install --no-dev --optimize-autoloader
npm ci && npm run build
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache
supervisorctl restart helpdesk-queue:*

Quick Start

For Customers

1. Go to /portal/register and create an account with your name, email, and password.

2. Log in at /portal/login.

3. Click New Ticket and describe your issue.

4. You'll receive a confirmation email with your ticket reference number.

5. Track replies on your Dashboard or under My Tickets.

For Admins

1. Log in at /admin/login with your admin credentials.

2. Go to Settings → Departments and create your team's departments and categories.

3. Go to Settings → Email / IMAP and configure your SMTP (outbound) and IMAP (inbound) mail settings.

4. Go to Tickets in the sidebar to see the ticket queue.

5. Assign tickets to agents, reply to customers, and track resolution through the workspace.

Login & Registration

Creating an Account

1. Navigate to /portal/register.

2. Enter your Full Name, Email Address, and choose a Password (minimum 8 characters).

3. Confirm your password and click Create Account.

4. You are logged in and redirected to your ticket list automatically.

Logging In

1. Navigate to /portal/login.

2. Enter your registered email and password.

3. Optionally check Remember me for 30 days.

4. Click Sign in.

Forgot Password

1. Click Forgot password? on the login page.

2. Enter your email and click Send reset link.

3. Check your inbox for the reset email and click the link.

4. Set a new password and log in.

Dashboard

After logging in you land on your Dashboard. It shows:

• Open Tickets — tickets that are open, in progress, or on hold.
• Resolved — tickets marked as resolved by an agent.
• Closed — tickets that have been closed.
• Recent Tickets — your 5 most recent tickets with status and priority.
• Quick Actions — shortcuts to submit a ticket, view all tickets, browse the knowledge base, and update your profile.

The left sidebar lets you navigate between Dashboard, My Tickets, Knowledge Base, and Profile. Your name and a logout button are at the bottom.

Submit a Ticket

Via the Portal

1. Click + New Ticket in the top bar (or via My Tickets).

2. Enter a clear Subject summarising your issue.

3. Select a Department and Category if applicable.

4. Set the Priority — see the priority guide below.

5. Write a detailed Description of the problem.

6. Attach files if needed (max 5 files, 10 MB each, formats: jpg, png, pdf, doc, docx, txt, zip).

7. Click Submit Ticket. You'll receive a confirmation email with your ticket code.

Via Email

Send an email to the support address configured by your admin (e.g. support@company.com). The system will automatically create a ticket and email you the reference code. Any reply to that email thread is appended to the same ticket.

Priority Guide

Priority	When to use	Target response
Low	General questions, feature requests, no urgency	3 business days
Normal	Standard issues with a workaround available	1 business day
High	Significant issue impacting your workflow	4 hours
Urgent	Critical — system down, no workaround	1 hour

Track & Reply to Tickets

My Tickets List

Go to My Tickets in the sidebar to see all your tickets. You can:

• Search by subject using the search bar.
• Filter by status using the dropdown.
• Click any ticket to open the detail view.

Ticket Detail

The ticket detail page shows the full conversation thread on the left and a details panel on the right. From here you can:

• Reply — type your message in the reply box and click Send Reply. Attach files if needed.
• Reopen — if your ticket was resolved but the issue persists, click Reopen Ticket on the right panel.
• Rate — once a ticket is closed, a rating widget appears. Rate 1–5 stars and optionally leave a comment.

Knowledge Base

The Knowledge Base contains help articles written by your support team. Before submitting a ticket, check if your question is already answered here.

1. Click Knowledge Base in the sidebar.

2. Browse articles or type a keyword in the search bar and press Enter.

3. Click an article to read it.

4. After reading, click Yes or No on the "Was this helpful?" prompt to give feedback.

5. If the article didn't solve your issue, click Still need help? Submit a ticket.

Profile Settings

Click your name in the sidebar or navigate to /portal/profile. There are two tabs:

Account Information

Update your display name and email address, then click Save Changes.

Change Password

Enter your Current Password, then your New Password and confirm it. Click Update Password.

Admin Login

Navigate to /admin/login. Enter your admin email and password. Only active admin accounts can access the panel.

Ticket Queues

Click Tickets in the sidebar. Five queue tabs appear across the top:

Queue	Shows
All Open	Every open, in-progress, and on-hold ticket
Unassigned	Open tickets not yet assigned to an agent
Mine	Tickets assigned to the currently logged-in agent
Overdue	Open tickets with no first response after 24 hours
Recently Closed	Resolved/closed tickets updated in the last 7 days

Filtering

Use the search box and dropdowns above the table to filter by status, priority, category, or department. The queue remembers your filters in the URL so you can bookmark a filtered view.

Bulk Actions

Check the checkbox next to one or more tickets, choose an action from the dropdown (Assign to me, Mark resolved, or Close), and click Apply.

Ticket Workspace

Click any ticket from the queue to open the workspace. The workspace has two columns:

Left column — Thread

• Customer messages appear on a white background.
• Agent replies appear on an indigo/blue background.
• Internal notes (agent-only) appear on a yellow background with "INTERNAL NOTE" label — customers never see these.

Replying

1. Select Reply to Customer or Internal Note using the toggle buttons.

2. Optionally select a Canned Response from the dropdown to insert a pre-written template.

3. Type your message in the text area.

4. Attach files if needed.

5. Click Send. The customer receives an email notification (for public replies only).

Right column — Controls

Control	Description
Status	Change to Open, In Progress, On Hold, Resolved, or Closed
Priority	Set to Low, Normal, High, or Urgent
Assigned Agent	Assign or reassign to any active agent
Department	Move ticket to a different department
Customer	Shows the customer name and email
Merge Into	Enter a target ticket ID to merge this ticket into it (this ticket closes)

Canned Responses

Canned responses are pre-written reply templates that agents can insert into the reply box with one click, saving time for common answers.

Creating a Canned Response

1. Go to Canned Responses in the sidebar.

2. Click New Response.

3. Enter a short Title (visible only to agents in the dropdown).

4. Optionally restrict to a Department.

5. Write the response Body and click Create.

Using a Canned Response

Inside the ticket workspace, select a response from the Insert canned response… dropdown above the reply box. The body is inserted automatically and can be edited before sending.

Knowledge Base (Admin)

Creating an Article

1. Go to Knowledge Base in the sidebar.

2. Click New Article.

3. Enter the Title, select a Category, and write the Content.

4. Set Status to Published to make it visible to customers, or Draft to hide it.

5. Click Create.

Editing an Article

Click any article title in the list to expand an inline edit form. Update the fields and click Save.

Article Analytics

The table shows view count and a helpful ratio (e.g. 42/48 helpful) so you can identify articles that need improvement.

Reports & Analytics

Go to Reports in the sidebar to view performance metrics.

KPI Tiles

Metric	What it shows
Open Tickets	Total open + in-progress + on-hold tickets right now
In Progress	Tickets currently being worked on
Resolved Today	Tickets resolved since midnight today
Overdue	Open tickets with no first response after 24 hours

Charts & Tables

• Tickets by Status — bar chart showing the proportion of each status.
• Tickets per Day — bar chart of ticket volume over the last 30 days.
• Agent Workload — table showing open tickets per agent.
• Average First Response Time — time from ticket creation to first agent reply.
• Average Resolution Time — time from ticket creation to resolved status.

Export to CSV

Click Export CSV in the top-right of the Reports page to download all tickets as a spreadsheet, including customer name, status, priority, assigned agent, and timestamps.

Audit Log

Go to Reports → Audit Log to see a history of all admin actions (status changes, user edits, settings changes) with actor, action, target, IP address, and timestamp.

User Management

Managing Agents & Admins

Go to Admins in the sidebar. This list shows all admin and agent accounts.

1. Click New Admin to open the creation form.

2. Enter the Name and Email.

3. Set Role: admin (full access) or agent (ticket management only, no settings access).

4. Enter a temporary Password and share it with the new user securely.

5. Set Active to Yes. Only active accounts can log in.

6. Click Create.

Editing an Account

Click Edit next to any admin/agent to update their name, email, role, or active status.

Resetting a Password

Click Change Password next to the account, enter and confirm the new password, then click Update. The user must use this new password on their next login.

Deactivating an Account

Edit the account and set Active to No. The user is immediately locked out without deleting their history or ticket assignments.

Managing Customers

Go to Users in the sidebar. This shows all customer portal accounts. You can view, edit, deactivate, or reset passwords from here. Customers can also self-register from the portal.

Notification Bell

The notification bell icon in the top-right of the admin panel shows a red badge with the count of unread notifications.

• New ticket created — appears when a customer submits a ticket via the portal or email.
• Customer replied — appears when a customer adds a reply to an open ticket.

Click the bell to open the notifications dropdown. Click an individual notification to jump directly to that ticket. Use Mark all as read to clear the badge in one click.

Notifications also update in real time — the badge increments without a page refresh when a new ticket or reply arrives.

Departments & Categories

Go to Settings → Departments. This page has two columns:

Departments

• Add a new department by typing a name and clicking Add.
• Click Edit on any department to rename it inline.
• Click Delete to remove a department (tickets in that department will lose their department assignment).

Categories

• Type a category name, optionally select a parent department, and click Add Category.
• Categories appear in the ticket creation form so customers can route their request.
• Delete a category by clicking Delete next to it.

Email / IMAP Settings

Go to Settings → Email / IMAP.

SMTP (Outbound Mail)

Field	Description
Host	Your SMTP server hostname (e.g. smtp.gmail.com)
Port	Usually 587 (TLS) or 465 (SSL)
Username	Your SMTP login email
Password	Your SMTP password (leave blank to keep the current one)
Encryption	TLS (recommended), SSL, or None
From Name	Name shown in the From field of outbound emails
From Email	Email address shown in the From field

IMAP (Inbound / Email-to-Ticket)

Field	Description
Host	Your IMAP server hostname (e.g. imap.gmail.com)
Port	Usually 993 (SSL)
Username	Your support inbox email address
Password	Your mailbox password
Encryption	SSL (recommended)

Testing

After saving, use the Send Test Email section at the bottom of the page to send a test message to any address and verify your SMTP settings are working.

Email Templates

Go to Settings → Email Templates. Customise the subject line and HTML body for each type of automated email.

Available Templates

• Ticket Created — sent to the customer when a new ticket is opened.
• Agent Reply — sent to the customer when an agent sends a public reply.
• Status Changed — sent to the customer when the ticket status changes.

Template Variables

Insert these placeholders anywhere in the subject or body — they are replaced automatically when the email is sent:

Variable	Replaced with
{{code}}	Ticket reference code (e.g. HD-DEMO01)
{{subject}}	Ticket subject line
{{customer_name}}	Customer's display name
{{ticket_url}}	Direct URL to the ticket in the portal
{{priority}}	Ticket priority (Low / Normal / High / Urgent)
{{reply_body}}	Body of the agent's reply (reply template only)
{{previous_status}}	Status before the change (status template only)
{{new_status}}	Status after the change (status template only)

Portal Branding

Go to Settings → Branding.

• Portal Name — the name shown in the browser title, sidebar logo, and email headers (e.g. "Acme Support").
• Primary Color — choose a hex color using the color picker; this updates the accent color across the portal.

Click Save Branding. Changes take effect immediately (may require a hard refresh: Ctrl+Shift+R).

Reverb Status

Go to Settings → Reverb Status. This page shows whether the real-time WebSocket server (Laravel Reverb) is reachable.

• A green indicator means Reverb is running and real-time updates are active.
• A red indicator means Reverb is not running. Tickets still work — they just won't update live without a page refresh.

To start Reverb on the server:

php artisan reverb:start

In production, Reverb is managed by Supervisor automatically. If it has stopped:

supervisorctl start helpdesk-reverb

Ticket Status Reference

Status	Meaning	Next typical step
Open	Ticket received, awaiting agent action	Agent assigns and starts working
In Progress	Agent is actively investigating	Agent replies or resolves
On Hold	Waiting for external info or third party	Resume when info arrives
Resolved	Agent has fixed the issue	Customer confirms or reopens
Closed	Fully complete, no further action	Customer can leave a rating

Troubleshooting

Checking Logs

All application errors are written to the Laravel log file. This is your first stop for any error:

# View the last 100 lines of the log
tail -n 100 /var/www/helpdesk/storage/logs/laravel.log

# Follow the log in real time
tail -f /var/www/helpdesk/storage/logs/laravel.log

500 Internal Server Error

Cause	Fix
No application encryption key has been specified	Run php artisan key:generate
SQLSTATE: Access denied for user	Check DB_USERNAME / DB_PASSWORD in .env
SQLSTATE: No such file or directory	Ensure DB_CONNECTION=mysql and MySQL is running: systemctl status mysql
Permission denied on storage/	Run chown -R www-data:www-data storage bootstrap/cache && chmod -R 775 storage
Blank white page, no error shown	Set APP_DEBUG=true temporarily, reload, then fix the error and set back to false

Emails Not Sending

1. Go to Settings → Email / IMAP and use the Send Test Email button. If it fails, the error message tells you what's wrong.

2. Check the queue is running: supervisorctl status — helpdesk-queue should show RUNNING.

3. Check for failed jobs: php artisan queue:failed. Retry with php artisan queue:retry all.

4. If using Gmail, enable App Passwords and use MAIL_PORT=587 with MAIL_ENCRYPTION=tls.

5. If emails arrive in spam, set up SPF and DKIM DNS records for the sending domain.

IMAP Inbox Not Polling

1. Verify the queue worker is running: supervisorctl status helpdesk-queue:*

2. Test IMAP credentials manually: php artisan tinker then test a connection, or use a desktop mail client with the same credentials.

3. Check IMAP SSL certificate issues — set MAIL_IMAP_ENCRYPTION=notls to diagnose.

4. For Gmail, ensure "Less secure app access" or an App Password is configured.

Real-time / WebSocket Not Working

1. Go to Settings → Reverb Status and note the error shown.

2. Check Reverb is running: supervisorctl status helpdesk-reverb

3. Check the Reverb log: tail -f /var/log/supervisor/helpdesk-reverb.log

4. Verify Nginx is proxying /app/ to port 8080 — check the Nginx config and test with: curl -s http://localhost:8080/app/ | head -5

5. Check that REVERB_APP_KEY in .env matches VITE_REVERB_APP_KEY (rebuild assets if changed: npm run build).

Supervisor Processes Not Starting

# Check all process statuses
supervisorctl status

# Reload after config change
supervisorctl reread && supervisorctl update

# View error details for a specific process
supervisorctl tail helpdesk-reverb stderr

# Restart a stuck process
supervisorctl restart helpdesk-queue:*

Nginx Shows Default Page or 404

# Test config for syntax errors
nginx -t

# Check the site is enabled
ls /etc/nginx/sites-enabled/

# Reload after config changes
systemctl reload nginx

# Check error log
tail -n 50 /var/log/nginx/error.log

Clearing Caches After Changes

php artisan config:clear
php artisan route:clear
php artisan view:clear
php artisan cache:clear

# Then re-cache for production:
php artisan config:cache
php artisan route:cache
php artisan view:cache

Frequently Asked Questions

I submitted a ticket but didn't receive a confirmation email.

Check your spam/junk folder. If nothing is there, ask your admin to verify the SMTP settings under Settings → Email / IMAP. Your ticket was still created and is visible under My Tickets.

Can I reopen a resolved ticket?

Yes. Open the ticket and click Reopen Ticket in the detail panel (visible when status is Resolved or Closed). The ticket reverts to Open.

Can I attach multiple files to a ticket?

Yes — up to 5 files per submission, maximum 10 MB each. Supported formats: jpg, jpeg, png, gif, pdf, doc, docx, txt, zip.

How do I merge duplicate tickets?

Open the ticket you want to close. In the right sidebar, enter the target ticket ID in the "Merge Into" field and submit. All messages and attachments are moved to the target ticket; this ticket is closed.

Emails sent from the support address land in spam.

Ask your admin to set up SPF, DKIM, and DMARC DNS records for the sending domain, and ensure the From Email matches the sending domain.

How do I change the support email address that receives tickets?

Go to Settings → Email / IMAP and update the IMAP credentials to point to the new mailbox. Update your DNS MX records or forwarding rules as needed.

Real-time updates aren't working.

Go to Settings → Reverb Status. If the server shows as unreachable, ask your system administrator to restart the Reverb service via Supervisor.

How do I add a new agent?

Admins can go to Admins in the sidebar and click New Admin. Set the role to agent or admin as needed.