A guide on how to deploy a Hexo static site using Azure Storage.
- 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
- 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.
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.
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.
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
# 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
Hexo is now ready.
Start the development server:
# Launch local 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:
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
All generated assets will be placed in:
Provision Azure Resources
Log into your Azure Portal
- Navigate to Resource Groups
- Click Add
- Select Subscription, Name, and Region
- Go to your newly created resource group
- Click Add
- Search for “Storage Account”
- Select it and press Create
- Select your subscription and resource group
- 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
- Review and submit for deployment- resources should take a few minutes to provision.
Upload Static Site to Azure Storage
- Navigate to your newly created storage account.
- On the Azure Settings blade, locate Static Website and set it to Enabled.
- Specify index document as
index.htmland supply a
404.htmlif you have one.
- Download and install Azure Storage Explorer. We’ll need it to upload your static files.
- 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
Azure Storage Explorer
- Open it and upload the contents of your
- Navigate to
Resource Group > YourStorageAccountName > Static Websiteand check your primary endpoint.
It will look something like this:
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!
- 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.
- Review and create
- Navigate to the settings of your newly created CDN endpoint
- On the settings blade, open Custom Domains
- Add a CNAME record to your domain registrar pointing to your CDN endpoint. More on that here.
- In Azure, add custom domain.
- 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
- Once validated, open your custom domain in a browser- it is now accessible over HTTPS.
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!
Please make sure you reference the latest docs when building or deploying your project- depending on when you read this, things could have changed.
Static website hosting in Azure Storage
Integrate Azure CDN with a storage account
Configure HTTPS on an Azure CDN custom domain