Utilizing SendGrid SMTP relay to setup a  Discourse server

Utilizing SendGrid SMTP relay to setup a Discourse server

Last week I started reading a new book titled "Starship For Sale" by M.R. Forbes. I thought it would be a fun project to build a fan site around the book series. While I was designing the site I wanted to add a forum so that other fans of the book series could talk and maybe brainstorm side stories or anything else for that matter... I decided on using Discourse for my forum. However, I did not want to pay $100 a month for a small side project like this. So, I launched a Discourse droplet on Digital Ocean at $12 a month. Initially I tried the $7 tier with 1GB of RAM but not only was the forum loading impossibly slow but notification emails were not being sent out. Once I bumped it to the Discourse recommended 2GB minimum everything started running much more smoothly.

The Discourse setup requires that a SMTP server be setup. Discourse lists quite a few options but in the end I decided to go with SendGrid as they had a forever free option with a decent amount of usage to get the site up and running.

There is plenty of information out there on getting the Digital Ocean side of things setup but I could not find anything that laid out how to implement SendGrid as a SMTP solution. Hence this will be the direction I take this "how to" article.

Initial Setup

Once I had launched the Digital Ocean droplet I tried to connect via SSH but I kept getting a port refusal error message. It was getting late so I decided to tackle that in the morning. When I woke up I tried the setup again (by connecting via SSH to the droplet) but the port refusal error was gone. I suspect that it was just taking time for Digital Ocean to get everything squared away on their end.

I initially tried getting my SMTP server up and running using AWS Workmail but it was not working (no pun intended). That is how I came across SendGrid - looking for solutions other than AWS that was not going to drive up the cost of this fun side project any further. Since I had already run the initial setup script I had to edit the app.yml file manually. (FYI - to find the app.yml file ssh into your droplet then cd /var/discourse/containers that is where you will find the app.yml file. I have nano installed so I was able to edit the file by entering nano app.yml from the var/discourse/containers directory).

Here is the info you need to fill out (you may need to scroll down a bit to see it):

  DISCOURSE_SMTP_ADDRESS: smtp.sendgrid.net
  DISCOURSE_SMTP_PASSWORD: "<your api key inside of an opening and closing double quote>"

To create your DISCOURSE_SMTP_PASSWORD you can find it under Settings > API Keys (when logged in to your SendGrid account). Select "Create API Key", give it a name, and then allow "Full Access".

If you input the above information during the initial setup script run than this step will not be necessary but if you were like me and had to update the information or you found an error than, according to the docs, you will need to rebuild the container by running the following:

cd /var/discourse
./launcher destroy app
./launcher start app

This is the simplest way to rebuild your container with the updated SMTP information. You could also run:

cd /var/discourse/
./launcher rebuild app

However, this will take much longer...

Your Discourse Hostname

I used Cloudflare to register the domain name for the fan site. Their prices are the most affordable and I have used their services for years so I trust them. I built the landing and About pages for the fan site with NextJS and deployed via Vercel. When you connect your app to a domain with Vercel there are comprehensive instructions on how to do so. So, setup was a breeze (and a little out of the scope of this article so I will not go into further detail). Next I pointed an A record with the name community to the Digital Ocean droplet's IP.


Do note that I had to set proxy status to DNS only so that the domain would work with Vercel.

One thing to note: when the initial setup script was running somehow the placeholder passcode had not been removed. Double check that that error did not happen to you. If it did go ahead and delete it but be sure you have (" ") around the correct "DISCOURSE_SMTP_PASSWORD"


FYI - you will need to rebuild the container if you change ANY SMTP information including this odd password

Now my new Discord server is up and running at community.starshipfor.sale! I hope you found this helpful and as always if you run into any problems feel free to reach out to me by clicking the suitcase icon in the footer of my portfolio site.