Setting Up a Self-Hosted FreeScout Help Desk

FreeScout serves as a direct, self-hosted alternative to proprietary platforms like Zendesk and Help Scout. Built utilizing PHP and the Laravel framework, the application functions as an open-source help desk and shared inbox. By hosting the software directly, organizations manage their own support infrastructure and customer data without being tied to external services that they do not control.

The system is designed to handle support requests efficiently and is inherently multichannel. Rather than tracking customer issues across different disconnected tools, FreeScout centralizes all customer conversations from various channels in one place.

Server Prerequisites and Environment Preparation

Deploying FreeScout requires a standard LEMP or LAMP stack. The environment must include a web server such as Nginx or Apache, a MySQL or MariaDB database server, and PHP.

When preparing the PHP environment, the choice of version is strictly defined by project compatibility. Administrators should install PHP 8.0 or 8.2 along with the necessary extensions (such as FPM, MySQL, MBString, XML, IMAP, ZIP, GD, cURL, and Intl). It is crucial to adhere to the project's warning regarding specific PHP versions; users are instructed: administrators must not use PHP 8.1 due to critical XML/HTML parsing bugs. PHP 8.2 and newer releases remain fully compatible.

For the database layer, you need to establish a dedicated MySQL or MariaDB database along with a user that has complete privileges over it. Connecting to the database server via the command line allows you to execute the exact required statements.

A dedicated support mailbox email address must also be prepared. FreeScout exclusively manages this inbox, meaning it will automatically mark fetched messages as read. The system ignores emails that have already been opened by users directly accessing the mailbox outside of FreeScout.

Application Download and Directory Configuration

With the environment prepared, you can proceed to download the source code to your web server's root directory. The destination folder (for example, /var/www/html) must be entirely empty before initiating the download. Use Git to clone the repository directly.

This command places the FreeScout application files, including the pre-packaged Composer dependencies from the distribution branch, into the current directory.

Because the web server operates under a specific user account (typically www-data on Debian and Ubuntu systems), the application files require appropriate ownership. Assigning correct ownership ensures the built-in web updater functions as intended and prevents permission-related errors during operation.

By ensuring that all application files are owned by the web server user, FreeScout gains the ability to self-update and write necessary cache or log files. If you manage the server using a distinct SSH user, adding that user to the www-data group allows safe modification of files without disrupting the web server's access rights.

Web Server and Incoming Email Processing

FreeScout routes its frontend through a single entry point. When configuring Nginx, the document root must point to the public subdirectory within the application folder (e.g., /var/www/html/public).

Additionally, Nginx must be configured to pass PHP requests to the PHP-FPM socket and allow for adequate upload sizes to accommodate file attachments on support tickets. If secure HTTPS access is required—which is mandatory for enabling browser push notifications—using Certbot to provision a Let's Encrypt certificate will safely encrypt traffic between agents and the help desk.

Finally, managing incoming support emails requires constant polling. FreeScout relies on background tasks scheduled via the server's cron daemon or managed through queue workers. A cron job invoking the artisan schedule command guarantees that incoming messages are fetched, processed, and distributed to the appropriate unified inbox in a timely manner.