Install FreeScout on Ubuntu 22.04 — Step by Step (2025)

This is the most complete guide to installing FreeScout on Ubuntu 22.04 available. It covers every step from a fresh VPS to a fully working helpdesk — including SSL, email deliverability, queue workers, and security hardening.

Estimated time to complete: 4–6 hours for a first-time installation. Common issues at each step are listed so you don't spend hours debugging.

Don't want to spend 6 hours on this? Our professional installation service does everything in this guide — plus security hardening, DKIM/DMARC setup, and a 1-hour onboarding call — for $100. Skip to the service →

Prerequisites

Before you start, you need:

• A VPS running Ubuntu 22.04 LTS (fresh install recommended)
• A domain name with DNS access
• SSH access to your server
• At least 2GB RAM (1GB will work but expect slowness)

Recommended providers: Hetzner CX21 (€5/mo), DigitalOcean Droplet ($12/mo), Vultr Cloud Compute.

Step 1: Initial Server Setup

SSH into your server and update everything:

ssh root@your-server-ip
apt update && apt upgrade -y
apt install -y curl wget git unzip supervisor

Create a non-root user (security best practice):

adduser freescout
usermod -aG sudo freescout
su - freescout

Step 2: Install PHP 8.2

Ubuntu 22.04 ships with PHP 8.1. FreeScout works best with PHP 8.2:

sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update
sudo apt install -y 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 php8.2-tokenizer php8.2-fileinfo

Verify installation:

php8.2 --version
# PHP 8.2.x

Common error: add-apt-repository: command not found → run apt install software-properties-common first.

Step 3: Install and Configure MySQL

sudo apt install -y mysql-server
sudo mysql_secure_installation

Answer the prompts:

• Set root password: Yes (use a strong password)
• Remove anonymous users: Yes
• Disallow root login remotely: Yes
• Remove test database: Yes
• Reload privilege tables: Yes

Create the FreeScout database:

sudo mysql -u root -p

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

Common error: ERROR 1819 (HY000): Your password does not satisfy the current policy requirements → use a password with uppercase, lowercase, numbers, and symbols.

Step 4: Install NGINX

sudo apt install -y nginx
sudo systemctl enable nginx
sudo systemctl start nginx

Step 5: Install Composer

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
composer --version

Step 6: 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
sudo find /var/www/freescout/storage -type d -exec chmod 775 {} \;

Install PHP dependencies:

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

This step downloads ~100 packages and takes 3–5 minutes. If it fails, check your PHP extensions are all installed.

Step 7: Configure the Environment File

sudo cp /var/www/freescout/.env.example /var/www/freescout/.env
sudo nano /var/www/freescout/.env

Update these values:

APP_URL=https://your-domain.com
APP_KEY=  # leave blank, generated in next step

DB_DATABASE=freescout
DB_USERNAME=fsuser
DB_PASSWORD=use_a_strong_password_here

MAIL_DRIVER=smtp
MAIL_HOST=smtp.your-provider.com
MAIL_PORT=587
MAIL_USERNAME=your@email.com
MAIL_PASSWORD=your_smtp_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=support@your-domain.com
MAIL_FROM_NAME="Your Company Support"

Step 8: Run Laravel Setup Commands

cd /var/www/freescout
sudo -u www-data php8.2 artisan key:generate
sudo -u www-data php8.2 artisan migrate --force
sudo -u www-data php8.2 artisan freescout:after-app-update
sudo -u www-data php8.2 artisan storage:link

Common error: SQLSTATE[HY000] [2002] Connection refused → MySQL isn't running or DB credentials are wrong. Check with sudo systemctl status mysql.

Step 9: Configure NGINX

Create the server block:

sudo nano /etc/nginx/sites-available/freescout

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

    client_max_body_size 100M;

    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;
        fastcgi_read_timeout 300;
    }

    location ~ /\.ht {
        deny all;
    }

    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires max;
        log_not_found off;
    }
}

Enable it:

sudo ln -s /etc/nginx/sites-available/freescout /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Common error: nginx: [emerg] a duplicate default server → remove the default site: sudo rm /etc/nginx/sites-enabled/default

Step 10: SSL Certificate with Let's Encrypt

Make sure your domain DNS is pointing to your server IP before this step:

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

Certbot will automatically update your NGINX config with SSL settings and set up auto-renewal.

Test auto-renewal:

sudo certbot renew --dry-run

Step 11: Queue Workers (Critical — Don't Skip)

Queue workers process email fetching and sending. Without them, FreeScout won't send or receive emails.

sudo nano /etc/supervisor/conf.d/freescout.conf

[program:freescout-worker]
process_name=%(program_name)s_%(process_num)02d
command=php8.2 /var/www/freescout/artisan queue:work database --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
stopwaitsecs=3600

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start freescout-worker:*
sudo supervisorctl status

Step 12: Cron Job

sudo crontab -u www-data -e

Add this line:

* * * * * /usr/bin/php8.2 /var/www/freescout/artisan schedule:run >> /dev/null 2>&1

Step 13: Security Hardening

# Enable firewall
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

# Install fail2ban
sudo apt install -y fail2ban
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

# Secure PHP
sudo nano /etc/php/8.2/fpm/php.ini
# Set: expose_php = Off
# Set: display_errors = Off

sudo systemctl restart php8.2-fpm

Step 14: Email Deliverability (SPF, DKIM, DMARC)

This step is where most DIY installations fail. Without proper DNS records, your emails land in spam.

Add these DNS records in your domain registrar:

SPF record (TXT):

v=spf1 ip4:YOUR_SERVER_IP ~all

DKIM: Generate a DKIM key pair and add the public key as a TXT record. The private key goes on your server. This requires configuring your mail server (Postfix or using a service like SendGrid that handles DKIM for you).

DMARC (TXT):

v=DMARC1; p=quarantine; rua=mailto:dmarc@your-domain.com

Step 15: Complete the Web Installer

Visit https://your-domain.com and complete the FreeScout web installer. Create your admin account and configure your first mailbox.

Common Errors and Fixes

| Error | Cause | Fix | |---|---|---| | 502 Bad Gateway | PHP-FPM not running | sudo systemctl restart php8.2-fpm | | 500 Server Error | Wrong file permissions | sudo chown -R www-data:www-data /var/www/freescout | | Emails not sending | Queue worker not running | sudo supervisorctl status | | Emails going to spam | Missing SPF/DKIM | Add DNS records as above | | SSL not working | DNS not propagated | Wait 24-48h for DNS to propagate | | Blank page | APP_DEBUG=false hiding errors | Set APP_DEBUG=true temporarily |

How Long Did That Take?

If you followed every step without issues: about 4 hours. If you hit errors: plan for a full day.

This is 15 steps, 50+ commands, and DNS configuration that takes 24-48 hours to propagate. One misconfiguration in NGINX, one wrong database credential, or one missing PHP extension stops everything.

This is exactly why businesses hire us. For $100 we handle all 15 steps, configure your email deliverability, harden your server, and hand you a working FreeScout helpdesk with a 1-hour walkthrough call.

The choice is yours — but now you know exactly what's involved either way.

Resources

• Ubuntu 22.04 LTS — what's new in Jammy
• FreeScout GitHub — source code and releases
• NGINX on Ubuntu — official packages
• Certbot on Ubuntu 22.04 — SSL setup
• Ondrej PHP Repository — latest PHP packages