Azure Static web site hosting meets Jekyll

Microsoft’s new solution for hosting static web sites in Azure storage is currently in preview. So why not take it for a spin with the static web site generator Jekyll? Those two seem to be a good match. Let’s give it a go!

Setting up a storage account

The first thing you need to do, is to set up the Azure storage account. You can do this in the Azure portal, but I prefer to use the Azure CLI. Here are the steps:

Steps to create

The first thing is to log in to Azure and, if your account has access to more than one subscription, select the subscription to use for our Azure resources. Next, create a resource group that will contain our resources, give it a name and specifying it’s location to be West Europe. Take notice of the --kind and --sku arguments, especially when the service is still in preview.

Enabling static web site hosting

The next thing you need to do, is to switch on static web site hosting on the storage account. There is currently no way to do this using the CLI, so you need to head over to the Azure portal and do the following:

1. Select Static web site (preview) on the left menu.
2. Toggle Static website to be enable.
3. Add index.html as the index document name.
4. Add error.html as the error document path.
5. Take notice of the primary endpoint. (You’ll need it later.)

Generate a static site using Jekyll

Jekyll is a static site generator written in Ruby. It is a key component that drives the Github Pages solution. In my experience, it is troublesome to run smoothly on Windows (a problem it inherits from the Ruby ecosystem in general), so if you are on a Window system, I recommend using the Windows Subsystem for Linux, or using a Docker container with the Jekyll toolchain already installed.

Assuming that you have Ruby already on your system, here’s how you install Jekyll:

Once this is done, you can have Jekyll scaffold the project, and serve the web site locally on your workstation:

Now you can head over to http://127.0.0.1:4000 and watch your scaffold-ed site:

Publishing your static web site

Before having Jekyll generate the site for production, open the _config.yml file in an editor and set the url parameter to point to your production hostname, for instance “https://staticjekyll.z6.web.core.windows.net”.

Then you are ready to generate a production version for the site, and upload it to Azure:

The web site is generated in the dist directory beside the src directory, and then uploaded to the automatically generated $web container in the blob store. Then, you can head over to new web site:

If you’re happy with having your site hosted in the .web.core.windows.net domain, you’re done! If you wish to host it on your custom domain, read on!

Serving your site using Azure CDN

If you wish to serve your site on your own domain, using HTTPS, configuring to serve your pages using the Azure content delivery network (CDN) is the key. You can set this up in the Azure portal.

Important: now when the static site hosting is in preview, don’t start configuring the CDN from the storage account. Instead, start fresh from the Azure portal dashboard (not in a storage account context):

Set Origin type to Custom origin, and then manually type the value for Origin hostname. Click Create and wait a while for the CDN endpoint to be ready to serve your site. You might have to wait a few minutes. Then, head over to https://<endpoint-name>.azureedge.net in a browser to check that your endpoint is working.

Setting up a custom domain

When the Azure CDN endpoint is working, the next step is to configure a custom domain. As an example, I set up a hostname in my domain, pwrsh.io. I use DNSimple for my domain services:

You need to set up a CNAME record that points to <cdn-endpoint-name>.azureedge.net. Also, if you have CAA records set up for your domain, make sure you have one record that enables Digicert.com to issue certificates for your domain, as this is the CA that Azure uses.

Once your DNS records are set up, head over to the Azure portal and add a custom domain to the Azure CDN endpoint:

Enter your custom hostname, and notice that a green check mark will appear on the right if your DNS records are set up correctly. Click Add.

Enable HTTPS for the custom domain

The last step that you probably want to do, is to enable HTTPS for your custom domain. For this, a certificated issued for your domain is needed. You can bring your on certificate to the party, but the easiest thing to do is to let Azure CDN manage the certificate for you.

Click on the custom domain for the endpoint:

Toggle Custom domain HTTPS to be On, and make sure that the Certificate management type is set to CDN managed. Then save the form. The process will start, and the progress will be indicated like so:

Then wait. Go for a cup of coffee. Go for lunch. Dinner, maybe. Sleep through the night. I did. My experience is that the validation part can take a surprising amount of time. Hopefully, you’ll experience it taking “a few minutes”, like the documentation states.

Once the process is complete, you can direct your browser to your custom hostname using HTTPS:

And you’re done with the setup. Now, add content to your site. Good luck!