Skip to content
Klutch.sh Docs

Deploying a FreeScout App

Introduction

FreeScout is a powerful, open-source help desk and shared inbox solution designed for customer support teams. Built with PHP and Laravel, FreeScout provides a lightweight, self-hosted alternative to paid help desk platforms like Help Scout, offering essential features such as email management, conversation tracking, collision detection, saved replies, internal notes, and a clean, intuitive interface for managing customer support operations.

Deploying FreeScout on Klutch.sh gives you a managed, scalable infrastructure for your customer support operations with automatic HTTPS, persistent storage for attachments and conversations, seamless database integration, and a streamlined deployment workflow. Whether you’re a startup building your first support system or an enterprise scaling your customer service infrastructure, Klutch.sh handles the complexity of deployment, letting you focus on delivering excellent customer support.

This comprehensive guide walks you through deploying FreeScout on Klutch.sh using a Dockerfile, configuring persistent volumes for data storage, setting up environment variables for database connectivity, and implementing production-ready best practices for security, performance, and reliability.

Prerequisites

Before you begin, make sure you have:

  • A Klutch.sh account — sign up here if you haven’t already
  • A GitHub account with a repository for your FreeScout deployment
  • Basic familiarity with Docker, environment variables, and PHP applications
  • (Recommended) Access to a MySQL or MariaDB database for production deployments

Project Layout

A typical FreeScout deployment repository structure:

freescout-docker/
├─ Dockerfile
├─ docker-entrypoint.sh (optional custom startup script)
├─ .env.example (template for required environment variables)
└─ README.md

For a minimal deployment, you only need a Dockerfile. The other files are optional but recommended for documentation and custom configurations.

Getting Started: Installation and Setup

1. Prepare Your Repository

First, create a new GitHub repository for your FreeScout deployment or fork the official FreeScout repository:

    1. Create a new repository on GitHub or use an existing one

    2. Clone the repository to your local machine:

      Terminal window
      git clone https://github.com/your-username/freescout-deployment.git
      cd freescout-deployment

    3. Initialize the basic structure for your FreeScout deployment

2. Understanding FreeScout Requirements

FreeScout requires the following to run successfully:

  • Web Server: Apache or Nginx to serve the PHP application
  • PHP: Version 7.4 or higher with required extensions (mbstring, imap, xml, gd, etc.)
  • Database: MySQL 5.7+ or MariaDB 10.2+ for storing conversations, users, and configuration
  • Storage: Persistent storage for attachments, logs, and uploaded files
  • SMTP: Email server configuration for sending and receiving support emails

Deploying with a Dockerfile

Klutch.sh automatically detects a Dockerfile in your repository’s root directory and uses it to build your application. This approach is recommended as it provides reproducible builds, full control over dependencies, and consistency across environments.

Sample Dockerfile for FreeScout

Create a Dockerfile in your repository root with the following content:

FROM tiredofit/freescout:latest


# Set working directory
WORKDIR /www/html


# Optional: Copy custom modules or themes
# COPY ./custom-modules /www/html/Modules/
# COPY ./custom-themes /www/html/public/themes/


# Optional: Copy custom configuration
# COPY ./config/custom.php /www/html/config/


# The application runs on port 80 internally
EXPOSE 80


# The base image already has an entrypoint configured
# CMD is inherited from tiredofit/freescout

This Dockerfile uses the tiredofit/freescout image, which is a well-maintained, production-ready FreeScout image that includes:

  • Apache web server pre-configured for FreeScout
  • PHP with all required extensions
  • Automatic database migration on startup
  • Cron job support for scheduled tasks
  • Logging and monitoring capabilities

Alternative: Custom Dockerfile from Official Image

If you prefer to build from the official FreeScout repository, you can use this alternative Dockerfile:

FROM php:8.1-apache


# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    curl \
    libpng-dev \
    libonig-dev \
    libxml2-dev \
    libzip-dev \
    zip \
    unzip \
    libicu-dev \
    libc-client-dev \
    libkrb5-dev \
    && docker-php-ext-configure imap --with-kerberos --with-imap-ssl \
    && docker-php-ext-install pdo_mysql mbstring exif pcntl bcmath gd zip imap intl \
    && apt-get clean && rm -rf /var/lib/apt/lists/*


# Install Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer


# Set working directory
WORKDIR /var/www/html


# Clone FreeScout repository
RUN git clone https://github.com/freescout-helpdesk/freescout.git . \
    && composer install --no-dev --optimize-autoloader \
    && php artisan freescout:clear-cache \
    && chown -R www-data:www-data /var/www/html


# Apache configuration
RUN a2enmod rewrite && \
    sed -i 's!/var/www/html!/var/www/html/public!g' /etc/apache2/sites-available/000-default.conf && \
    sed -i 's!AllowOverride None!AllowOverride All!g' /etc/apache2/apache2.conf


# Expose port 80
EXPOSE 80


# Start Apache
CMD ["apache2-foreground"]

Step-by-Step Deployment on Klutch.sh

1. Push Your Repository to GitHub

    1. Commit your Dockerfile and any other files to your repository:

      Terminal window
      git add Dockerfile
      git commit -m "Add FreeScout Dockerfile for Klutch.sh deployment"
      git push origin main

2. Create a New App on Klutch.sh

    1. Log in to the Klutch.sh dashboard

    2. Create a new project or select an existing one

    3. Create a new app and configure it:

      • Repository: Select your FreeScout GitHub repository
      • Branch: Choose the branch to deploy (e.g., main or production)
      • Traffic Type: Select HTTP (FreeScout is a web application)
      • Internal Port: Set to 80 (this is the port FreeScout listens on inside the container)

3. Configure Persistent Volumes

FreeScout requires persistent storage for attachments, logs, and application data. Set up volumes in your app configuration:

    1. In your app settings, navigate to the Volumes section

    2. Add a new volume with the following configuration:

      • Mount Path: /www/html/storage (for tiredofit/freescout image) or /var/www/html/storage (for custom builds)
      • Size: Start with at least 5GB, scale up based on your expected attachment volume

    3. (Optional) Add another volume for logs:

      • Mount Path: /www/html/storage/logs
      • Size: 2GB

Important: When configuring volumes on Klutch.sh, you only need to specify the mount path and size. The platform handles volume naming and management automatically.

4. Set Environment Variables

Configure the required environment variables for FreeScout to connect to your database and send emails:

    1. In your app settings, navigate to the Environment Variables section

    2. Add the following required variables (mark sensitive values as secrets):

      Database Configuration:

      Terminal window
      DB_HOST=your-mysql-host
      DB_PORT=3306
      DB_DATABASE=freescout
      DB_USERNAME=freescout_user
      DB_PASSWORD=your-secure-password

      Application Configuration:

      Terminal window
      APP_URL=https://example-app.klutch.sh
      APP_KEY=base64:your-generated-app-key
      APP_DEBUG=false
      APP_ENV=production

      SMTP/Email Configuration:

      Terminal window
      MAIL_DRIVER=smtp
      MAIL_HOST=smtp.your-provider.com
      MAIL_PORT=587
      MAIL_USERNAME=your-email@domain.com
      MAIL_PASSWORD=your-smtp-password
      MAIL_ENCRYPTION=tls
      MAIL_FROM_ADDRESS=support@yourdomain.com
      MAIL_FROM_NAME=Your Support Team

    3. Generate APP_KEY: If you don’t have an APP_KEY, you can generate one by running the following command locally or in a temporary container:

      Terminal window
      docker run --rm tiredofit/freescout php artisan key:generate --show

Security Note: Always mark sensitive values like DB_PASSWORD, MAIL_PASSWORD, and APP_KEY as secrets in Klutch.sh to prevent them from appearing in logs or being exposed.

5. Configure Additional Settings

    1. Region: Choose a region closest to your users for optimal performance

    2. Compute: Select an instance size based on your expected load:

      • Small (1 CPU, 1GB RAM): Development or low-traffic support (up to 5 agents)
      • Medium (2 CPU, 2GB RAM): Production use (5-20 agents)
      • Large (4 CPU, 4GB RAM): High-traffic production (20+ agents)

    3. Instances: Start with 1 instance and scale horizontally as needed

6. Deploy Your Application

    1. Review your configuration settings

    2. Click “Create” to start the deployment

    3. Klutch.sh will:

      • Detect your Dockerfile automatically
      • Build your Docker image
      • Deploy the container with your configured volumes and environment variables
      • Route HTTP traffic to port 80 inside your container
      • Generate a public URL like example-app.klutch.sh

    4. Monitor the build and deployment progress in the dashboard

7. Initial FreeScout Setup

    1. Once deployment is complete, visit your app URL (e.g., https://example-app.klutch.sh)

    2. Complete the FreeScout installation wizard:

      • Set up your admin account
      • Configure your support email addresses
      • Add team members and set permissions
      • Customize your help desk settings

    3. Test email sending and receiving functionality

    4. Configure mailbox polling if using IMAP for incoming emails

Database Setup and Configuration

FreeScout requires a MySQL or MariaDB database. You have several options:

Option 1: Use a Managed Database Service

For production deployments, we recommend using a managed database service:

These services provide automatic backups, high availability, and simplified maintenance.

Option 2: Deploy MySQL on Klutch.sh

You can also deploy a MySQL database as a separate app on Klutch.sh:

  1. Create a new app with a MySQL Docker image
  2. Configure it with TCP traffic type (not HTTP)
  3. Set up persistent storage for the database
  4. Connect to it from your FreeScout app on port 8000

Note: For TCP traffic applications like databases, Klutch.sh makes them accessible on port 8000 externally, while traffic is routed to your configured internal port inside the container.

Database Initialization

FreeScout will automatically run database migrations on first startup. Ensure your database is created and accessible before deploying.

Email Configuration

FreeScout relies heavily on email for customer communication. Proper email configuration is critical:

SMTP Configuration

Configure outgoing email with your SMTP provider. Popular options include:

IMAP Configuration for Incoming Email

To receive customer emails, configure IMAP mailbox fetching:

Terminal window
FREESCOUT_MAIL_FETCH=true
FREESCOUT_IMAP_HOST=imap.your-provider.com
FREESCOUT_IMAP_PORT=993
FREESCOUT_IMAP_USERNAME=support@yourdomain.com
FREESCOUT_IMAP_PASSWORD=your-imap-password
FREESCOUT_IMAP_ENCRYPTION=ssl

Add these as environment variables in your Klutch.sh app configuration.

Customization and Extensions

Installing FreeScout Modules

FreeScout supports modules for extended functionality. To add modules:

  1. Create a modules directory in your repository

  2. Add module files to this directory

  3. Update your Dockerfile to copy modules:

    COPY ./modules /www/html/Modules/

  4. Rebuild and redeploy your app

Popular modules include:

Custom Themes

Customize FreeScout’s appearance:

  1. Create a themes directory in your repository

  2. Add your custom CSS and assets

  3. Update your Dockerfile:

    COPY ./themes /www/html/public/themes/

Persistent Storage Best Practices

FreeScout stores important data in the storage directory:

  • Attachments: Customer email attachments
  • Logs: Application and error logs
  • Cache: Session and application cache
  • Uploads: Profile pictures and other uploads

Mount the entire storage directory to a persistent volume:

  • Path: /www/html/storage (tiredofit/freescout) or /var/www/html/storage (custom builds)
  • Initial Size: 5GB minimum
  • Scaling: Monitor usage and increase as needed

Backup Strategy

    1. Regular Database Backups: Use your database provider’s backup features or run scheduled mysqldump commands

    2. Storage Volume Backups: Regularly back up your persistent volume to object storage

    3. Backup Frequency:

      • Database: Daily incremental, weekly full backups
      • Attachments: Daily backups with 30-day retention

Security Best Practices

Environment Variable Security

    1. Never commit secrets to your repository
    2. Use Klutch.sh’s secret management to store sensitive values
    3. Rotate passwords and API keys regularly
    4. Use separate credentials for development and production

Application Security

    1. Force HTTPS: Set APP_URL to use https://
    2. Disable Debug Mode: Set APP_DEBUG=false in production
    3. Strong Database Passwords: Use randomly generated passwords (minimum 32 characters)
    4. Restrict Admin Access: Use IP whitelisting or VPN for admin panels if possible
    5. Regular Updates: Keep FreeScout and dependencies up to date
    6. Enable Two-Factor Authentication: Configure 2FA for admin accounts

Network Security

Klutch.sh automatically provides:

  • TLS/SSL encryption for all HTTP traffic
  • DDoS protection
  • Automatic certificate management

Performance Optimization

Application-Level Optimization

    1. Enable Caching: Configure Redis or Memcached for session and cache storage

      Terminal window
      CACHE_DRIVER=redis
      SESSION_DRIVER=redis
      REDIS_HOST=your-redis-host
      REDIS_PORT=6379

    2. Queue Workers: For large-scale deployments, run background workers for email processing

    3. Database Optimization:

      • Create proper indexes on frequently queried columns
      • Regular database maintenance and optimization
      • Use read replicas for high-traffic scenarios

Scaling Strategies

    1. Vertical Scaling: Increase CPU and memory for your Klutch.sh instance
    2. Horizontal Scaling: Deploy multiple instances behind a load balancer (requires shared storage and session management)
    3. Database Scaling: Use connection pooling and read replicas

Monitoring and Maintenance

Application Monitoring

    1. Log Monitoring: Check application logs regularly for errors:

      • Location: /www/html/storage/logs/laravel.log

    2. Performance Metrics: Monitor:

      • Response times
      • Database query performance
      • Email sending/receiving rates
      • Disk usage on persistent volumes

    3. Health Checks: FreeScout typically responds with a 200 status on the homepage. Configure health check endpoints in Klutch.sh

Maintenance Tasks

    1. Regular Updates: Pull latest FreeScout releases and rebuild your image

    2. Database Maintenance: Run optimization queries monthly

    3. Log Rotation: Configure log rotation to prevent disk space issues

    4. Cache Clearing: Periodically clear application cache if experiencing issues

      Terminal window
      php artisan cache:clear
      php artisan config:clear
      php artisan view:clear

Troubleshooting Common Issues

Application Won’t Start

    1. Check Database Connection: Verify DB_HOST, DB_PORT, and credentials are correct
    2. Verify APP_KEY: Ensure APP_KEY is set and properly formatted
    3. Review Logs: Check application logs in /www/html/storage/logs/
    4. Port Configuration: Confirm internal port is set to 80

Email Not Sending

    1. SMTP Configuration: Verify SMTP credentials and settings
    2. Test SMTP Connection: Use telnet or online tools to test SMTP connectivity
    3. Check Firewall Rules: Ensure outbound SMTP ports (25, 587, 465) are not blocked
    4. Review Email Logs: Check FreeScout logs for email-related errors

Storage Issues

    1. Check Volume Mounts: Verify persistent volumes are properly mounted
    2. Disk Space: Monitor disk usage and increase volume size if needed
    3. Permissions: Ensure web server has write permissions to storage directories

Performance Issues

    1. Database Performance: Review slow query logs and add indexes
    2. Cache Configuration: Enable Redis or Memcached for better performance
    3. Resource Limits: Increase CPU/memory allocation if needed
    4. Email Queue: Implement queue workers to handle email processing asynchronously

Production Deployment Checklist

Before going live with FreeScout:

  • Database properly configured with automated backups
  • Persistent volumes configured and tested
  • All environment variables set (especially secrets)
  • SMTP and IMAP configured and tested
  • SSL/TLS certificate active (automatic with Klutch.sh)
  • APP_DEBUG=false in production
  • Admin account created with strong password
  • Two-factor authentication enabled
  • Regular backup schedule established
  • Monitoring and alerting configured
  • Custom domain configured (optional)
  • Email deliverability tested (inbox, not spam)
  • Load testing performed for expected traffic
  • Documentation updated with your specific configuration

Advanced Configuration

Custom Domain Setup

To use a custom domain with your FreeScout deployment:

    1. Configure your custom domain in the Klutch.sh dashboard (see Custom Domains Guide)

    2. Update your DNS records to point to your Klutch.sh app

    3. Update the APP_URL environment variable to match your custom domain:

      Terminal window
      APP_URL=https://support.yourdomain.com

    4. Klutch.sh automatically manages TLS certificates for your domain

Using Nixpacks for Customization

If you need to customize the build or start commands without using a Dockerfile, you can use Nixpacks environment variables:

  • START_COMMAND: Override the default start command
  • BUILD_COMMAND: Add custom build steps

For example, to customize the PHP version or add extensions:

Terminal window
NIXPACKS_PHP_VERSION=8.1
BUILD_COMMAND=composer install --no-dev --optimize-autoloader
START_COMMAND=apache2-foreground

However, for FreeScout, we strongly recommend using the Dockerfile approach for better reproducibility.

Resources and Further Reading

Conclusion

Deploying FreeScout on Klutch.sh provides a robust, scalable solution for managing customer support operations. With automatic Docker detection, persistent storage, seamless database integration, and built-in SSL/TLS, you can focus on delivering exceptional customer service while Klutch.sh handles the infrastructure complexity.

This guide covered everything from basic deployment to advanced configuration, security best practices, and troubleshooting. Whether you’re running a small support team or scaling to enterprise levels, FreeScout on Klutch.sh offers the flexibility and reliability you need.

For additional help or questions, refer to the resources above or reach out to the Klutch.sh support team.