As I’ve both written in the About section of the site and in my recent update about the status of the blog, the site got its start on AWS Amplify. AWS Amplify is “a set of purpose-built tools and features that enables frontend web and mobile developers to quickly and easily build full-stack applications on AWS.” In short, for my needs I set up the contents of this Jekyll-powered site on GitHub in a private repo, added that to Amplify and let it build the site whenever I push in a new blog post to the repo. Simple, quite elegant and most importantly, at least at the time, completely free.
But ain’t no such thing as a free lunch, and once my generous 12 month trial of AWS ran out I started to get billed a little over $4 a month for the site. Now it’s not a massive amount of money, but it does add up and I would much prefer to use it on something else than to keep my rambling musings available online. But at the end of the day I was already in love with Jekyll and the convenient CI/CD pipeline that AWS offered, so setting things up e.g., on a some low use VPS wasn’t really something I was too keen on. Enter Azure.
Azure Static Web Apps
Having moved my overall cloud learning focus towards Azure I find their offerings when compared to AWS to be much less generous and way more limited with “To access this feature you need this license - but here’s a trial for a month” in every turn, but one thing that they do offer for free for hobbyists is Azure Static Web Apps.
This is effectively the Amplify of Azure, and it’s used to automatically build and deploy full stack web applications from a repository you control. I have my blog on GitHub, so drop in the link and we’re off to the races? Well, not quite. Not quite at all.
Prepare Jekyll
First we’ll need to make sure that we have Jekyll available for deployment on GitHub. The old theme I used is no longer supported, so I ended up moving to Chirpy, which also offers an easy starter version that you can just use as a template to be up and running practically instantly. Check out https://github.com/cotes2020/chirpy-starter, and if it tickles your fancy click on Use this template and select *Create a new repository. This repository can be kept private if you wish.
Alternatively you can read about Jekyll at https://github.com/jekyll/jekyll to get started with a basic site of your own.
Local Jekyll Installation (Optional)
This step is optional, but if you want to have an easy way to check that everything works fine locally before pushing your updates to GitHub, you can install Jekyll locally and quickly set up an instance when you need to check things.
The actual installation varies a bit depending on your platform, so refer to https://jekyllrb.com/docs/installation/ for more specific details. Once you have everything installed, just enter the directory you have your site in and run jekyll serve. This will set up a web server, by default on port 4000, which you can use to see that you didn’t break anything. Or in the likely scenario that you did, you can use it to verify that you end up fixing it.
Creating a Static Web App on Azure
Creating a new Static Web App is straightforward enough: open the service in Azure Portal, select your Subscription, choose or create a new Resource Group, enter a Name for the site (this is just for your own records, the actual URL will be random), select the Free plan, select Region and finally select your Deployment details, i.e., where your code is stored. Once you link your GitHub account to Azure you can easily select from all available repositories and branches. So far so good.
Build Details Shenanigans
This part is going to take some explaining and modifications, and most likely lots of notification emails from GitHub telling you that your deployment actions failed.
Once you select the Branch of your project you get to select from a list of Build Presets. With Jekyll, this will be Other, Custom. Next you need to fill in the App location, which will be /_site, and do not forget that underscore nor the forward slash.
You can also check the Workflow configuration as that’ll be the next step, but you can’t edit it yet. Just Review + create and let its do it’s thing.
Fixing the GitHub Actions workflow
Once everything goes through, you’ll get a notification email from GitHub telling that the deployment failed. Ruh-roh. If you look into the error message, it’ll state the following:
Node.js 12 actions are deprecated. Please update the following actions to use Node.js 16: actions/checkout@v2. For more information see: https://github.blog/changelog/2022-09-22-github-actions-all-actions-will-begin-running-on-node16-instead-of-node12/.
Why has this not been fixed in the default workflow file I do not know, but we’ll get that fixed. Go to your site repository, enter .github/workflows and open the .yml file there. It’s named after the random URL Azure assigns to you, and will be along the lines of azure-static-web-apps-rainbow-bear-randomnumbers.yml. Feel free to be lazy and edit the file on GitHub.
Like the error message stated, we need to use a more recent version of Node.js, so we’ll change the uses: actions/checkout@v2 to uses: actions/checkout@v3. In addition to that, we need to add the following block of code right under it, and before the - name: Build And Deploy part of the file:
1
2
3
4
5
6
7
8
- name: Set up Ruby
uses: ruby/setup-ruby@v1.59.1
with:
ruby-version: 2.6
- name: Install dependencies
run: bundle install
- name: Jekyll build
run: jekyll build
With these changes done our site will be built correctly. Save the edits and commit the changes to the workflow file to re-start. It’s probably going to take couple minutes, but then your new site will be online and accessible via the URL assigned to it by Azure.
Using a Custom Domain Name
While the randomly generated domain name might end up being funny, it’s probably not something you’ll want to be using outside of testing. Luckily using your own domain is extremely easy, and Microsoft will even throw in the SSL certificate for free.
Open up the Static Web App you’ve created, go to Settings and select Custom domains. Click on Add and select the option that matches your use case. If you have your domain on Azure go with that, in the likely scenario that you don’t, choose the other one. I have mine on Gandi, so we’ll proceed with that and enter the domain name and its extension, no other details.
Once the domain is added it needs to be validated. This is done by adding a simple TXT record to your domains DNS records. How exactly this can be done depends on your registrar, so check their documentation, or just wing it by replicating the steps for Gandi from below - they’re likely very similar anyway.
Open up your domain information, select DNS Records, click on Add records, select TXT as the type and paste the validation code you got from Azure into the Text value field. Create the entry and let it propagate. This can take quite a few hours, so go study for an Azure exam meanwhile.
Once the validation is done you’ll see the domain as Validated on Azure, and can proceed to add the A record for your domain. In order to find the IPv4 address you need to open up your Static Web App, select Overview and click on JSON View. Look for stableInboundIP. Copy this address and go create a new A record for your domain with it. Create the record and once again wait a little. Once the propagation finishes your site will be accessible via your domain.