Installation12 min readApril 28, 2025

FreeScout Installation Guide: Complete Setup (2025)

The complete FreeScout installation guide — server requirements, step-by-step setup, SSL, email configuration, and why most businesses hire an expert instead.

FreeScout is the most popular open-source helpdesk software available today — a self-hosted alternative to Zendesk and Freshdesk that costs nothing in monthly fees. But installing it correctly is a different story.

This guide covers everything: server requirements, the full installation process, SSL, email deliverability, and the hidden complexities that catch most teams off guard.

Want to skip straight to a working helpdesk?

We handle the full FreeScout installation on your server — SSL, email, security hardening, and a 1-hour onboarding call. Done in 24 hours.

Get It Installed for $100View All Packages

One-time fee · 30-day support · Money-back guarantee

What is FreeScout?

FreeScout is a free, open-source help desk and shared inbox built with Laravel. It runs on your own server, stores your data under your control, and has no per-agent pricing or monthly subscription fees.

Key capabilities:

  • Shared mailboxes — your whole team works from one inbox
  • Ticket management — assign, tag, prioritize, and track every conversation
  • Email integration — works with any SMTP provider
  • 50+ modules — live chat, knowledge base, AI replies, reports, satisfaction ratings
  • White-label — fully brandable with your own logo and colors

The catch: it's self-hosted. You need a server, and you need to configure it.

Server Requirements

Before you install FreeScout, you need a VPS that meets these minimum requirements:

| Requirement | Minimum | Recommended | |---|---|---| | OS | Ubuntu 20.04 | Ubuntu 22.04 LTS | | RAM | 1 GB | 2 GB | | CPU | 1 vCPU | 2 vCPU | | Disk | 20 GB SSD | 40 GB SSD | | PHP | 7.4 | 8.2 | | Database | MySQL 5.6+ | MySQL 8.0 | | Web server | Apache / NGINX | NGINX |

Recommended VPS providers: Hetzner (best value), DigitalOcean (easiest), Vultr, Linode.

A €4/month Hetzner CX11 (2GB RAM, 2 vCPU) is perfectly sufficient for most teams.

The Full Installation Process

Here is what a complete FreeScout installation involves. Read this carefully before deciding whether to do it yourself.

Step 1: Server preparation

Update your server and install required packages:

sudo apt update && sudo apt upgrade -y
sudo apt install -y nginx mysql-server php8.2 php8.2-fpm \
  php8.2-mysql php8.2-mbstring php8.2-xml php8.2-curl \
  php8.2-imap php8.2-zip php8.2-gd php8.2-bcmath \
  php8.2-intl unzip git curl

Step 2: MySQL database setup

sudo mysql_secure_installation
sudo mysql -u root -p

CREATE DATABASE freescout CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'freescout'@'localhost' IDENTIFIED BY 'your_strong_password';
GRANT ALL PRIVILEGES ON freescout.* TO 'freescout'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Step 3: Download FreeScout

cd /var/www
sudo git clone https://github.com/freescout-helpdesk/freescout.git
sudo chown -R www-data:www-data /var/www/freescout
sudo chmod -R 755 /var/www/freescout

Step 4: Composer dependencies

cd /var/www/freescout
sudo -u www-data composer install --no-dev

Step 5: Environment configuration

sudo cp .env.example .env
sudo nano .env

Configure your database credentials, app URL, and mail settings. This file has 40+ variables that all need to be set correctly.

Step 6: Laravel setup

sudo -u www-data php artisan key:generate
sudo -u www-data php artisan migrate --force
sudo -u www-data php artisan freescout:after-app-update
sudo -u www-data php artisan storage:link

Step 7: NGINX configuration

Create a server block at /etc/nginx/sites-available/freescout:

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/freescout/public;
    index index.php;

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

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

    location ~ /\.ht {
        deny all;
    }
}

Step 8: SSL certificate

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

Certbot will modify your NGINX config and set up auto-renewal. If your DNS isn't propagated yet, this will fail.

Step 9: Queue workers (critical — most people miss this)

FreeScout uses Laravel queues for email fetching and sending. Without a running queue worker, emails won't be processed.

Create a supervisor config at /etc/supervisor/conf.d/freescout-worker.conf:

[program:freescout-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/freescout/artisan queue:work --sleep=3 --tries=3 --timeout=60
autostart=true
autorestart=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/freescout/storage/logs/worker.log

sudo apt install -y supervisor
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start freescout-worker:*

Step 10: Cron job

sudo crontab -u www-data -e

Add:

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

Email Configuration (Where Most Installations Break)

Email is the hardest part of FreeScout. You need to configure two separate things:

Outgoing mail (SMTP): FreeScout sends notification emails and replies through an SMTP server. You can use Gmail, SendGrid, Mailgun, Amazon SES, or your own server.

Incoming mail (IMAP): FreeScout fetches new tickets by polling your mailbox via IMAP. The polling interval, connection timeout, and SSL settings all need to be correct.

Beyond SMTP/IMAP, email deliverability requires:

  • SPF record — tells receiving servers your server is allowed to send from your domain
  • DKIM — cryptographically signs outgoing emails to prove they're genuine
  • DMARC — policy that handles emails failing SPF/DKIM checks
  • Reverse DNS (PTR record) — your server IP must resolve back to your domain

Miss any one of these and your emails land in spam.

Security Hardening

A default FreeScout installation is not production-ready from a security standpoint. You need:

# Firewall
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

# Fail2ban — blocks brute force attacks
sudo apt install -y fail2ban
sudo systemctl enable fail2ban

# Disable root SSH login
sudo nano /etc/ssh/sshd_config
# Set: PermitRootLogin no
# Set: PasswordAuthentication no
sudo systemctl restart sshd

How Long Does FreeScout Installation Take?

An experienced Linux sysadmin who has done it before: 3–4 hours.

A team doing it for the first time, troubleshooting issues: 1–3 days.

Common points of failure:

  • PHP version conflicts
  • MySQL permission errors
  • NGINX misconfiguration causing 502 errors
  • SSL certificate failing due to DNS not propagated
  • Queue workers not starting properly
  • Email not sending due to SMTP port blocking
  • Emails landing in spam due to missing SPF/DKIM

The Alternative: Professional Installation

If you're reading this guide and thinking "this is more complex than I expected" — you're not alone. This is exactly why most businesses hire an expert.

Our professional FreeScout installation service:

  • Completes in 24 hours — not 3 days of troubleshooting
  • Includes everything — NGINX, PHP, MySQL, SSL, SPF, DKIM, DMARC, firewall, fail2ban
  • Email deliverability guaranteed — your emails won't land in spam
  • 30 days of support — we fix any issues that come up after go-live
  • 1-hour onboarding call — your team learns how to use FreeScout properly
  • One-time fee from $100 — no monthly subscription, ever

This took you 12 minutes to read. The installation takes 6 hours. We do it in 24 hours for $100.

We handle the full FreeScout installation on your server — SSL, email, security hardening, and a 1-hour onboarding call. Done in 24 hours.

Get It Installed for $100View All Packages

One-time fee · 30-day support · Money-back guarantee

Frequently Asked Questions

Can I install FreeScout on shared hosting? No. FreeScout requires SSH access, Composer, PHP CLI, and a queue worker — none of which are available on shared hosting. You need a VPS.

Which PHP version should I use? PHP 8.2 is recommended. PHP 7.4 reaches end of life and has security vulnerabilities. FreeScout is fully compatible with 8.2.

Does FreeScout work with Gmail? Yes, but Google has restricted less secure app access. You need to configure OAuth2 or use an app password with 2FA enabled.

How many emails can FreeScout handle? A 2GB RAM VPS handles hundreds of tickets per day comfortably. For high-volume operations (1000+ tickets/day), you'll want 4GB RAM and Redis for queue management.

Is FreeScout GDPR compliant? Yes — because it's self-hosted, your data never leaves your server. This makes FreeScout inherently GDPR-compliant, unlike SaaS alternatives.

Resources

Need FreeScout Installed Professionally?

Skip the complexity. We install and configure FreeScout on your server in 24 hours — SSL, email, security, and a full onboarding call included.

Get It Done for $100

One-time fee · 30-day support · Money-back guarantee

Related Articles