How to troubleshoot Ghost installations & upgrades on Azure

I recently upgraded a Ghost site from a quite old version to a new one and like we often see it in a deployment... it did not went as expected. Let me tell you what I did to solve the problem so that it may save you some time if you encounter hat kind of problems with your Ghost deployment on Azure.

All I see is a blank window

Right after my deployment, I tried to hit the website to see if everything was OK... No error in the browser was shown but only a blank white page without any information.

Blank site in error

This is not what I expected, but how can you get more information when this happen on a web application where you cannot remote desktop on the machine behind?

Say hello to the Kudu console!

The Kudu console is a very helpful tool to get into the core of your web app, it enable you to perform tons of actions behind the scene.

In this example, the site is named ghost-azure5938, which resolve to a url like: ghost-azure5938.azurewebsites.net. To access the Kudu console, you need to insert scm in the url like this:
ghost-azure5938.scm.azurewebsites.net

Kudu home

I cannot emphasize enough that killing a process/deleting files can cause strange behaviors and may lead to data loss. Make sure you have a backup of your files before going further.

View Ghost error logs

PowerShell console in Kudu

Now that you are in Kudu, we'll go see our node.js stderr logs. Open a PowerShell console using the menu at the top.

Browse to site/wwwroot/iisnode and click edit (pencil button) to view the logs you are interested in, in my case, I checked one with stderr (error) in the filename.

iisnode folder from console

Error log in edit mode in Kudu As you can see I have a problem with a dependency: sqlite3

In my case, I did the npm install --production command as instructed in the error message but it didn't help at all. I suspected a npm cache problem so I decided to delete the whole site/wwwroot/node_modules folder thinking maybe an older dependency version was causing a problem during modules installation. I tried to delete node_modules completely but the node.exe process was locking a dependency. To help here I needed to kill the node.exe process.

Kill node.js process

Browse to Process explorer and click on the Properties button of node.exe
Process explorer in Kudu

Browse to the bottom of the details window and you'll have the option to kill the process, this is what I've done in my case.

I went back in a PowerShell console to the site/wwwroot/node_modules and was able to delete the whole folder without problem.

Now I needed to tell npm to reinstall all modules but the cache caused me problems before. Here is the commands I ran while being in the site/wwwroot folder:

npm commands in wwwroot folder

npm cache clean  
grunt clean  
npm install --production  

After doing that, I tried to hit my website again and everything lifted as expected.

Fixed and working Ghost installation

Hope it help you diagnose Ghost dependencies problems on Azure and where to look to have more information from node.js logs.

Resources

I am the proud father of two little gems. A beer & wine enthusiasm. For everything else, I work and play with Azure at day, and I am an Azure MVP & Advisor at night.
Montreal, Canada