Upgrading Ghost Blog from 5.x via Docker & adding Giscus comments

Upgrading Ghost Blog from 5.x via Docker & adding Giscus comments

This post will go through how to update your ghost blog to the latest minor version as well as a new mail setup and getting rid of Disqus in favour of Giscus. A few modifications were made to get this working. Firstly you need to clone the below repo which contains the Docker file, the config and the theme.

GitHub - daniaalnadir/GhostBlogTemplate
Contribute to daniaalnadir/GhostBlogTemplate development by creating an account on GitHub.

The Dockerfile

A few changes were made such as not using the alpine base image anymore. This is because the azure-ghost-storage project has some dependencies that required python 2. This conflicts which the alpine image because an alpine image built to be small and secure and only contain the bare essentials to run the application. This meant that support for python 2 was dropped from the alpine image. The solution to this is to use the full fledged image and this is typically based on a full linux distribution and contains everything we need. See here for more information.

Mail and Mailgun

I also made some changes to the email provider that being Mailgun. This is because Ghost only supports Mailgun to send out bulk newsletter emails. Registering for a Mailgun account is free with a quota of 100 emails a day. Make sure to register your own domain, mine was mg.daniaal.com and then you will need to verify your domain by adding CNAME, TXT and MX DNS records.

It is very important that you setup the MX records in the receiving section. Some email providers will actually check that the sending email domain is legit and they will do this by checking if there are MX records present on the domain that match the domain in the from email address. I found this out the hard way!! Below is an screenshot of what the Mailgun DNS record UI looks like.

You will then need to fill out the config.development.json with your Mailgun authentication details. Whilst I was filling out this config, there is a property called port and there were multiple examples of port 465 and 587 being used. From what I gathered, port 587 is the port to use because it is more secure and using port 465 has been deprecated.

In Mailgun you can generate an API key. You will then need to head over to the Ghost admin portal and enter your API key into the "Mailgun settings" section. When you publish a post you will have an option to send a email.

Deployment

To prevent building the image locally and then deploying to docker hub I have instead decided to use Github Actions. In the ghost blog template I have included a file in the .github folder. There are some instruction in there that you will need to follow and they are very straight forward. Once you have this setup, you should be able to commit locally and that's it, your app should get deployed to your app service.

Giscus Comments

Since I created my blog, I have always used Disqus so that users could leave comments. The issue with this is that user had to have a Disqus account so would require a signup which could prevent a user leaving a comment. They also host ads in the comments section which isn't something i'm particularly onboard with. For this reason I have removed Disqus and now use Giscus. The comments are hosted on Github and you will need a Github account to comment. The advantages of this are that most developers will have a Github account and the comments link to a public repo which in this case is the GhostBlogTemplate.

Navigate to https://giscus.app/ and follow the below steps. Then enter the name of your repository to verify if your repository follows the criteria.

Then select the checkboxes that apply to you. For the "Page to Discussions" mapping I selected Discussion title contains page <title>. I also opted for the comments box to appear at the top. Then you can copy the script and add it to the post.hbs file and then build and run your image. Then you should see a Github comments section.

Useful Info

SMPT Port 465 and Port 587: What’s the Difference?
Learn about the differences between port 587 vs port 465, why there’s so much confusion around the ports, and how to best use them.

Container Issues

When I was deploying to Azure I was receiving an error Container daniaalghostblog_0_e0272dfb didn't respond to HTTP pings on port: 2368, failing site start. See container logs for debugging.

It turned out that when building the container on MacOS, I needed to specify the platform that I was building for which was linux. See below for an example. Once I built and pushed my image the deployment worked on the Azure app service.

docker build --platform linux/amd64 -t name/ghost-blog:{version} .

To mitigate this the next steps would be to build the image on a linux agent via Github actions or Azure Devops.

Running Image Locally Issues

When I was trying to run my image locally I was getting an error about Ghost not being able to connect to my database. It turned out that my public IP address had changed and this IP address was not in the whitelist of the database firewall. Once I added this, everything worked.