How to self-host FreeScout using Docker

FreeScout is a free, open-source help desk and shared inbox system that serves as a viable alternative to commercial help desk solutions. In this guide, you deploy FreeScout in a Dockerized environment. By containerizing FreeScout, you gain the benefits of easy deployment, simplified maintenance, and improved portability.

At the end of this guide, you will have FreeScout running on your server with persistent storage, ready to be accessed through your browser.

Prerequisites

Before you begin, make sure that you have the following in place:

1. Docker and Docker Compose Installed
   Ensure that Docker and Docker Compose are installed and running on your server.
   Learn more about installing Docker on Docker’s official documentation and Docker Compose on Docker Compose installation guide.
2. A Dedicated Directory for FreeScout Data
   Prepare directories on your host machine to map persistent storage for FreeScout’s data and logs.
3. Database Credentials
   You need to have credentials for a MySQL/MariaDB database. This guide uses a separate MariaDB container.
4. Optional: Domain Name and Reverse Proxy Setup
   If you plan to expose FreeScout to the internet, consider setting up a reverse proxy with HTTPS (for example, using Nginx or Traefik).

Main Content

Follow these steps to deploy FreeScout using Docker Compose:

1. Prepare Your Working Directory

Create a new directory on your host to hold your Docker Compose file and mapped volumes. For example:

mkdir -p ~/freescout/{data,db,logs}
cd ~/freescout

2. Create the Docker Compose File

Create a file named docker-compose.yml in your working directory. This file defines two services: one for FreeScout and one for the database. Copy and paste the example below:

version: '3.8'

services:
  freescout-db:
    image: tiredofit/mariadb:latest
    container_name: freescout-db
    volumes:
      - ./db:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: yourRootPassword
      MYSQL_USER: freescoutuser
      MYSQL_PASSWORD: yourDBPassword
      MYSQL_DATABASE: freescout
      TZ: UTC
    restart: always

  freescout:
    image: ghcr.io/tiredofit/docker-freescout:latest
    container_name: freescout
    depends_on:
      - freescout-db
    ports:
      - "8080:80"
    volumes:
      - ./data:/data
      - ./logs:/www/logs
    environment:
      ADMIN_EMAIL: admin@example.com
      ADMIN_PASS: yourAdminPassword
      SITE_URL: http://your-domain-or-IP:8080
      ENABLE_SSL_PROXY: "false"
      DB_HOST: freescout-db
      DB_NAME: freescout
      DB_USER: freescoutuser
      DB_PASS: yourDBPassword
      TZ: UTC
    restart: always

This configuration uses:

• The MariaDB container (from the tiredofit/mariadb repository) to host your database.
• The FreeScout container (from ghcr.io/tiredofit/docker-freescout) that automatically sets up the application upon first start.
• Mapped volumes for persisting data and logs.

Customize the environment variables to suit your configuration:

• Replace yourRootPassword, yourDBPassword, and yourAdminPassword with secure passwords.
• Set SITE_URL to the appropriate domain name or IP address with the mapped port.

3. Deploy FreeScout

Once your docker-compose.yml file is ready, deploy the containers using the following command:

docker-compose up -d

This command starts the containers in detached mode. The first boot may take several minutes as FreeScout initializes its database and configurations.

4. Verify the Installation

After the containers are running, open your web browser and navigate to the URL specified in SITE_URL (for example, http://your-domain-or-IP:8080). You should see the FreeScout login or installation page. Complete any initial setup through the web installer interface.

5. (Optional) Configure Reverse Proxy and HTTPS

If you want to secure your deployment with HTTPS:

• Set up a reverse proxy (using Nginx, Traefik, etc.) to forward traffic to port 8080.
• Obtain and install an SSL certificate (for instance, via Let’s Encrypt).
• Adjust the SITE_URL environment variable to use https://.

If you haven’t installed NGINX yet, do so with:

sudo apt update
sudo apt install nginx -y

Create a new NGINX configuration file for FreeScout:

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

Paste the following configuration (replace your-domain.com with your actual domain):

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    client_max_body_size 100M;  # Adjust if needed
}

Save the file (CTRL+X, then Y, then Enter).

Enable the Configuration

Run:

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

Now, NGINX should forward requests from your-domain.com to FreeScout running on port 8080.

Secure with Let’s Encrypt (SSL)

To enable HTTPS, install Certbot and generate an SSL certificate:

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

Follow the prompts and agree to the terms. Certbot will automatically modify your NGINX config to handle HTTPS.

Adjust FreeScout Configuration

Modify your docker-compose.yml file:

• Change SITE_URL to https://your-domain.com
• Set ENABLE_SSL_PROXY: "true"

Then restart FreeScout:

docker-compose down
docker-compose up -d

Automate SSL Renewal

Let’s Encrypt certificates expire every 90 days. Set up automatic renewal:

sudo crontab -e

Add this line at the bottom:

0 3 * * * certbot renew --quiet

This will renew the certificate automatically every day at 3 AM.

Next Steps and References

• Customize FreeScout: After installation, explore FreeScout’s settings to configure email, modules, and user roles to fit your support workflow.
• Maintenance and Updates: For routine maintenance, use Docker commands to view logs, update images, or access container shells for troubleshooting.
• Further Reading:
  • Visit the FreeScout GitHub repository for more detailed configuration options and environment variable explanations.

By following these steps, you deploy FreeScout in a Docker environment, enabling a flexible and maintainable help desk system that you control.

Happy hosting!