Install FreeScout on Debian — Complete Guide (2025)

Debian is lighter weight than Ubuntu and preferred by many sysadmins. This guide covers installing FreeScout on Debian 12 (latest stable). Installation is nearly identical to Ubuntu — mainly different package names.

Why Debian?

• ✅ Lightweight (uses fewer resources than Ubuntu)
• ✅ Stable (3-year support cycle)
• ✅ Predictable (slower release cycle = less surprises)
• ✅ Server-focused (fewer desktop bloat)

Debian 12 is the current stable release (released June 2023, support until 2026).

Prerequisites

• Debian 12 VPS (64-bit, fresh install)
• 1GB RAM minimum, 2GB recommended
• SSH access
• Domain name (for SSL)

Step 1: Initial Server Setup

SSH into your Debian server:

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

Create non-root user:

adduser freescout
usermod -aG sudo freescout
su - freescout

Step 2: Install PHP 8.2

Debian's default repos have PHP 8.2, no PPA needed (unlike Ubuntu):

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-cli

Verify:

php8.2 --version

Step 3: Install MySQL

sudo apt install -y mysql-server
sudo mysql_secure_installation

Answer prompts:

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

Step 4: Create Database

sudo mysql -u root -p

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

Step 5: Install NGINX

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

Step 6: Install Composer

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

Step 7: 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
cd /var/www/freescout

Install dependencies:

sudo -u www-data composer install --no-dev --optimize-autoloader

This takes 3–5 minutes.

Step 8: Configure Environment

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

Update these values:

APP_URL=https://your-domain.com
APP_KEY=   # Leave blank, auto-generated
DB_DATABASE=freescout
DB_USERNAME=freescout
DB_PASSWORD=strong_password_here
MAIL_DRIVER=smtp
MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=your-sendgrid-api-key
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=support@your-domain.com
MAIL_FROM_NAME="Your Support"

Step 9: Generate Keys & Migrate

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

Step 10: Configure NGINX

Create /etc/nginx/sites-available/freescout:

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

Paste:

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

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

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

Enable:

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

Step 11: Point Domain to Debian Server

1. Go to your domain registrar
2. Update A record to your server's IP
3. Wait 15–30 minutes for DNS propagation

Step 12: Install SSL

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

Certbot will auto-update your NGINX config and set up auto-renewal.

Step 13: Queue Workers

Create /etc/supervisor/conf.d/freescout.conf:

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

Paste:

[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

Start:

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

Step 14: Cron Job

sudo crontab -u www-data -e

Add:

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

Debian vs Ubuntu

Both work great for FreeScout. Differences:

| | Debian | Ubuntu | |---|---|---| | Size | Lighter | Heavier | | Updates | Quarterly | Monthly | | Stability | Very stable | Stable | | Support | 3 years | 5 years | | Packages | Recent but stable | Newer, may change more | | Best for | Servers, sysadmins | Beginners, servers |

For FreeScout: Both are identical. Choose based on preference.

Debian-Specific Tips

Tip 1: Use apt instead of apt-get

Debian's newer alias is apt:

sudo apt install package
sudo apt update
sudo apt upgrade

(Both work, but apt is preferred)

Tip 2: Check Debian Versions

cat /etc/debian_version
lsb_release -a

Tip 3: Long-Term Support

Debian 12 is supported until June 2026. Plan major changes before then.

Troubleshooting

| Issue | Cause | Fix | |---|---|---| | "PHP module not found" | Module not installed | Check module list: php8.2 -m | | "NGINX can't find fastcgi socket" | Wrong PHP version path | Verify FPM socket: ls /var/run/php/ | | "MySQL connection refused" | MySQL not started | sudo systemctl restart mysql | | "Composer out of memory" | 1GB RAM insufficient | Add swap: sudo fallocate -l 2G /swapfile |

Firewall (UFW)

Secure your Debian server:

sudo apt install -y ufw
sudo ufw enable
sudo ufw allow 22/tcp   # SSH
sudo ufw allow 80/tcp   # HTTP
sudo ufw allow 443/tcp  # HTTPS
sudo ufw status

Performance Tweaks (Optional)

Increase PHP memory limit:

sudo nano /etc/php/8.2/fpm/php.ini

Change:

memory_limit = 256M
max_execution_time = 300
upload_max_filesize = 100M

Restart PHP:

sudo systemctl restart php8.2-fpm

Summary

Debian 12 is a rock-solid foundation for FreeScout. The installation is nearly identical to Ubuntu — just a few package name differences. You get a lighter-weight, stable, predictable system.

Install time: 3–4 hours (same as Ubuntu).

Debian 12 + FreeScout = production-ready helpdesk.

Resources

• Debian Documentation — official Debian guide
• FreeScout GitHub — source code and releases
• Certbot for Debian — SSL setup
• NGINX on Debian — installation guide