Blog

Update May 16th 2021: I’ve added a section about how to make sure SSL certificates are renewed automatically.

In this tutorial I will go through the steps of setting up the open source helpdesk software Freescout on a SpinupWP site. I’m using this setup in production on a 2GB DigitalOcean droplet that is also hosting a bunch of WordPress sites and it’s running just fine, no performance issues to report.

A 2GB droplet will set you back $10 USD per month. Combined with a $12 USD per month SpinupWP account you could be running a very competent support system with unlimited users starting at $22 USD per month with very little ongoing maintenance. If you’re already paying for these services chances are that the additional monthly cost for running Freescout will be zero.

It’s quite likely that you will also want to get at few of the Freescout premium modules but note that they are pay once perpetual licenses so even if you end up spending $100 USD on those, your monthly fee won’t rise.

I’ll be using a test domain that I have laying around called wundercogs.com and the resulting Freescout installation will get the address https://support.wundercogs.com, some of the config file edits and screenshots below will reflect that.

For full disclosure. I’m not affiliated with Freescout or DigitalOcean but I do work for Delicious Brains, the makers of SpinupWP. None of the links in this post is an affiliate link.

Step 1 – prerequisites

Before we get started there are a few things we need to get sorted.

We’re going to use a terminal shell to log on to the server using ssh. For security reasons SpinupWP only allows ssh logins using SSH keys (as opposed to using a password). If you’re not comfortable starting and using a command line shell this tutorial isn’t for you.

We need to have a domain name. In this guide I’ll be showing some screenshots from hover.com and their DNS editor. But most DNS editors work more or less the same and you should be able to figure out out to make the same changes on your preferred domain name provider.

Next we need to have an account with DigitalOcean because we’re using them to host our Freescout site. If you prefer to use another cloud server provider that’s fine, SpinupWP has plenty of documentation on how to provision servers from other providers.

We obviously also need a SpinupWP account because we’re going to use SpinupWP to do all the heavy lifting also known as server management.

Once we have both the DigitalOcean and SpinupWP accounts set up we’ll be following the SpinupWP docs to provision our first server. Their documentation is more than adequate so I’ll trust you’ll do just fine following that.

If you happen to already have a provisioned server in SpinupWP it’s OK to use that, Freescout is a fairly light weight application so it’s fine to host it toghether with other SpinupWP sites.

Once the server is setup in SpinupWP you can navigate to the server dashboard to find the IP number, make a note of it because we need it in the next step.

Step 2 – setting up a domain name

We’re going to configure a domain name to point to our newly created server. This step is important to do first because if we get this part right we’ll be able to get an SSL certificate without any additional hassle.

To do this we’ll jump over to the DNS editor of our domain name hosting provider. As I mentioned earlier I’m using hover.com for this and this is what the steps looks like with them:

Click Add record to add a host name to the domain:

Enter a host name. In this tutorial we want Freescout to be accessible on the address support.wundergcogs.com, so the host name we add is simply “support” and then we fill in the server IP address we got from step 1:

We finish by clicking Add record and we are all set.

Step 3 – Creating a site

To create a site we need to go back to the SpinupWP console and navigate to the server dashboard. Once there we hit the aptly named +Add site button to launch the site creation wizard

On the first step we’ll add our domain name and make sure the Enable HTTPS (SSL/TLS certificate) checkbox is checked and then click next

We’ll be asked if we’re ready to point our domain name to the server and since we’ve already taken care of that we’ll just click next and then I’ve updated the DNS

…and a few moments later we should get the confirmation:

On the next screen we’ll be asked what to install, we’re going to say Don’t Install Any Files because we’ll add the Freescout stuff later:

Freescout needs to have a MySQL database set up so we need to add this on the next screen. Because we selected not to install anything on the previous screen we need to manually select Create New:

Please note that SpinupWP automatically generates a database password on this screen. Be sure to copy it because you will need this password later.

On the next screen we set Linux user name for our application. This is the Linux user account that Freescout will use to write files etc and SpinupWP will suggest a name based on the domain name we selected earlier which we will just accept. SpinupWP also suggests that we use PHP 7.4 for this site which is a sensible choice since at the time of writing this, Freescout isn’t confirmed to work with PHP 8 (but that may change).

But we do want to uncheck the Enable full page cache checkbox since full page caching isn’t going to be needed and could quite frankly be a bit annoying for Freescout:

And that will take us to the last wizard step which is just to confirm that everything looks OK

…and since it looks just fine we’ll scroll all the way down and hit Add Site

SpinupWP will take a few minutes to set up the site and that’s that.

Step 4 – Creating a sudo user

For the next steps we need to create a sudo user in SpinupWP. This is the user we will use to login to the server and install Freescout.

To do this, we go to the server dashboard and click Sudo users:

Here we need to make up our own username, let’s go with freescout and make a note of the auto generated sudo password as we will need it later.

Important. You need to Add SSH Key to the newly created user because SpinupWP will not allow you to login using just the password. GitHub has a great guide for finding out your computers existing SSH key or help you generate a new one if needed. Make sure to upload your SSH public key to SpinupWP before saving the new user.

Step 5 – Installing Freescout

Ok, time for some keyboard work. First we’ll log on to the server using our newly created sudo user from the command line shell on your desktop / laptop:

ssh [email protected]

Once we’re on the server, navigate to the site folder for our site:

cd /sites/support.wundercogs.com/

And grab a copy of Freescout. Note that we’re running this command as the user support which is is the Linux user we created in step 4. When we issue this command we will have to enter the sudo password that we also created in step 4 above.

sudo -u support git clone https://github.com/freescout-helpdesk/freescout

Setting up a cronjob

Freescout runs a lot of internal jobs every minute and to make that work we need to set up a cronjob. We create a new files as root:

sudo nano /etc/cron.d/support

…and enter the following:

* * * * * support	php /sites/support.wundercogs.com/freescout/artisan schedule:run >> /dev/null 2>&1

Then type Ctrl+o to save and Ctrl+x to exit the editor.

Fixing server location

Next, since we’re installing custom software here the webserver configuration files that SpinupWP generated for us will need a little tweaking. We’ll edit the nginx config file for our site so that nginx goes looking for the Freescout files in the right place.

sudo nano /etc/nginx/sites-available/support.wundercogs.com/support.wundercogs.com

About 10-12 lines down there’s a line starting with root, we’re going to change that line so that it reads:

root /sites/support.wundercogs.com/freescout/public/;

Then type Ctrl+o to save and Ctrl+x to exit.

Fixing static files

Freescout does a little trickery to be able to serve inline images and attachments correctly and to make that work we need to add a few lines in another nginx config file:

sudo nano /etc/nginx/sites-available/support.wundercogs.com/server/static-files.conf

You will see a lot of blocks starting with a descriptive comment on one line and the the word location on the next. Each block separated with blank a line. We need to add a new block to handle attachments near the top of the file, before the block that handles images with the comment “Caches images….”:

# Manually added for Freescout
location ~* ^/storage/attachment/ {
        expires 1M;
        access_log off;
        try_files $uri $uri/ /index.php?$args;
}

# Caches images, icons, video, audio, HTC, etc.
...
...

Then type Ctrl+o to save and Ctrl+x to exit.

Making sure SSL certificate auto renews

When SpinupWP first creates the site it also sets up an SSL certificate which is needed for HTTPS to work. SpinupWP also takes care of renewing the SSL certificate on a regular basis. When this happens, the update script creates a file on disk and then asks the Letsencrypt service to verify that that file exists.

We’ve just modified the nginx config a bit so the place where nginx looks for file to server doesn’t match the place where the update script will put that file for Letsencrypt. We’ll fix this by creating a simple symlink:

sudo -u support ln -s /sites/support.wundercogs.com/files/.well-known /sites/support.wundercogs.com/freescout/public/

Install IMAP support

In most cases Freescout will be setup to use the IMAP protocol to fetch incoming emails. For this we need the PHP imap module installed:

sudo apt-get install -y php7.4-imap

That should be all the editing we need to do via ssh, to make the changes active, we just reload nginx:

sudo service nginx reload

Step 6 – Run the web installer

We’re going to take the easy route and do the rest of the installation using the Freescout web installer. The installer is located at https://support.wundercogs.com/install. Use your browser and navigate to the corresponding URL on your domain to get started:

Requirements should be OK:

Permissions should also be OK:

Make sure to select Use HTTPS Protocol:

On the database setup screen we enter the database credentials we generated in Step 4, we only need to fill in database name, username and password, the rest is pre-filled:

Select language and time zone on the next page:

…and as the last step we create the admin user:

And as as through magic we should get a happy success message telling us that everything went fine:

Note that we took care of setting uo the cron job in a previous step. We’re done.

Step 7 – Login

So now we have a fully working Freescout installation running on a DigitalOcean droplet. The rest of all setup needed is handled via the Freescout web interface and is well documented over at the Freescout GitHub pages, you probably want to get started with:

• Sending emails
• Fetching emails

Feedback?

Was this tutorial helpful? Did you miss anything or have you spotted any errors? Let me know in the comments below.