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.
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
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
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.
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
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 cache clean
grunt clean
npm install --production
After doing that, I tried to hit my website again and everything lifted as expected.
Hope it help you diagnose Ghost dependencies problems on Azure and where to look to have more information from node.js logs.