Migrating to Azure Static Web Apps

I recently took the decision to move my blog away from Wordpress to one hosted on Azure Static Web Apps using Azure CDN to host my static content such as images. I wanted to share my experience of moving and share some tips which may help you if you are thinking of doing the same.

But before I begin, let me talk about the setup a little bit. I am using Jekyll which is a static site generator based on the Ruby programming language. In order to run your blog or website you do need to have experience and knowledge of a number of concepts which I will cover in this post.

Backend setup

First of all, I want to talk about the backend setup of the blog. It’s pretty simple, and very cheap to run. I have a storage account for my static assets, such as images, and stylesheets. In front of that I have a Azure CDN profile and endpoint, followed by an Azure Static Web App, connected to a private repository in my GitHub account. That is pretty much it! I have a diagram below which gives you an outline of roughly how this is put together.

High level architecture using Azure Static Web Apps and Azure CDN

Azure Static Web Apps are a preview service currently, while I’ve been using them up until the migration of the blog, I’ve not experienced any issues with them so seem to do a great job, bear in mind in preview though if you’re considering it for a critical workload.

Setup of Jekyll

A number of static site generators exist, you could use any number of them including Gatsby, Hugo, VuePress or Jekyll. Microsoft have a great guide for using Jekyll and getting it setup on your machine. Installing Jekyll is really simple, it uses Ruby as I mentioned earlier. Many of the static site generators come with a CLI for issuing commands against your static site, many of the packages are Linux based and you have to be careful around the Windows support for some of them.

I’ve used Jekyll before, if you have used a blog based on GitHub Pages then that is actually using Jekyll as well. To get started, you will first need to install Jekyll. For Windows users, you can install using RubyInstaller or by using the Windows Subsystem for Linux. Personally, I found the RubyInstaller method the easiest.

Once you have installed the pre-requisites, you can then install Jekyll. It’s really easy, from the command line, just issue the command gem install jekyll builder. This will take a few minutes to complete, check your installation once you have finished by checking the version of Jekyll using jekyll -v. This will let you know if your installation has completed successfully or not.

Creating your Jekyll site

When you have completed the installation of Jekyll, it’s really again quite simple to get started. In the directory you want to create your new site, from the terminal, you can use the Jekyll CLI to create a new app. This is done simply by typing jekyll new blog, this will create a directory called blog in your working directory and install the required components.

You can check your site locally as well, first you need to serve your content using bundle exec jekyll serve, this creates a local web server on port 4000 and when compelted, you can browse to http://localhost:4000 and see your site. You can again use the Jekyll CLI to build your site, running jekyll build will output the static version of your site to the _site directory.

Commit your changes to your local Git repository, if you are using the CLI, you can do this using the command git add -A and git commit -m "Initial commit". Then you can push your application over to your GitHub account. Again using the CLI this is very simple to do, you can of course use a GUI if you prefer. First, add the remote origin using git remote origin https://github.com/<username>/<repo-name> and then push using git push --set-upstream origin master.

Now your code is stored within your GitHub account in the repository you have created. Next we need to create the static web app to build and serve the content.

Creating your Azure Static Web App

During the resource creation process for your Azure Static Web App, you will be asked to connect to your GitHub account, currently in the preview, only GitHub is supported. You will need to select your GitHub organisation, repository and branch you want to serve your static web app from. After providing this information on the Build screen, you will then be given the option to specify some additional details.

For App location, set this to /_site, if you remember above, the built site get’s generated to this directory. When the static web app resource is created, this will generate a new workflow which will be stored on your GitHub repository in the form of a GitHub Action. This is now what is executed upon a commit to the selected branch or a pull request to that branch which is closed. If you look at the logs from one of your builds, you will actually see that a container is created and deployed with your static content.

Adding a custom domain

Of course, you get by default a URL which will look like https://<random-string>.azurestaticapps.net/, you will likely want to add your own custom domain to this. You can do this in the Custom domains blade within the static web app. Simply add the URL you like and your DNS will need to include a CNAME from the domain you require mapping to the domain provided by the static web app. This process will also automatically issue a certificate for you, so you don’t need to worry at the moment about providing your own certificate.

Authoring workflow

Authoring a new post is really simple. In your _posts directory, simply create a new markdown file, the name of the file should be the date and title of the post in a slugifed format. For example, YYYY-MM-DD-this-is-my-post.md. I also upload my static content to my storage account which the CDN will take care of.

When I’m ready, I commit to my repository and push up to GitHub, then the workflow will execute and when completed the published content will be available on the static web app.


I like the process, it works well for me and the site is blisteringly fast as it’s all static content, my one biggest complaint about WordPress was the speed, with even minimal plugins, a basic theme and caching it still seems pretty sluggish. One improvement I did make pretty quickly is on the build ability in the pipeline, I don’t want to use jekyll build before every commit and upload a bunch of files more in my commit.

You can achieve this really quickly and very easily by editing the workflow file. After the line - uses: actions/checkout@v2 in the configuration file, add the following.

- name: Set up Ruby
  uses: ruby/setup-ruby@ec106b438a1ff6ff109590de34ddc62c540232e0
    ruby-version: 2.6
- name: Install dependencies
  run: bundle install
- name: Jekyll build
  run: jekyll build


In short, what you see at the minute scores the high 95+ scores for both mobile and desktop sites on PageSpeed Insights. That is much better than the low 50-55 scores I was getting with WordPress and a decent caching solution in place. I also have the benefit of a really simple architecture, no server side coding so a very secure solution, no usernames or passwords involved and no administration backend to protect.