Deploying Hexo Static Site on Azure Storage

Michal Kups

A guide on how to deploy a Hexo static site using Azure Storage.

Objectives

  • Generate static blog pages with Hexo on a local machine
  • Upload blog content to an Azure Storage Account
  • Enable static site
  • Optional: Ensure content is accessible over HTTPS under a custom domain name

Out of Scope
The following should be considered out of the scope of this article:

  • Nuances of Hexo’s theming engine, plugins, and other Hexo-specific components

Dependencies

  • Azure Subscription
  • An hour of your time

Please note that the instructions given below are carried out on a macOS terminal; tools used here are available on all operating systems and CLI commands are applicable to Ubuntu and Windows’ PowerShell as well.

Project Structure
Before we delve into the implementation details, let’s have a top-level overview of the project. It should make this easier to follow and help visualize the dataflow.

File structure:

Dataflow:


Prepare a Dev Environment
I prefer to keep my projects and their dependencies isolated- which can be done with containers or Bitnami stacks;

I’ve covered setting up a Bitnami Stack in a previous entry here should you wish to read up on that.

Note: You can skip this and proceed to the installation phase if you do not wish to setup a separate dev environment or already have one of your own. Keep in mind you will need Node.js and Git installed locally to proceed.


Install Hexo
Now we’re ready to install Hexo. From the terminal:

# Install Hexo package
npm install -g hexo-cli

This will install the Hexo command-line utilities necessary to build a project. It’ll allow you to generate a site from a template.

Navigate to your project directory.

# Confirm we're at the root of our project
pwd
/Users/michalkups/Workspaces/HexoExample

# Initialize Hexo in folder 'AppLogic'
hexo init AppLogic

Hexo-cli will create a project from template within the directory you specified.
package.json is used by npm to determine which dependencies need to be fetched/updated and placed within your project folder.

# Navigate to project directory
# and fetch/update the dependencies
cd AppLogic
npm install

Hexo is now ready.
Start the development server:

# Launch local Hexo server
Hexo server

# Hexo will start and happily inform you that it's running:
INFO Start processing
INFO Hexo is running at http://localhost:4000 . Press Ctrl+C to stop.

Open up a browser and navigate to http://localhost:4000
You should see a Hello World from Hexo:

Hexo Hello World

Generate a Static Site

Next, we need to stop the server with Ctrl+C and generate the static files for our blog.

# Generate static files
hexo generate

All generated assets will be placed in:
../HexoExample/AppLogic/public


Provision Azure Resources

Log into your Azure Portal

  1. Navigate to Resource Groups
  2. Click Add
  3. Select Subscription, Name, and Region
  4. Go to your newly created resource group
  5. Click Add
  6. Search for “Storage Account”
  7. Select it and press Create
  8. Select your subscription and resource group
  9. Specify configuration:
  • Name: Storage Account names in Azure must be unique. I’m using ExampleHexoBlogStatic. Replace this with something meaningful to your project.
  • Location: Choose your region
  • Performance: Standard (we dont need Premium for this)
  • Account Kind: StorageV2

The following settings should be chosen based on your expected load. Leaving them at default should be sufficient.
In my case:

  • Replication: RA-GRS
  • Access Tier: Hot
  1. Review and submit for deployment- resources should take a few minutes to provision.

Upload Static Site to Azure Storage

  1. Navigate to your newly created storage account.
  2. On the Azure Settings blade, locate Static Website and set it to Enabled.
  3. Specify index document as index.html and supply a 404.html if you have one.
  4. Download and install Azure Storage Explorer. We’ll need it to upload your static files.
  5. Open storage explorer, sign in with your Azure credentials. Locate your Storage Account and expand it. Under Blob Containers you should see a folder called $web .
Azure Storage Explorer

Azure Storage Explorer

  1. Open it and upload the contents of your ../HexoExample/AppLogic/public folder.
  2. Navigate to
    Resource Group > YourStorageAccountName > Static Website and check your primary endpoint.
    It will look something like this:
    https://BLOB_NAME.z33.web.core.windows.net/

Open it in a browser.
Your blog is now live.


Configure Custom Domain with HTTPS

If you wish to make your blog accessible using a custom domain and have it served over HTTPS, continue with these steps.

At the time of writing (Feb 2019), Static Sites hosted on Azure storage accounts do not allow for HTTPS with custom domains. There is no way to upload a certificate to enable this functionality.

The workaround for this is to utilize Azure CDN, as it allows for custom domains with content served over HTTPS- and you don’t even need your own SSL certificate!

  1. Go to your storage account. On the Azure Settings blade, locate Azure CDN.
  • Assign profile name
  • Pricing Tier: Standard Microsoft
  • CDN Endpoint Name: Unique Name
  • Origin Hostname: Specify the primary endpoint on your storage blob- you can find it in the static site settings.
  1. Review and create
  2. Navigate to the settings of your newly created CDN endpoint
  3. On the settings blade, open Custom Domains
  4. Add a CNAME record to your domain registrar pointing to your CDN endpoint. More on that here.
  5. In Azure, add custom domain.
  6. Enable custom domain HTTPS with CDN-managed certificate.
  • To complete domain validation you must follow instructions provided by Azure to create appropriate CNAME records with your domain registrar- this record will be used to validate ownership of the domain.
Configure HTTPS with custom domain

Configure HTTPS with custom domain

  1. Once validated, open your custom domain in a browser- it is now accessible over HTTPS.

Conclusion
And that is it- your static Hexo website should be now up and running from your storage blob and/or available through a custom domain with HTTPs if you’ve opted for it.
I hope you found this helpful and can learn from my approach or any mistakes when implementing your own project!


Public Documentation
Please make sure you reference the latest docs when building or deploying your project- depending on when you read this, things could have changed.

Hexo Docs
https://hexo.io/docs/

Static website hosting in Azure Storage
https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website

Integrate Azure CDN with a storage account
https://docs.microsoft.com/en-us/azure/cdn/cdn-create-a-storage-account-with-cdn

Configure HTTPS on an Azure CDN custom domain
https://docs.microsoft.com/en-us/azure/cdn/cdn-custom-ssl

Michal Kups

Written by

IT Engineer sharing a collection of thoughts, sysadmin, and skill development miscellanea.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade