Everything you need to install, set up and run Desklane, the self-hosted help desk with an AI chat that answers from your own articles. Want to see it first? Open the live demo.
Contents
- Requirements
- Services and what they cost
- Installation steps
- Web server
- First steps in the admin
- Tickets and customers
- Knowledge base and help center
- AI and the chat widget
- Email to ticket
- Automations, reports and alerts
- Sending emails
- Colors and look
- Updating
- Good to know
- Troubleshooting
- Support
Requirements
- PHP 8.3 or newer with the extensions
pdo,mbstring,openssl,curl,json,tokenizer,xml,ctype,fileinfo,zipandiconv(all usual on shared hosting; the PHPimapextension is not needed). - A database: MySQL 8 / MariaDB 10.6+ (an empty database and its user), or SQLite for small sites (nothing to create).
- A domain or subdomain, with HTTPS (needed for the customer pages and the chat widget), whose document root is the
publicfolder of Desklane, or Apache 2.4 reading.htaccessfiles (see Web server below). - A way to run a task every minute: a cron line, or a web cron calling a secret URL.
The installer checks all of this and shows what is missing in red.
Services and what they cost
Desklane itself has no monthly fee and takes no commission. Some features use outside services that you choose and pay to them directly:
| Service | Needed for | Cost |
|---|---|---|
| Web hosting with PHP 8.3 and a database | Running Desklane | Your hosting plan (any shared host that meets the requirements works). |
| An email account (SMTP) | Sending ticket replies, notifications and sign-in links | Usually included with your hosting or domain; otherwise a transactional email service (many have a free tier). |
| An AI provider (optional): OpenAI, Anthropic, Google or a compatible service | The AI chat and the AI in tickets | Billed by the provider per use, on your own API key; no fee from Desklane. |
| Zapier, Make or n8n (optional) | Webhooks to your other tools | Their own plans; Desklane sends the webhooks for free. |
Installation steps
- Create the site in your hosting panel and point its document root to the
publicfolder of Desklane. This is the safe setup on every server. If your host does not let you choose the document root, read Web server below first: only Apache with.htaccessfiles allowed is supported then. - MySQL only: create an empty database and a user with all rights on it.
- Upload the zip into the site folder and extract it. The
storageandbootstrap/cachefolders and the.envfile must be writable by PHP (most shared hosts already allow this). For SQLite, thedatabasefolder must be writable too. - Open
https://your-site.com/install. The first visit writes a random setup key tostorage/app/setup-key.txt: open that file with your hosting file manager or FTP (or runphp artisan desklane:setup-key) and paste the key in the form, so nobody else can install on your upload. You can also choose the key yourself withDESKLANE_SETUP_KEY=in.env. Then fill in the name, address, database and your owner account.- The installer runs one installation at a time, creates the tables and the single owner account, checks the result, then closes for good (the address
/installanswers “not found”) and deletes the setup key. - If it stops half-way (an error, a time limit, a server restart), nothing is locked: fix the cause and send the form again with the same database. It removes the tables that the stopped run created (never the tables that were in the database before) and installs again.
- When the document root is not
public, the installer first checks over HTTP that private files are refused, and stops if they are not (see Web server).
- The installer runs one installation at a time, creates the tables and the single owner account, checks the result, then closes for good (the address
- Add the cron job shown at the end of the installer (also in Settings):
- with a command line:
* * * * * php /path/to/desklane/artisan desklane:cron >> /dev/null 2>&1 - with a web cron only: call
https://your-site.com/cron/YOURKEYevery minute.
- with a command line:
Web server
Only the public folder is meant for the web. Everything else (.env with your encryption key and database password, database/ with the SQLite file, storage/ with logs, private attachments, update backups and the setup key, vendor/, config/…) must never be served. These setups are supported; each was checked on a fresh installation (Apache 2.4 with PHP-FPM, Nginx 1.24 with PHP-FPM): the application works and none of those files can be opened.
| Setup | What to do |
|---|---|
Any server, document root = public (best) |
Point the document root of the site to public. Nothing else is needed. |
| Apache 2.4, document root = the Desklane folder | Allowed only when Apache reads .htaccess files (AllowOverride All for that folder) and mod_rewrite is on. The .htaccess at the root sends every request to public; each private folder has its own .htaccess that refuses access, and .env, the database file, logs and archives are refused by name. If mod_rewrite is off, every address answers 403 Forbidden (nothing is shown): turn it on, or use public as the document root. |
| Nginx | The document root must be public. Use this server block (change the paths, the domain and the PHP-FPM address): |
server {
listen 80;
server_name help.example.com;
root /var/www/desklane/public;
index index.php;
charset utf-8;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
fastcgi_param DOCUMENT_ROOT $realpath_root;
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
}
location ~ /\.(?!well-known).* {
deny all;
}
}
Not supported: a document root that is the Desklane folder (or a folder above it) on a server that does not read .htaccess files: Nginx, Apache with AllowOverride None, IIS, Caddy and others. There the private files would be public. The installer detects it (it asks for a random file in storage/, for .env and for a file in vendor/) and refuses to install until the document root is public. LiteSpeed reads Apache .htaccess files, but we have not checked it: use public as the document root there.
Checking it yourself: open https://your-site.com/.env, /storage/logs/, /database/desklane.sqlite and /vendor/composer/installed.json. Each must show an error (403 or 404), never a file. If the installer cannot call its own address (some servers block it), it says so: check these addresses by hand, then set DESKLANE_SKIP_EXPOSURE_CHECK=true in .env to go on.
First steps in the admin
- My account: turn on two-factor sign-in.
- Licence & updates: enter your licence key (copies bought on the Aluleth Market). Copies bought on a marketplace update by uploading the new zip on the same page.
- Company: your company name, support email, website and logo.
- Team: add the people who work with you. Roles: Owner (everything), Admin (everything except licence, updates and owners), Agent (answers tickets and chats, writes help articles), Viewer (reads tickets and articles).
- Settings: name, default language, time zone, sending emails.
Tickets and customers
- Customers write from the contact page (
/support), from the customer portal (/portal, sign-in with a one-time link sent by email, no password) or by phone: your team opens the ticket for them (Tickets → New ticket). - Each email to the customer has a private link to the request: keep it secret, it opens the request without a password.
- Help desk (admin): ticket numbers, who gets an email, files accepted (web pages, SVG pictures and programs are always refused), departments, tags and saved replies. Solved tickets close by themselves after 7 days (the cron job must run).
- Files attached to tickets are kept in
storage/app/private/attachments, outside the web folder.
Knowledge base and help center
- Knowledge base (admin): write articles in Markdown (any HTML is removed), add pictures, choose a category, publish. Team only articles are internal procedures that customers never see.
- The public help center is at
/help, with search, categories, related articles and “Was this article helpful?”. Its sitemap for search engines is/help/sitemap.xml. - While a customer types the subject of a request, matching articles are suggested.
AI and the chat widget
- AI & chat (admin): choose OpenAI, Anthropic (Claude), Google Gemini or any OpenAI-compatible service (Mistral, Groq, OpenRouter, a local Ollama…), paste your own API key, then click Test the AI. The key is kept encrypted and never shown again. You pay the provider directly; set Most AI calls per day to cap the bill (0 = no cap). The cap is one counter for the chat widget and the AI in tickets, and it holds even when many visitors ask at the same moment: each call takes its place in the counter before it is sent. A call counts once it may have reached the provider (answer, error, timeout); it does not count when the provider could not be reached or refused it at once (wrong key, unknown model, rate limit). Test the AI never counts. When the cap is reached, the chat shows the matching help articles and the ticket buttons say that the cap is reached until tomorrow.
- Without a key, everything still works: the chat shows the help articles that match the question, and Draft with AI writes a short reply with links to them.
- What the AI is told, and what Desklane checks. The AI gets your best matching published articles and is told to answer only from them, to name the articles it used, and to say when it does not know (the widget then offers Talk to a person: the conversation becomes a ticket and the visitor gets the usual email). Desklane shows a reply as an answer only when it names at least one of those articles; a reply without a valid article reference is not shown, the matching articles are shown instead. The AI is also told to treat what visitors write as data, not instructions. These are safeguards with limits: an AI can still misread an article or be steered by a cleverly written message, so answers can be incomplete or wrong. The widget says so under every AI answer and always offers a person.
- Masking. Before anything is sent to the provider, Desklane masks the usual formats of email addresses (also written “name [at] domain [dot] com”), phone numbers, card numbers and IBANs, in every part of the request: the visitor’s messages, ticket messages, the help articles quoted (team-only ones too, for drafts) and your AI notes. The masking works with patterns, so a number written in words, split over lines or in an unusual format can get through: keep passwords and other secrets out of articles and notes. Your articles, tickets and notes keep their full text in Desklane.
- Chat widget: turn it on, add the sites allowed to show it (one per line,
https://*.example.comfor all subdomains), and paste the code shown (<script src="https://your-site.com/widget.js" defer></script>) before</body>on those sites. It is also shown on your help center if you want. - In tickets: Draft with AI (reply from the conversation and your articles, team-only ones included), Improve the text (clearer, friendlier, shorter, more formal, spelling, in the customer’s language), Summarize the ticket and, on a solved ticket, Draft a help article from it. The AI only writes in the reply box: a person always reads and sends.
- Live chat: open Live chat and tick I am available for chats. While the page is open, Talk to a person in the widget brings a visitor to your queue; take the chat and answer, transfer it to a colleague, close it or make it a ticket. You can also take over a chat the AI is having. Nobody takes it within the waiting time (3 minutes by default, AI & chat): the visitor is asked for their email instead. The AI stays silent while a person is in the chat.
- Chats (admin): every conversation, what the AI answered, which questions it could not answer (the articles to write next) and which became tickets.
Email to ticket
Three ways, in Email to ticket (admin); use one:
- A mailbox (IMAP): add the support address with the details of “Email accounts” in your hosting panel (IMAP server, port 993 with SSL, the address and its password), then Add and test. New emails are read every 2 minutes by the cron job; choose whether they are marked as read or deleted.
- Pipe (cPanel: Email → Forwarders → Pipe to a program): forward the address to the command shown on the page (
| /usr/bin/php /path/to/desklane/artisan desklane:email). - An email service (Mailgun, SendGrid Inbound Parse, CloudMailin…): post the raw email to the secret address shown on the page.
A new email opens a ticket (with its files, checked like files sent on the web). An answer to one of our emails goes into its ticket, without the quoted text, even if the customer changed the subject. Automatic replies, mailing lists, bounces, our own emails and more than 20 emails an hour from one address are ignored. Last emails received shows what happened to each one.
Each email is handled once, even when it arrives twice at the same time (an email service that retries, two cron runs): one ticket or reply, one set of files, one email to the customer and the team, one webhook event. An email is acknowledged only when it is done:
- while another attempt is still handling it, an email service gets 503 with Retry-After (it delivers it again later), a pipe ends with code 75 (the mail server keeps it and tries again, no bounce) and a mailbox email stays unread for the next cron run;
- if handling fails half-way, nothing is kept and the email is not acknowledged either (error 500, code 75, unread);
- once it is done, or when it was already done before, the email service gets 200 and a mailbox email is marked as read (or deleted).
An attempt stopped by the server (restart, time limit) shows as Being handled; after 15 minutes the next delivery of the same email takes it over. Each attempt has its own token: an attempt that was taken over can no longer finish the email, so even if it wakes up later it adds nothing.
Automations, reports and alerts
- Automations (admin):
- Opening hours and reply target: days, hours (in the time zone of Settings) and the first reply target in opening hours. Late tickets show in the view First reply late.
- New tickets go to: nobody (the team takes them) or each member in turn.
- Rules: when a customer opens a ticket, if the subject or message contains a word, the email ends with a domain, it comes from a channel or a department, then set the priority, the department, a tag or the member.
- Satisfaction: two buttons “Good, thank you / Not good” in the email of a solved ticket, with an optional comment.
- Alerts: new tickets (all or urgent only) and visitors waiting in the live chat, in Slack, Discord or Telegram.
- Purchase checks (for sellers): the contact form and the portal ask for an Envato purchase code (with your Envato personal token) or a licence key checked by your own licence server. The ticket shows the product and until when support runs; you can refuse requests without a valid code.
- Reports: new tickets per day, first reply and time to solve (medians), reply target met, satisfied customers, by channel, by member, the chat and the AI, and the questions the AI could not answer.
Sending emails
Settings → Sending emails: choose SMTP server and enter the details your host gives in “Email accounts” (server, port 465 with SSL or 587 with TLS, user name, password). Use a sender address of your own domain, then click Send a test email to me. Until this is set up, emails are only written to storage/logs.
Colors and look
- Chat widget: AI & chat → Chat widget → Color and Side. No file to edit.
- Admin, help center, portal and contact page: one stylesheet,
public/css/desklane.css. Its first block,:root { … }, holds every color; change the values there:--accent: #0f766ebuttons, links, the selected menu entry, the charts;--accent-ink: #fffffftext on the buttons;--accent-soft: #e2f2eflight backgrounds of the selected entries and suggestions;--bgpage background,--panelcards,--panel-2light grey areas,--lineborders,--texttext,--mutedsecondary text;--good,--warn,--bad(and their-softversions) for the green, orange and red labels;--radiusthe corners,--fontthe font. The block just after it,@media (prefers-color-scheme: dark), holds the same names for dark mode: change both. Reload the page with Ctrl+F5 (or Cmd+Shift+R) to see the change.
- Your logo appears in the admin, the customer pages and the emails: Company → Logo.
- Emails: the button color is
#0f766einresources/views/emails/ticket.blade.php,portal-link.blade.phpandteam-notice.blade.php; the frame isresources/views/emails/layout.blade.php. After a change, runphp artisan view:clear(or delete the files instorage/framework/views). - An update replaces these files: keep a copy of your changes (the replaced files are also saved in
storage/app/updates).
Updating
- With an active licence: Licence & updates → Update to x.y.z.
- Without: download the new full zip, then Licence & updates → Update from a zip.
- If the server refuses the upload (the zip is about 24 MB and some hosts allow less): extract the zip on your computer and upload its files over the old ones by FTP, keeping your
.envfile andstoragefolder. Database changes apply on the next visit.
How an update from Licence & updates works (one update at a time):
- Desklane checks the zip (Desklane package, newer version, safe paths, writable files) and extracts the whole new release in
storage/app/updates, compared file by file with the zip, before anything changes. - It saves every file it is going to replace,
vendor/included, instorage/app/updates/backup-<version>-<date>.zip, reads the backup back, and writes a journal (storage/app/updates/journal.json) with the list of files that are new in this release. - It copies the files, each one written next to its place and then renamed, so no file is ever half-written. Visitors get a short “Desklane is being updated” page meanwhile.
- On the next page, the new release saves a copy of the whole database (
storage/app/updates/database-<version>-<date>.json.gz: every table, its structure and all its rows), then applies its database changes.
If anything goes wrong, the update is undone, automatically:
- a file cannot be written, or the process stops during the copy (time limit, server restart): the next visit puts the old files back from the backup and removes the new ones, before any of the new code runs;
- a database change fails, or the process stops during the database changes: the database is put back from the copy and the files from the backup.
Either way the previous version runs again, and Licence & updates says that the update was undone; you can try again. The 3 newest backups and database copies are kept. Your .env file, storage folder and uploaded files are never replaced. The update to 0.1.4 itself is made by the updater of your current version; these protections apply to the updates after it.
Undo by hand: on the server, php bootstrap/recover.php undoes an unfinished update (--status only shows it); it needs neither Composer nor Laravel. Without a command line: extract the latest backup-*.zip of storage/app/updates over the Desklane folder, delete the files listed under created in journal.json, then delete journal.json; for the database, run php bootstrap/recover.php --database storage/app/updates/database-<version>-<date>.json.gz with the copy made by that update (it replaces every table), or restore your own database backup. If you uploaded files by FTP instead (see above), no automatic copy is made: back up the database and the folder first.
Good to know
- The admin is at
/admin. Change it withDESKLANE_ADMIN_PATH=in.env. - Keep
APP_DEBUG=falsein production. - Back up the database and the
.envfile: it holds the encryption key of the installation. - Locked out with no email set up? On the server, run
php artisan desklane:reset-password you@example.com: it prints a new password and turns off two-factor sign-in for that account.
Troubleshooting
| Problem | What to do |
|---|---|
| The installer shows a line in red | Install the missing PHP extension or version in your hosting panel, or make the folder writable, then reload the page. |
| Notifications or background work do not happen | The cron job never ran: add the cron line or the web cron (Settings → Cron job shows the last run), then wait one minute. |
| Blank page or error 500 | Check that PHP is 8.3 or newer and that storage, bootstrap/cache and .env are writable. The details are in storage/logs/laravel.log. |
| 403 Forbidden on every page | The document root is the Desklane folder and mod_rewrite is off: turn it on, or make public the document root (Web server). |
| The installer says private files can be opened from the web | Make public the document root of the site, or use Apache with .htaccess files allowed (Web server). |
| “Desklane is being updated” for more than a few minutes | An update stopped and could not be undone by itself: run php bootstrap/recover.php on the server, or see Updating. |
| Emails do not arrive | Settings → Sending emails → Send a test email to me. Check the spam folder, use a sender address of your own domain, and ask your host for the right port and security (SSL 465 or TLS 587). |
| Locked out and no email set up | On the server, run php artisan desklane:reset-password you@example.com: it prints a new password and turns off two-factor sign-in for that account. |
| Where is the admin? | At /admin. Change it with DESKLANE_ADMIN_PATH= in .env. |
Support
- Bought on a marketplace (WPBay, Codester…): contact the author through the support or message page of the item on that marketplace. Updates are downloaded there too.
- Bought on the Aluleth Market: write to us from https://market.alulethmarketing.com/support/ with your order number. Updates come with one click while your licence is active.
Please give the Desklane version (bottom of the admin menu and Licence & updates), your PHP version and, for an error, the last lines of storage/logs/laravel.log. Support covers installing and using Desklane; it does not cover changes to its code, your hosting or the outside services above.