Sample code for generating a GitHub Pages-like solution with Azure

This repo contains the source code used in my "Building a Better GitHub Pages Experience Using Azure Services, How Hard Can It be?" that was been presented at NDC Oslo.

What does it do?

There are 3 parts in this solution. There is a Pulumi based infrastructure as code part, a Jekyll-based web application, and an Azure DevOps pipeline to manage the builds.

Pulumi

Let's start with the Pulumi part. All the code for this is located in /Pulumi.

First of all, you need to have Pulumi installed. For information about that, have a look at https://www.pulumi.com/docs/get-started/install/.

Note: On Windows, I do recommend using Chocolatey for it. It makes it so much easier to update in the future.

Next, you need to log-in to Pulumi to tell it where to store it's state. For playing around with it, you can run

cd Pulumi
pulumi login file://.

This will store the state locally in a subdirectory to your current directory. In this case /Pulumi/.pulumi.

For production use, I would suggest storing the state in AWS S3, Azure Storage or using the Pulumi service.

There is already a Pulumi project, and a stack called dev. However, you need to initialize the stack in the state store. So the first thing you need to do, is to run

pulumi stack init dev

When doing this, it will ask for a passphrase. This is because there is already a stack-file (Pulumi.dev.yaml) in place. So you need to enter that passphrase, instead of generating a new one. The passphrase is Password1!.

Now that here is a stack available, you are almost ready run Pulumi. But there is a small caveat or two... In the Pulumi.dev.yaml you will find the settings for the Pulumi script. In there, you can change the Azure datacenter being used. Right now it is using North Europe. On top of that, there is a setting called AzurePagesDemo:projectName that defines the name of the resources to create. This is likely to collide with existing Azure resource names. So you will likely want to change this.

Inside /Pulumi/website-environment.ts you will also find some code that has to do with setting up the CName in the DNS. This needs to be updated with your DNS resource information. And you will need to run the script using an account that has permission to add RecordSets to the DNS Zone.

Speaking of accounts, you also need to sign in to the Azure CLI and select the Azure subscription to use. This is because Pulumi uses the CLI under the hood to perform its job.

az login
# PERFORM LOGIN
az account set -s "<SUBSCRIPTION ID>"

The last thing you need to do before running Pulumi is to install the npm packages using npm i.

Once the packages are installed, you should be ready to run the Pulumi script by executing

pulumi up

This will verify what resources needs to be added/updated/deleted, and then ask you if you want to perform the changes. At what point you say "Yes".

Creating the static website using Jekyll

The system is built around a static website generated by Jekyll. However, I'm not so interested in that part as such, and there are a bunch of really good Jekyll resources on the interwebs. However, it might be nice to know how to generate the site using Docker. To do so, you can just run

docker run -v "<AZUREPAGESDEMO DIR>/Site:/srv/jekyll/source" -v "<TARGET DIR>:/srv/jekyll/destination" --rm -e JEKYLL_ROOTLESS=true jekyll/jekyll jekyll build --source /srv/jekyll/source --destination /srv/jekyll/destination

This will spin up Jekyll, generate the site based on the template in <AZUREPAGESDEMO DIR>/Site, and output it to <TARGET DIR>. Finally, it will just kill the Jekyll container and remove it.

Note: In the post template there is a reference to the domain name azurepagesdemo.azurewebsites.net. This needs to updated with your chosen project name.

Settig up the Azure DevOps

The last part is the Azure DevOps pipeline. The pipeline is alread in place, and just needs to be added to a new Azure DevOps project. However, it does contain some references to AzurePagesDemo in the properties section, so you will need to update based on your selected project name.

Once you have made those changes, you can simply push the code to an Azure DevOps project and add the pipeline to the project. However, it does require you to set up a Azure Rresource Manager Service Connection called AzurePagesDemo for it to work.

Conslusion