Installation Guide - freescout-helpdesk/freescout Wiki

  1. Prerequisites
  2. Installing Package Dependencies
  3. Configuring PHP
  4. Configuring MySQL
  5. Downloading the Application
  6. Configuring Web Server
    1. Nginx
    2. Apache
    3. IIS
  7. Restarting Services
  8. Installing the Application
    1. Using web installer
    2. Manual installation
  9. Configuring Cron Jobs
  10. Final Configuration
  11. Troubleshooting


Images & one-click installs:

Interactive installation bash-script (Ubuntu):

sudo apt install wget
chmod u+x
sudo ./

Systems-specific tutorials:

Cloud Hosted

1. Prerequisites

Prerequisites required to run FreeScout are listed here. In this tutorial we are going to install FreeScout on Ubuntu LTS and use Nginx/Apache as a web server, but you can use any web server you like (Nginx, Apache, IIS, etc). Before you start installation please make sure to read about choosing a server.

You will also need a mailbox email address which will be used to fetch incoming emails (and optionally to send outgoing emails). This email can be set up anywhere (Gmail, G Suite, Yahoo, Office365, Zoho Mail, etc). This email is supposed to be accessed via FreeScout only, as all incoming emails will be automatically marked as READ and FreeScout will not fetch emails which have been read by people accessing the mailbox. If in your company you already have a mail server allowing SMTP and IMAP connection, just create a new email address (for example, [email protected]) and use it as a support mailbox email.

Make sure to learn about sending emails.

If you want to connect FreeScout to G Suite or Microsoft Office 365 via OAuth see this instruction.

Keep in mind that for the browser push notifications to work, HTTPS protocol is required.

2. Installing Package Dependencies


sudo apt-get update
sudo apt remove apache2
sudo apt install nginx
sudo rm /var/www/html/*nginx*.html


Install PHP 7.1 - 8.x in FPM mode and all required extensions.

sudo apt install php7.4 php7.4-mysqli php7.4-fpm php7.4-mbstring php7.4-xml php7.4-imap php7.4-json php7.4-zip php7.4-gd php7.4-curl

Make sure that extensions are also enabled in console version by running: php -m


sudo apt install mysql-server libmysqlclient-dev

If you want to use MariaDB (it will automatically remove the mysql-server installation if any):

sudo apt install mariadb-server libmysqlclient-dev


sudo apt install git

3. Configuring PHP

For FPM we need to fix_pathinfo:

If you are working under the root user:

echo ‘cgi.fix_pathinfo=0’ >> /etc/php/7.4/fpm/php.ini

In other cases:

sudo -- "$SHELL" -c "echo 'cgi.fix_pathinfo=0' >> /etc/php/7.4/fpm/php.ini"

4. Configuring MySQL

Log into the MySQL root administrative account:

mysql -u root -p

Create FreeScout database and user (replace "XXX" with the real password):

CREATE DATABASE `freescout` CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON `freescout`.* TO `freescout`@`localhost` IDENTIFIED BY "XXX";

If above code does not work try:

CREATE USER 'freescout'@'localhost' IDENTIFIED BY 'XXX';
GRANT ALL PRIVILEGES ON `freescout`.* TO `freescout`@`localhost`;

5. Downloading the Application

Create the new directory, set permissions. Make sure to replace /var/www/html with the path on your server (this is just an example):

sudo mkdir -p /var/www/html
sudo chown www-data:www-data /var/www/html
cd /var/www/html

Now you need to download the app. There are two ways to do it:

  1. Download the application build from and extract it into /var/www/html. This method can be used if installing via cPanel for example.

  2. Download the app using Git into the current directory (it must be empty):

sudo git clone .

This will install the app from dist branch with all the composer dependencies included.

If you are planning to contribute to the project

Run the following commands:

git pull origin master
git checkout master

When running composer commands always add --ignore-platform-reqs flag: composer install --ignore-platform-reqs

When making a pull request make sure to submit it to the master branch, NOT dist!!!

6. Configuring Web Server

We are installing application in /var/www/html/ (application directory), so server's web root directory must be /var/www/html/public.

Web server runs as www-data user. All application files must be owned by www-data, so that application can self-update itself.

Run the following command to make sure that www-data user is the owner of all the files in the application directory:

sudo chown -R www-data:www-data /var/www/html

Now if you have some SSH user (for example freescout) which you are going to use for development, add this user to www-data group to allow edit files and folders created by the web server. If you are not going to work with files via SSH/FTP just skip this step.

www-data must be the primary group of the freescout user. Otherwise you will be getting a Permissions issue

sudo  usermod -g www-data freescout

find /var/www/html -type f -exec chmod 664 {} \;    
find /var/www/html -type d -exec chmod 775 {} \;

If you are installing FreeScout in a subdirectory, just make corresponding changes in the web server configuration files and specify proper App URL when installing the app.

6.1 Nginx

Create a new server config (make sure to replace "" with your actual site name):

sudo cp /etc/nginx/sites-available/default /etc/nginx/sites-available/
sudo rm /etc/nginx/sites-enabled/default
sudo ln -s /etc/nginx/sites-available/ /etc/nginx/sites-enabled/
sudo nano /etc/nginx/sites-enabled/

The modified Nginx configuration file will look like this:

server {
    listen 80;
    listen [::]:80;


    root /var/www/html/public;

    index index.php index.html index.htm;

    error_log /var/www/html/storage/logs/web-server.log;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    location ~ \.php$ {
	fastcgi_split_path_info ^(.+\.php)(/.+)$;
	fastcgi_pass unix:/run/php/php7.4-fpm.sock;
	fastcgi_index index.php;
	fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
	include fastcgi_params;
    # Uncomment this location if you want to improve attachments downloading speed.
    # Also make sure to set APP_DOWNLOAD_ATTACHMENTS_VIA=nginx in the .env file.
    #location ^~ /storage/app/attachment/ {
    #    internal;
    #    alias /var/www/html/storage/app/attachment/;
    location ~* ^/storage/attachment/ {
        expires 1M;
        access_log off;
        try_files $uri $uri/ /index.php?$query_string;
    location ~* ^/(?:css|js)/.*\.(?:css|js)$ {
        expires 2d;
        access_log off;
        add_header Cache-Control "public, must-revalidate";
    location ~* ^/(?:css|fonts|img|installer|js|modules|[^\\\]+\..*)$ {
        expires 1M;
        access_log off;
        add_header Cache-Control "public";
    location ~ /\. {
        deny  all;

Apply Nginx config:

nginx -t
service nginx reload

Install Certbot:

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo certbot --nginx

The specific commands to use for different distros can be obtained from

Enable HTTPS on Nginx and test automatic certificate renewal:

certbot --nginx --register-unsafely-without-email
certbot renew --dry-run

When asked choose option 2: Redirect - Make all requests redirect to secure HTTPS access.

Add to root crontab:

0 12 * * * /usr/bin/certbot renew --quiet

If you want to set up the FreeScout behind Nginx proxy see this instruction.

6.2 Apache

Apache virtual host configuration:

<VirtualHost *:80>
  DocumentRoot "/var/www/html/public"
  Options Indexes FollowSymLinks
  ErrorLog /var/www/html/storage/logs/web-server.log
  <Directory "/var/www/html/public">
    AllowOverride All
    Require all granted

To install FreeScout into a subdirectory no need to create extra .htaccess files, just make sure to set proper path in Directory parameter.

Make sure that Apache mod_rewrite is enabled, otherwise you will always receive 404 Not Found error in browser. To enable mod_rewrite do the following:

sudo a2enmod rewrite
sudo systemctl restart apache2

If you receive error 500, try to add the following to the Apache virtual host configuration:

RewriteBase /

6.3 IIS

Import the .htaccess file using URL Rewrite.

Select URL Rewrite > Import Rules > ... > select .htaccess from the public directory > Delete the line highlighted in red.

Install cygwin.

7. Restarting Services


nginx -t
service nginx restart
service php7.4-fpm restart


service apache2 restart
service php7.4-fpm restart

8. Installing the Application

There are two ways to install the app:

8.1 Using web installer

If you want to use web installer, DO NOT create .env file manually. If .env file exists in the root of your app, web installer won't run. To run web installer, remove .env file and /storage/.installed (if exists), then remove all files from /bootstrap/cache`.

Open web installer and follow instructions:

Installation wizard will guide you through the steps of installation process:

  1. Check PHP extensions
  2. Check folders permissions
  3. Choose database type: MySQL or PostrgeSQL
  4. Enter database details
  5. Choose application timezone
  6. Create admin user

8.2 Manual installation

This method is for advanced users who can use SSH console.

  1. Copy .env.example as .env and make appropriate changes in the file.
  2. Generate APP_KEY in the .env file:
php artisan key:generate
  1. Clear application cache and apply .env file changes:
php artisan freescout:clear-cache
  1. Create a symbolic link from "public/storage" to "storage/app/public"
php artisan storage:link
  1. Create tables:
php artisan migrate
  1. Create admin user:
php artisan freescout:create-user

9. Configuring Cron Jobs

Set up a cron task for www-data SSH user (if you don't know how to do it, contact your hosting provider).

crontab -u www-data -e

* * * * * php /var/www/html/artisan schedule:run >> /dev/null 2>&1

Make sure to replace /var/www/html/ with the path to your installation. On some shared hostings you may need to specify full path to the PHP executable (for example, /usr/local/bin/php-7.4).

This command runs every minute and also makes sure one instance of it runs as a daemon in the background.

In you are using Plesk, see this instruction.

Make sure that the cron task user is not messing up file permissions. Otherwise you will be getting a Permissions issue

If regular cron jobs are not functioning on your hosting cron job can be executed via the URL which can be found in "Manage » System » Cron Commands". But this method is not recommended as some features may not work as expected. Use it at your own risk.

10. Final Configuration

Got to Settings » Mail Settings and configure System Emails (alerts to admin and invitation emails to users).

In Settings » Alerts you can configure receiving alerts by email when some errors occur in the app.

If you want to store attachments using something like S3 – see this.

11. Troubleshooting

Make sure that your system configuration is fine in Manage » System

If you get any errors, check app logs in Manage » Logs » App Logs. If you have problems with loading JavaScript, menu will not work, so you need to check logs on the server in storage/logs folder.

You can also enable debugging (only if installed manually from master) to see error messages in your browser by uncommenting the following in .env file (don't forget to remove it when you finish debugging): APP_DEBUG=true

— Permissions issue

This is the most common issue. Usually failed to open stream or File /modules/modulename/js/laroute.js does not exist errors mean that you have permissions issue.


file_put_contents(/var/www/html/storage/framework/cache/data/): failed to open stream: no such file or directory
file_put_contents(/var/www/html/storage/framework/cache/data/5e/3c/5e3cbbed47195384f39edf30b47d8cd8245cdff8): failed to open stream: Permission denied
Error: File '/www/html/public/storage/js/vars.js' does not exist
File /modules/modulename/js/laroute.js does not exist
File /modules/modulename/css/module.css does not exist
Error occurred creating [...] symlink: symlink(): No such file or directory


This issue means that the web server user does (www-data) not have permissions to write in some folder in storage. Make sure that web server user (www-data) has write permissions in storage folder and run again the following commands:

sudo chown -R www-data:www-data /var/www/html

Also make sure that the cron task user is not messing up file permissions.

— open_basedir restriction in effect

Try this.

— queue:work is not running

Try to add to add the following cron job:

crontab -u www-data -e

* * * * * php /var/www/html/artisan queue:work --queue='emails,default' --sleep=5 --tries=1 >> /dev/null 2>&1

On some shared hostings you may need to specify the full path to the PHP executable (for example, /usr/local/bin/php-7.4).

— If styles or JavaScripts are working incorrectly (top menu is not working)

Manually create a /public/storage symlink:

php artisan storage:link

or create symlink manually:

ln -s /var/www/html/storage/app/public public/storage

Make sure that PHP is able to write to public/css/builds and public/js/builds (see Configuring permissions)

— FreeScout redirects into public/public ("Request exceeded the limit of 10 internal redirects")

This error is mostly related to the Apache web server. In this case check your Apache redirect rules, check or remove all higher-level .htaccess file. Try to add the following to the Apache virtual host configuration: RewriteBase /

— I'm activating (deactivating) a module but it stays inactive (active)

It means that in /storage/framework/cache/data/ there are files created by a user different from www-data, and www-data user can not completely clear cache. Run the following command to make www-data user an owner of all the FreeScout files:

sudo chown -R www-data:www-data /var/www/html

— If you forgot your admin password

Just create a new admin user via console:

php artisan freescout:create-user

— FreeScout is crashing as cache files are being created as root

Make sure you don't run any cron jobs under root user.

— Inline images do not display and attachments lead to 404 errors

In Manage » System make sure that directories are writable.

If you are using Nginx, make sure it has correct config.

— FreeScout displays incorrect time

— If browser push notifications are not working

— If HTTPS is configured but the app is loading via HTTP instead of HTTPS

Set correct APP_URL in .env file and clear cache in Manage » System » Tools.

— Emails are not delivered

See this.

— Emails are not fetched

See this.

— FreeScout sends multiple duplicate emails to customers

See this.

— Composer does not work

When running composer commands always add --ignore-platform-reqs flag: composer install --ignore-platform-reqs