Installation Guide

FreeScout edited this page Nov 22, 2018 · 119 revisions
  1. Prerequisites
  2. Installing Package Dependencies
  3. Configuring PHP7
  4. Configuring MySQL
  5. Downloading the Application
  6. Configuring Web Server
    1. Nginx
    2. Apache
  7. Restarting Services
  8. Installing the Application
    1. Using web installer
    2. Manual installation
  9. Configuring Cron Jobs
  10. Checking Installation

1. Prerequisites

Prerequisites required to run FreeScout are listed here. In this tutorial we are going to install FreeScout on Ubuntu 16.04 and use Nginx/Apache as a web server, but you can use any web server you like (Nginx, Apache, IIS, etc).

If you prefer to use Docker, here is the Docker image.

Before you start installation of the FreeScout please make sure to read about choosing a server and blacklists check and learn about sending emails. You will also need a mailbox email address which will be used to send outgoing emails and fetch incoming emails, so you need IMAP or POP3 access to this email.

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

2. Installing Package Dependencies

Nginx

sudo apt-get update
sudo apt remove apache2
sudo apt install nginx

PHP7

Install PHP7.1 in FPM mode and all required extensions.

sudo apt install php7.0 php7.0-mysqli php7.0-fpm php7.0-mbstring php7.0-xml php7.0-imap php7.0-json php7.0-zip

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

MySQL

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

Git

sudo apt install git

3. Configuring PHP7

For FPM we need to fix_pathinfo:

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

4. Configuring MySQL

Log into the MySQL root administrative account:

mysql -u root -p

Create FreeScout database and user:

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

5. Downloading the Application

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

mkdir -p /var/www/html
sudo chown freescout:freescout /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 https://freescout.net/download/ 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):

git clone https://github.com/freescout-helpdesk/freescout .

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

If you are planning to use composer and contribute to the project, run also the following commands:

git pull origin master
git checkout master

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. The application directory is owned by our system user, freescout, and is readable but not writable by the web server (www-data). But there are few directories where the web server must be able to write files. So we are changing the group ownership of the storage and bootstrap/cache directories to www-data (or apache for CentOS/RedHat):

sudo chgrp -R www-data storage bootstrap/cache public/css/builds public/js/builds
sudo chmod -R ug+rwx storage bootstrap/cache public/css/builds public/js/builds

Web installer will need to create .env file for you in the root /var/www/html/ of your application:

sudo chgrp www-data /var/www/html
sudo chmod ug+rwx /var/www/html

6.1 Nginx

Create a new server config file by copying over the default file:

sudo cp /etc/nginx/sites-available/default /etc/nginx/sites-available/example.com
sudo nano /etc/nginx/sites-enabled/example.com

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 index.nginx-debian.html;

    server_name example.com www.example.com;

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

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    location ~ \.php$ {
	try_files $uri =404;
	fastcgi_split_path_info ^(.+\.php)(/.+)$;
	fastcgi_pass unix:/run/php/php7.0-fpm.sock;
	fastcgi_index index.php;
	fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
	include fastcgi_params;
    }
    location ~* \.(?:jpg|jpeg|gif|png|ico|cur|gz|svg|svgz|mp4|ogg|ogv|webm|htc|svg|woff|woff2|ttf)$ {
        expires 1M;
	access_log off;
	add_header Cache-Control "public";
    }
    location ~* \.(?:css|js)$ {
	expires 2d;
	access_log off;
	add_header Cache-Control "public, must-revalidate";
    }
    location ~ /\. {
        deny  all;
    }
}

6.2 Apache

Make sure that Apache mod_rewrite is enabled.

Apache virtual host configuration:

<VirtualHost *:80>
  ServerName example.com
  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
  </Directory>
</VirtualHost>

7. Restarting Services

Nginx:

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

Apache:

service apache2 restart
service php7.0-fpm restart

8. Installing the Application

There are two ways to install the app:

  • Use web installer (recommended).
  • Install manually.

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.

Open web installer https://example.com/install and follow instructions:

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

  1. Check PHP extensions
  2. Check folders permissions
  3. Enter database details
  4. Choose application timezone
  5. 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 your SSH user (if you don't know how to do it, contact your hosting provider).

crontab -e

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

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

10. Checking Installation

Open and check your FreeScout installation at https://example.com

If you are receiving the following error message upon logging in:

file_put_contents(/var/www/html/storage/framework/cache/data/): failed to open stream: no such file or directory

just run again the following commands:

sudo chgrp -R www-data storage bootstrap/cache public/css/builds public/js/builds
sudo chmod -R ug+rwx storage bootstrap/cache public/css/builds public/js/builds

If you forgot your admin password, just create a new admin user via console:

php artisan freescout:create-user

If styles or JavaScripts are working incorrectly, manually create a /public/storage symlink:

ln -s storage/app/public public/storage

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

Got to Settings » Mail Settings and set Mail From for outgoing system emails (alerts to admin and invitation emails to users).

If you get any errors, check app logs in Manage » Logs

You can also enable debugging 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
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.