How to self-host FreeScout using Docker

This guide will walk you through setting up FreeScout, an open source alternative to HelpScout or Zendesk, on your Ubuntu 24.04 server using Docker, making it accessible at your custom domain with HTTPS.

Click here to view prerequisites for installing FreeScout.

Hardware Requirements

  • A VPS or dedicated server with at least:
    • 1 CPU core (2+ recommended)
    • 2GB RAM minimum (4GB+ recommended)
    • 20GB storage space (SSD preferred)

Software Requirements

  • Ubuntu 24.04 LTS (fresh installation recommended)
  • Root or sudo access to the server
  • A registered domain name (in your case freescout.codecope.org)
  • DNS configured to point your domain to your server’s IP address

Network Requirements

  • Ports 80 and 443 must be open in your server’s firewall
  • Public IP address (static IP recommended)
  • Unrestricted outbound internet access (for software updates and Let’s Encrypt)

Domain Setup

  • An A record for freescout.codecope.org pointing to your server’s IP address
  • DNS propagation completed (can be verified using tools like whatsmydns.net)

Skills/Knowledge

  • Basic Linux command-line familiarity
  • Basic understanding of web servers and DNS
  • Ability to connect to your server via SSH

Before Installation

  1. Ensure your server is up-to-date: sudo apt update && sudo apt upgrade -y
  2. Verify your domain is correctly pointing to your server: ping freescout.codecope.org
  3. Make sure you have a valid email address to use for FreeScout admin account and Let’s Encrypt certificates

Once you have all these prerequisites in place, you can proceed with the installation guide to set up FreeScout on your Ubuntu 24.04 server.

1. Connect to Your Server

Bash
ssh username@your-server-ip

2. Update and Install Dependencies

Bash
sudo apt update
sudo apt upgrade -y
sudo apt install -y docker.io docker-compose curl git

3. Start and Enable Docker

Bash
sudo systemctl start docker
sudo systemctl enable docker

4. Add Your User to the Docker Group (to run Docker without sudo)

Bash
sudo usermod -aG docker $USER

Log out and log back in for this change to take effect:

Bash
exit

Then reconnect to your server.

5. Create a Directory for FreeScout

Bash
mkdir -p ~/freescout
cd ~/freescout

6. Create a docker-compose.yml File

Bash
nano docker-compose.yml

Paste the following configuration:

Note: In this guide, we will use freescout.codecope.org as an example domain. You want to replace it with your own domain.

Bash
version: '3'

services:
  db:
    image: mysql:8.0
    container_name: freescout-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: YourStrongRootPassword
      MYSQL_DATABASE: freescout
      MYSQL_USER: freescout
      MYSQL_PASSWORD: YourStrongPassword
    volumes:
      - db_data:/var/lib/mysql

  freescout:
    image: tiredofit/freescout:latest
    container_name: freescout
    restart: unless-stopped
    depends_on:
      - db
    ports:
      - "8080:80"
      - "8443:443"
    environment:
      - DB_HOST=db
      - DB_NAME=freescout
      - DB_USER=freescout
      - DB_PASS=YourStrongPassword
      - SETUP_TYPE=AUTO
      - ADMIN_EMAIL=your-email@example.com
      - ADMIN_FIRST_NAME=Admin
      - ADMIN_LAST_NAME=User
      - ADMIN_PASS=YourAdminPassword
      - SITE_URL=https://freescout.codecope.org # Replace freescout.codecope.org with your own domain.
      - TIMEZONE=UTC
    volumes:
      - freescout_data:/www/html

volumes:
  db_data:
  freescout_data:

Save and exit (Ctrl+X, Y, Enter).

Important: Replace the domain (SITE_URL) and placeholder for passwords and email with your own values!

7. Start the Docker Containers

Bash
docker-compose up -d

This will download the images and start the containers in the background.

8. Set Up DNS for Your Domain

In your domain registrar or DNS provider, create an A record pointing freescout.codecope.org to your server’s IP address.

9. Install and Configure Nginx as a Reverse Proxy

Bash
sudo apt install -y nginx certbot python3-certbot-nginx

Create a Nginx configuration file:

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

Paste the following configuration:

Note: Replace freescout.codecope.org with your own domain.

Bash
server {
    listen 80;
    server_name freescout.codecope.org; # Replace freescount.codecope.org with your own domain.
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 600s;
        proxy_connect_timeout 600s;
        proxy_send_timeout 600s;
        client_max_body_size 100M;
    }
}

Save and exit.

Create a symbolic link to enable the site:

Bash
sudo ln -s /etc/nginx/sites-available/freescout /etc/nginx/sites-enabled/

Test the Nginx configuration:

Bash
sudo nginx -t

If the test is successful, restart Nginx:

Bash
sudo systemctl restart nginx

10. Set Up SSL with Let’s Encrypt

Note: Replace freescout.codecope.org with your own domain.

Bash
sudo certbot --nginx -d freescout.codecope.org

Follow the prompts to complete the SSL setup.

11. Verify Your FreeScout Installation

Open your browser and navigate to:

Bash
https://freescout.codecope.org

You should see your FreeScout installation with the admin credentials you specified in the docker-compose.yml file.

12. Configure Automatic Container Updates (Optional)

If you want to keep FreeScout updated automatically, install Watchtower:

Bash
docker run -d \
  --name watchtower \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --cleanup --interval 86400

This will check for updates once per day and update your containers if new versions are available.

Troubleshooting

Check Container Logs

If you encounter issues, check the container logs:

Bash
docker logs freescout
docker logs freescout-db

Container Status

Check if containers are running:

Bash
docker ps

Restart Containers

If needed, restart the containers:

Bash
cd ~/freescout
docker-compose restart

That’s it! You now have FreeScout running on your Ubuntu 24.04 server with Docker, accessible at https://freescout.codecope.org.

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *