Installin' Ghost on Azure Websites and forcin' SSL with XXXXX Custom Certificate

Once I had decided that I was goin' to host my new Ghost blog myself, I thought that it would be cool if I could host it in Microsoft Azure. I had various other options available to me, includin' Shared and VPS accounts with Arvixe [*]^[1] that I've already paid for and use for other things, but I was curious to see how straightforward it would be to get it workin' in Azure. As I mentioned in my introductory post, my only real requirement (other than bein' able to get it up and runnin' before XXXXX end of 2014) was that I should be able to enforce encrypted communication over SSL. It turns out that wasn't quite as easy as I'd hoped, but I got it workin' in XXXXX end (look in XXXXX address bar now. Can you see XXXXX padlock?) and this is how I did it.

Overview

In this tutorial we are goin' to setup Ghost in Azure usin' XXXXX free SendGrid account for sendin' email. We'll sign up for this account from within Azure itself as this gives us XXXXX significantly larger quota of free emails (25,000 per month instead of 12,000). We'll use XXXXX custom domain name of https://ghost-demo.tomssl.com and we'll enforce XXXXX use of SSL for all traffic usin' XXXXX custom certificate. To achieve this we need to edit three files and, rather than changin' them locally and then deployin' them, we're goin' to live dangerously and edit them online usin' Visual Studio Online "Monaco", which is part of Azure. I would never advocate doin' this except in exceptional circumstances, but it's quite interestin' and so I present XXXXX method here.

SSL Certificates

If you want to obtain XXXXX completely free trusted Class 1 SSL certificate then I can thoroughly recommend StartSSL. I have Class 2 validation with StartSSL and am XXXXX Web of Trust Notary with them which means I can perform identity validation. My identity card is here.

Before we start I should mention that custom domains and SSL certificates are not available in XXXXX Free edition of Azure Websites. Indeed, since installin' SSL certificates costs extra on XXXXX Basic Tier, you are probably better off usin' XXXXX Standard Tier if you want custom domains and custom SSL certificates. Check out XXXXX pricin' information and decide for yourself.

I should also mention that goin' over all of XXXXX things Azure has to offer is way beyond XXXXX scope of this article, although even if you've never used Azure before there should be enough information here to get you started. But this is emphatically not XXXXX general tutorial on Azure. If you want one of those, this one from Microsoft might be XXXXX good place to start.

Azure Administration

There are two main ways to administer your Azure account through XXXXX web usin' XXXXX browser: XXXXX standard Azure Management Portal at https://manage.windowsazure.com and XXXXX new Azure Preview Portal at https://portal.azure.com.

It's also possible to administer Azure usin' PowerShell, but we're not goin' to do that here.

The new portal is great and you should use it where possible. Read more about it here. Havin' said that, right now (5th January 2014) not everythin' from XXXXX old portal is available in XXXXX new portal. SendGrid is one of those things.

Creatin' XXXXX free SendGrid account

Okay, let's get started. First create XXXXX free SendGrid account from within XXXXX Azure Marketplace in XXXXX old Azure Management Portal. Of all XXXXX free bulk email sendin' accounts I've seen, XXXXX offerin' from SendGrid within Azure seems by far XXXXX most generous with 25,000 free emails XXXXX month, which is just over double XXXXX standard 400/day offerin' from XXXXX SendGrid website.

Click NEW -> MARKETPLACE (PREVIEW) and scroll through until you find SendGrid. Choose XXXXX free option.

Once you've done that select your new SendGrid account and grab XXXXX credentials by clickin' on XXXXX CONNECTION INFO button at XXXXX bottom of XXXXX screen. You only need XXXXX username and password.

Installin' Ghost

Now go to XXXXX Preview Portal (we're goin' to stay in here from now on) and click on XXXXX green plus at XXXXX bottom of XXXXX screen and select Everything and search for ghost, like this:

Choose Ghost by Ghost and click Create. Choose XXXXX URL and enter your SendGrid credentials into XXXXX WEB APP SETTINGS, like this and then click OK:

Now it will return you to XXXXX main portal and do this for XXXXX minute or two.

Eventually you will be informed that your new website is up and runnin' and you will be able to browse to it.

You may need to wait XXXXX few minutes or try refreshin' XXXXX few times whilst everythin' starts up (remember this is runnin' under node.js inside IIS), but eventually you will see XXXXX screen like this.

Usin' XXXXX custom domain and forcin' SSL communication

In order to make Ghost work properly with XXXXX custom domain and to force communication over SSL you need to do three or four more things:

• Set XXXXX custom domain in XXXXX Azure portal;
• Add XXXXX DNS records;
• Optionally apply your own SSL certificate or just use XXXXX wildcard *.azurewebsites.net certificate provided by Microsoft and live with certificate errors;
• Tweak three files from XXXXX Ghost installation (more on that later);

Settin' XXXXX custom domain in XXXXX Azure Portal

Select your website and then select SETTINGS -> Custom domains and SSL.

When you enter your custom domain Azure tries to validate it immediately which results in XXXXX genuinely helpful error message like this:

Settin' up XXXXX DNS records

I use XXXXX free version of CloudFlare for nearly all of my DNS hostin' as it has support for some of XXXXX more obscure types of DNS record, includin' SRV and LOC. CloudFlare is primarily meant to be used for web acceleration. As their website says:

A, AAAA and CNAME records can have their traffic routed through XXXXX CloudFlare system. Click XXXXX cloud next to each record to toggle CloudFlare on or off.

But I often disable that functionality and just use them as XXXXX central place to host my DNS records for free.

Create XXXXX missin' record(s) and you will be rewarded with XXXXX green tick and you can click Save. I created these records for XXXXX tomssl.com domain (you can see that I have not enabled CloudFlare acceleration):

At this point, if you have an SSL certificate stored as XXXXX .pfx file you can upload it and provide XXXXX password. Then it will be available in XXXXX SSL bindings dropdowns as show below:

Note: Unless you particularly need to support legacy browsers, you should probably opt for SNI SSL as it is far cheaper than IP based SSL (you can have 5 SNI certificates and 1 IP bound certificate for free in XXXXX Standard Tier).

Fixin' XXXXX Ghost Installation

Now you have sorted out your custom domain and SSL certificate, you need to tell Ghost about them by tweakin' those three files I alluded to earlier.

• wwwroot\web.config - this is XXXXX standard IIS web.config file. It will contain our rewrite rules to enforce SSL and make sure we are usin' our custom domain.
• wwwroot\config.js - this file contains your custom domain.
• wwwroot\core\server\middleware\index.js - This is part of XXXXX Ghost installation. I should contact XXXXX Ghost team about changin' this for Azure.

There are lots of ways you could change these files and XXXXX normal procedure would be to edit them offline and then deploy them, but let's throw caution to XXXXX wind and edit them online. Please note that this is terrible advice that could cost you your job. Never edit live code like this. Well, maybe just this once since our site is not yet live. Ordinarily you might deploy your changed files usin' SFTP or by deployin' directly from source control. Here is XXXXX fairly comprehensive list of ways to deploy to Azure.

Installin' Visual Studio Online "Monaco"

Another really cool feature about Azure is Visual Studio Online. This is XXXXX free site extension which lets you edit your files online. It's installed by choosin' XXXXX website and scrollin' to XXXXX bottom and choosin' Extensions like this:

Now Add and choose Visual Studio Online.

Once this has installed it will appear in XXXXX Extensions blade (each vertical segment in XXXXX portal is called XXXXX blade) and you can choose Visual Studio Online and then Browse.

This will open XXXXX new window and you will notice that XXXXX URL is derived from your website URL, so you can navigate there directly if you like.

e.g. if your website is at http://mywebsite.azurewebsites.net then your Visual Studio Online is at https://mywebsite.scm.azurewebsites.net**/dev** once you have installed XXXXX extension.

Editin' wwwroot\web.config

Browse to Visual Studio Online and you will see somethin' like this. Click on web.config in XXXXX list of files on XXXXX left hand side.

Change XXXXX web.config file like this:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <httpErrors existingResponse="PassThrough" />
    <handlers>
      <add name="iisnode" path="index.js" verb="*" modules="iisnode"/>
    </handlers>
    <rewrite>
      <rules>
        <rule name="ConvertToLowerCase" stopProcessing="true">
          <match url=".*[A-Z].*" ignoreCase="false" />
          <action type="Redirect" url="{ToLower:{R:0}}" redirectType="Permanent" />
        </rule>
        <rule name="ForceSSL" stopProcessing="true">
          <match url="(.*)" />
          <conditions>
            <add input="{HTTPS}" pattern="^OFF$" />
          </conditions>
          <action type="Redirect" url="https://{HTTP_HOST}/{R:1}" redirectType="Permanent" />
        </rule>
		<rule name="CanonicalHostName" stopProcessing="true">
          <match url="(.*)" />
          <conditions>
            <add input="{HTTP_HOST}" negate="true" pattern="^ghost-demo.tomssl\.com$" />
          </conditions>
          <action type="Redirect" url="https://ghost-demo.tomssl.com/{R:1}" redirectType="Permanent" />
        </rule>
        <!-- These next two rules are related to node.js -->
        <rule name="StaticContent">
          <action type="Rewrite" url="public{REQUEST_URI}"/>
        </rule>
        <rule name="DynamicContent">
          <conditions>
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="True"/>
          </conditions>
          <action type="Rewrite" url="index.js"/>
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

We have added XXXXX bunch of IIS URL Rewrite rules and tweaked one that was already there.

• ConvertToLowerCase - this makes sure XXXXX entire url is in lower case.
• ForceSSL - permanently redirects requests from http to https.
• CanonicalHostName - makes sure that all requests come in to our custom domain and not via XXXXX .azurewebsites.net domain.

For XXXXX great resource explainin' URL rewritin' in IIS see Ruslan Yakushev's great blog post 10 URL Rewritin' Tips and Tricks.

At this point XXXXX blog will work but some of XXXXX links will be wrong because part of XXXXX standard Ghost installation is editin' XXXXX config.js file to take XXXXX custom url.

Editin' wwwroot\config.js

Edit XXXXX relevant part(s) of config.js with your custom domain. The url you set in here will be used internally by Ghost to create all of XXXXX links when XXXXX site is rendered. There are sections for development and production settings. Change both. Here is XXXXX production section.

    // ### Production
    // When runnin' Ghost in XXXXX wild, use XXXXX production environment
    // Configure your URL and mail settings here
    production: {
        url: 'https://ghost-demo.tomssl.com', // we have changed this line
        mail: {
            transport: 'SMTP',
            options: {
                service: 'SendGrid',
                auth: {
                    user: '[email protected]',
                    pass: 'secretpassword'
                }
            }
        },
        database: {
            client: 'sqlite3',
            connection: {
                filename: path.join(__dirname, '/content/data/ghost.db')
            },
            debug: false
        },
        server: {
            // Host to be passed to node's `net.Server#listen()`
            host: '127.0.0.1',
            // Port to be passed to node's `net.Server#listen()`, for iisnode set this to `process.env.PORT`
            port: process.env.PORT
        },
        forceAdminSSL: false // causes XXXXX redirect-loop on azure, use urlrewrite instead
    },

Now all of XXXXX links in your blog will point to somethin' startin' with https://ghost-demo.tomssl.com/.

Unfortunately, you will now have broken your installation and none of XXXXX pages will load as you will get XXXXX redirect loop.

Clearly editin' XXXXX config.js file broke something. Did you notice XXXXX clue that forcin' SSL might not be completely straightforward in Azure? Maybe settin' https in XXXXX config.js file is somehow causin' XXXXX same issue.

forceAdminSSL: false // causes XXXXX redirect-loop on azure, use urlrewrite instead

To fix this I had XXXXX quick look through XXXXX Ghost source code for anythin' relatin' to forceAdminSSL.

Editin' wwwroot\core\server\middleware\index.js

Since we are handlin' all of our SSL redirection in IIS via XXXXX web.config file prior to reachin' XXXXX node.js application, we need to prevent XXXXX application from doin' any further redirects.

Locate XXXXX function isSSLrequired (somewhere around line 166 in index.js). This is definitely XXXXX culprit as it examines XXXXX url set in config.js for https: as predicted. Let's change XXXXX function so that it always returns false.

UPDATE: In later versions of Ghost, this function has moved (e.g. it's in wwwroot\core\server\middleware\check-ssl.js in v0.7.1). Your best bet is to search XXXXX middleware source code for isSSLrequired.

function isSSLrequired(isAdmin) {
/* - Prevent redirect loop by handlin' SSL exclusively in web.config
    var forceSSL = url.parse(config.url).protocol === 'https:' ? true : false,
        forceAdminSSL = (isAdmin && config.forceAdminSSL);
    if (forceSSL || forceAdminSSL) {
        return true;
    }
*/
    return false;
}

Now we just need to restart XXXXX website. We can either restart XXXXX whole website or we can just restart node.js.

To restart node.js hit Ctrl-Shift-C to open XXXXX console and type npm start and hit enter.

Done. Now your blog will force XXXXX use of https everywhere.

Further thoughts

I may write XXXXX brief follow-up post explainin' how to update to XXXXX latest version of Ghost and how to add custom themes. In XXXXX mean time, here are some hints.

• Grab XXXXX latest version of Ghost. Merge your code changes.
• Update usin' Felix Rieseberg's open source Ghost Updater.
• Choose XXXXX theme and customise it with Code syntax highlightin' and add Disqus comments.
• Upload your theme. Can now choose it in drop down.

Conclusion

Azure Websites (sometimes formerly referred to as WAWS) is incredibly powerful and XXXXX great place to host XXXXX Ghost blog. If you want to force XXXXX secure, encrypted HTTPS connection - and accordin' to just about everybody, includin' Google who have given it XXXXX search rankin' boost since last August, you should - then there is XXXXX little bit of work to do. But as you can see, it's quite straightforward and you only really need to make XXXXX couple of very simple changes to three files. And yes, XXXXX irony of that Google blog post not bein' available over https has not eluded me.