This is an in-depth walkthrough to show you how to install a Discourse forum on a subdomain (e.g. forum.example.com). It’s the first in-depth tutorial that I’ve written, and a lengthy one at that, so I am likely to revisit this and try and edit it to be more user friendly in the future. If any of it doesn’t make sense, just let me know and I’ll do my best to help.
Discourse is the forum software that Webflow uses for this very forum, in case you were wondering. It seems to be extremely popular amongst modern services and companies, so it’s worth getting on board! PHP boards are a thing of the past.
This walkthrough will use two main services: DigitalOcean and Mailgun.
I’ll start this off by saying that I am NOT an expert at this (virtual servers, Ubuntu etc). Before getting this forum up and running, I had never touched Ubuntu / cloud servers before! It is highly likely that if you have a question outside of the scope of this walkthrough, I will not be able to help you. I welcome anyone wishing to comment/give their thoughts and input. For anyone with more bespoke questions that may be off-topic here, feel free to reach out to me via www.jollygoodweb.com.
The method I detail below may not be the best way, however it’s how I got it to work after a LOT of trial and error. I am more than happy to edit this guide if anyone can suggest more efficient ways of going about things. It’s also worth noting that you don’t have to use this in conjunction with a Webflow project. The example domain I use (britishfishing.co.uk) is not currently connected to anything other than the Discourse forum.
Don’t bother signing up to the forum that I create - it will likely get deleted / overwritten soon. Purely for test purposes at the moment.
There will be a number of links at the end of this tutorial that contain a ton of useful information that I referred to continuously throughout the process of getting a forum up and running. I have taken a lot of my information from these links, but have also added my own observations to them. You may find some of these links useful - I encourage you to read them to get a full understanding.
Let’s dive in…
DigitalOcean offer a $100 account credit to new joiners. Full Disclosure: this is a referral link. It’s very much appreciated if you sign up to DigitalOcean using this link, but not necessary if you don’t want to. I don’t know of any other way for you to receive $100 credit, though.
If you already have a DigitalOcean account, simply sign in.
Once you are signed in, go to this link. Click the “Create Discourse Droplet” to download the Discourse App directly into a new DigitalOcean Droplet.
You will be greeted with the “Create Droplets” screen.
To create a small forum, you don’t need a massive plan! On the “Choose A Plan” section, select the $10/month option (2GB / 1 CPU / 50GB SSD / 2TB Transfer) as recommended here. I did try the $5/month option but ran into a number of issues, including not being able to access the forum at all. For the sake of $5/month, this was not something I felt inclined to spend time troubleshooting - upgrading to the $10 a month option instantly solved my issues. If you want to play it really safe, or you plan for your forum to grow into a large community, then you can of course select a larger plan.
Run through the rest of the options. I am in the UK, so for Datacenter Region I selected London. I also selected Monitoring from the Additional Options section. Ensure you change the hostname to a more memorable one (I am super OCD about that kind of thing!) - I used forum.britishfishing.co.uk as it then matches what I intend to use it for. Additionally, I chose to enable backups.
Finally, click “Create Droplet”.
In your DNS provider where the domain you want to use is registered, create an A-Record that points to the IP of the Droplet. You can find this IP in the email that DigitalOcean will have sent you upon Droplet creation, or from the Droplet overview in DigitalOcean.
A number of services are recommended in this guide, which I highly recommend you read as it goes into more detail than I will in this walkthrough. I chose to use Mailgun, so that is what I will focus on.
Sign up for a Mailgun account. Once signed in, click “Domains” from the left-hand panel. Then, in the top right of the screen, click the button titled “Add New Domain”
Add your domain. As suggested in the previously linked guide, I used “mg” as the subdomain. So, the full domain that I entered here was mg.britishfishing.co.uk - substitute “britishfishing.co.uk” for your own domain. Note that I selected EU as my region, so if you select US you may be greeted with different settings etc further down the line - adapt as necessary.
You will then be greeted with an overview screen. You will need to follow the instructions it gives, which I will try and list sensibly below.
- Open your domain from within your DNS provider. For this example, I use GoDaddy.
- Add the DNS records that Mailgun lists and provides prompts for. Below is a screenshot of exactly how it looks from within my GoDaddy account, with the exception of the domain key (I have no idea if this could be used maliciously, so I have blocked it out from the screenshot). NOTE: Where Mailgun tells me to enter “mg.britishfishing.co.uk”, for example, I actually only need to enter “mg” into the GoDaddy settings. Likewise with “email.mg” etc.
I noted in this guide that you do not in fact need to set the MX records that Mailgun shows. I have no idea of the potential ramifications of this - however I have not set MX records and it’s working fine for me. EDIT 1 month after writing: this later led to issues with mail deliverability to certain email providers. Because of the fact that I was setting DNS records from a registrar other than DigitalOcean, the issue noted in the previously linked tutorial regarding subdomains was not a factor. I simply set MX records for “mg” (being the subdomain that I was setting MailGun up on) using the values given to me by Mailgun - see screenshot a couple of paragraphs down.
Also worth noting is that the Values for your TXT records need to be enclosed in quotation marks “”. It may also say something different in the Mailgun domain settings where it says “mailo” for me - it could say “smtp”, for example. Copy whatever Mailgun gives you exactly, but don’t forget not to include the domain itself in your DNS records (instead of “mg.example.com” enter “mg”).
Once you have entered the correct values into your DNS provider, go back to Mailgun and click “Check DNS Records Now” in the top right corner. Note that it can take several hours for changes to take effect! Go an have a coffee or five, and just wait patiently… Or, you can do what I did, and sit there clicking the button over and over again
If all goes, well, you will be greeted with the following screen in Mailgun:
If it’s not working for you after several hours, I advise that you go through your DNS settings checking for typos, starting from scratch if necessary (I had to, several times!). Alternatively, you can refer to this troubleshooting guide, or start from scratch using one of the many guides at the bottom of this post. You might breeze it first time, but setting up the mail server correctly took me several attempts and a lot of time - mostly because I was referring to several outdated guides, so hopefully you don’t have that issue.
Back to DigitalOcean. Select your droplet which, if you followed the naming instructions in Section 2, will be displayed as “forum.example.com”.
Click on it, then on the left-hand side click “Access”. Then, click “Launch Console”.
You will be greeted with this:
Enter the following:
Password:this was emailed to you by DigitalOcean when you first created the Droplet. Simply copy and paste it into the console. It’s worth noting that it does not look like you have entered anything - Simply copy & paste, and press enter. In the screenshot below, it looks like there is no password but I have in fact entered it and pressed enter.
You will then need to change your root password. MAKE SURE YOU REMEMBER IT.
- re-enter your current root password (the one that DigitalOcean emailed you).
- enter a MEMORABLE password of your own choosing.
Your password will be changed, and you will then be greeted with the following screen:
Press Enter to begin, and follow the steps it takes you through:
Hostname for your Discourse:Enter the domain that you set up in your DNS provider. For me, this is forum.britishfishing.co.uk (because I created an A-Record for “forum” earlier on in Section 3).
It will then check for the correct DNS record. If it fails at this step, go back to Section 3 and ensure you have created the appropriate A-Record for your subdomain (in this case, the subdomain is “forum”).
Email address for admin account(s):Enter your own email address that you would like to be the Discourse Admin account. Note that you must have access to the inbox for this address as a verification link will be sent! For me, this is email@example.com (my agency email address).
SMTP server address:Go to your Mailgun page, to the domain that you created in Section 4, and navigate to the “SMTP Credentials” tab. Remember that I set up an EU domain in Mailgun, so the settings you need to use may differ. Ensure you use the correct settings shown to you on your Mailgun page. For me, this is smtp.eu.mailgun.org.
SMTP port:In several of the guides linked throughout this walkthrough, they nearly all recommend Port 587. So this is what we will use.
SMTP user name:This is shown to you on your Mailgun SMTP Credentials page. For me, it is firstname.lastname@example.org.
SMTP password:Again on your Credentials page, in the top right click “Reset Password”. Mailgun will then generate a new password for the SMTP Username that you have just entered. It will only show you this password once, so it’s up to you if you make a note of it or simply copy and paste it in. It will appear as a prompt in the top right of your screen, and is a long alphanumeric string. For obvious reasons, I’m not going to share mine with you. Copy and paste it into the console and press enter.
Skip the Let’s Encrypt warning option unless you wish to use this.
If you’ve followed this Section, you will then end up with the following (obviously with your own domain & SMTP settings etc instead of mine):
CHECK FOR TYPOS!!! Then check it again for typos. Press Enter, and Discourse will begin installing to your Droplet. This can take some time (10+ minutes) so just leave it - even if you think it’s done, it probably isn’t… until it displays the following:
So, you’ve successfully set up your mail server (you think), and the Discourse software has installed to your Droplet. Huzzah!
In your browser, go to your domain. If Discourse has successfully installed to your Droplet, you will see the following:
Click “Register”. You’ll notice that the email field is pre-populated with the email address you entered during your Discourse installation.
Enter the account details that you wish to use, and click “Register”.
This is the Litmus Test! If you have not set up your mail server correctly, you will not receive an email. I cover some basic troubleshooting below. If it doesn’t work after the troubleshooting, the likelihood is you’ve made a small error somewhere and it may prove easier to simply start over. This happened to me several times!
If you receive the verification email, then congratulations! You have successfully set up both your mail server and the Discourse software. I am not going to cover the Discourse forum setup itself - they guide you through the process and it is quite self-explanatory. You can now skip to the end of this tutorial and A) tell me that I rambled on for too long or B) do some further reading via some of the links that I’ll provide in the very final section. Enjoy!
So, Section 6 didn’t work for you? Ok, there’s two things that I did when I ran into trouble:
Check for “bouncing” emails
Your email could simply be bouncing. From your Mailgun dashboard, click the domain you set up, and it will show you a log of your emails so far (at the time of writing, I have sent a single successful email - this is my verification email). If it is showing that the email is bounced, I am afraid you will need to Google solutions for this / ask for help from other forum users in the comments below. Or, you can take a read of this article.
Troubleshoot the mail server
Here’s a detailed guide on how to troubleshoot your mail server, provided by Discourse.
If all else fails, you may simply have to scrap it and start again, paying particular attention to typos. It took me about 3 attempts (with zero prior experience).
In learning how to set up a Discourse forum, I referred to a huge number of guides. I didn’t find a guide that completely worked for me - instead, I had to use bits and pieces from different guides in order to come up with the walkthrough that you have so patiently read! However, these guides have all helped me in a small way so it’s only fair that I link to them. You may find it useful to read them, you may not. Your choice…
- discourse/INSTALL-cloud.md at master · discourse/discourse · GitHub
- How to Setup Discourse on DigitalOcean – Sam Solomon
- GitHub - discourse/discourse_docker: A Docker image for Discourse
MAILGUN SETUP / TROUBLESHOOTING
- discourse/INSTALL-email.md at master · discourse/discourse · GitHub
- Mailgun + DigitalOcean DNS Settings
- Setting up Mailgun on Digital Ocean | by Andrew Forward | Medium
- Failed to verify domain on Mailgun | DigitalOcean
- Handling bouncing e-mails - admins - Discourse Meta
- Troubleshooting email on a new Discourse install - sysadmin - Discourse Meta
- How do I setup SMTP on a Discourse Droplet ? | DigitalOcean
USEFUL CONSOLE COMMANDS
More for my own use than anything…but someone may find these commands useful.
cd /var/discourse- changes to the discourse directory
cd /root- changes to the root directory
./discourse-setup- re-input SMTP settings etc (useful if you screw up inputting your mail server settings etc)
df -h- check remaining disk space on droplet
free -m- check available memory on your Droplet
./launcher rebuild app- rebuilds the app (use cd /var/discourse first)
If you have to log back in to your Droplet for any reason, username is “root”, password is whatever you set it to initially. Reset from the DigitalOcean Droplet dashboard if needed.
If you’ve gotten this far, congratulations! I sincerely hope you found this useful - it took me some number of hours to write. It’ll be useful for me to refer back to in future, but if it helps just one other person then it is even more worth it.
Let me know how you get on setting up your Discourse forum, and as always feel free to reach out to me via:
Thanks for reading!