Hosting Jekyll website on Azure Static WebApps

Now that Azure now has a free service for hosting static web apps via Azure Static Web Apps, I decided to write a quick post on how to host Jekyll website on Azure Static WebApps. To my surprise it turned out to be quite simple and easy to host.

Jekyll - static site generator

Jekyll is a simple, static site generator.

Installation

Jekyll website has a good post on installation already based on your operating system. You can use WSL (Windows Subsystem for Linux) and it works just fine. If you specifically like to have Windows installation guide, David Burela has posted a neat trick to install it in 3 easy steps here using Chocolatey.

Creating a simple blog

Once you have Jekyll working, you can create a simple blog post by running the following command

jekyll new .

This will create a basic a blog structure which will look like below.

The _posts folder will contain all your blog posts and each post is a markdown file. Each markdown contains a front matter which allows you to add the meta data for the post.

Now to run your website locally run jekyll serve and you will see the blog up and running in local machine under port 4000 at http://localhost:4000.

Jekyll will build your site using jekyll build and store the generated static content in _site folder. Your site will be served from this _site folder.

Source control your website using GitHub

1. Initialise the repo

 git init

1. Commit the changes

 git add -A
 git commit -m "initial commit"

I committed mine here. Finally push the changes to the repo.

1. Next, create a repo on GitHub (if you have not done already) and add the remote to that GitHub repo.

 git remote add origin https://github.com/<YOUR_USER_NAME>/jekyll-azure-static

1. Finally, push the repo

 git push --set-upstream origin master

Deploying the to Azure Static Web App

Create the application

1. Navigate to the Azure portal
2. Click Create a Resource
3. Search for Static Web Apps
4. Click Static Web Apps (Preview)
5. Click Create
6. Fill the details and click Sign in with GitHub button

You will be prompted to authorise the Azure Static WebApp to GitHub. Make sure you Grant access to organisation that has the repo.

Complete the steps in the popup and you will see the below screen where you will select the repository and organisation. My values look as below.

⚠️ If for any reason, you missed granting access to the right organisation, you have to Revoke that Authorisation from GitHub by going to Applications section in the Settings and Revoking for Azure Static Web Apps as shown below

Setting up Build

1. Next click Next: Build > button to edit the build configuration.
2. Set the App location to _site since, that is the default folder where Jekyll puts the generated files.
3. No need to fill the App artifact location and also API location as this is not an API.

Review and create

1. Click the Review + Create button to verify the details are all correct.

2. Click Create to start the creation of the Azure Static Web Apps and provision a GitHub Action for deployment.

1. Once you see the notification that resource deployment is successful, the Azure Static Web App would have created a workflow for GitHub Action on the repository.

2. Navigate to your terminal and pull the commit with the GitHub Action to your machine.
   

 git pull

1. In the workflow at .github\workflows\<workflow-file-name>.yml, replace the line - uses: actions/checkout@v1 with the following, to build the Jekyll application.

In the below steps, I am setting up Ruby (needed for installing Jekyll and dependencies), then installing the dependencies (using bundle install) and finally calling jekyll build to generate the static site.

    - uses: actions/checkout@v2
      with:
      submodules: true

    - name: Set up Ruby
      # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
      # change this to (see https://github.com/ruby/setup-ruby#versioning):
      # uses: ruby/setup-ruby@v1
      uses: ruby/setup-ruby@ec106b438a1ff6ff109590de34ddc62c540232e0
      with:
      ruby-version: 2.6

    - name: Install dependencies
      run: bundle install

    - name: Jekyll build
      run: jekyll build

    - name: Build And Deploy
      id: builddeploy
      uses: Azure/static-web-apps-deploy@v0.0.1-preview
      with:
      azure_static_web_apps_api_token: $
      repo_token: $ 
      action: 'upload'
      app_location: '/_site' # App source code path
      api_location: '' # Api source code path - optional
      app_artifact_location: '' # Built app content directory - optional

I had a struggle with this to be honest. Eventually I had to change the app_location path to generated /_site instead of setting it as just _site (see line # 27)

Refer to the complete workflow file in the repository

1. Commit the updated workflow and push to GitHub.

 git add -A
 git commit -m "Updating GitHub Actions workflow"
 git push

1. Wait for the GitHub Action to complete.

2. In the Azure portal’s Overview window of newly created Azure Static Web Apps resource, click the URL link to open your deployed application. You can check the the demo site here

Isn’t it cool! Go check it out.