Deploying a Hugo Site to Cloudflare Pages

For my personal blog (this site) I wanted something that is easy to use since this is my first blog. Hugo seems like a good choice because I can write in Markdown, and using Cloudflare Pages means I can register my domain, configure DNS, and host the site all from the same interface. Pretty convenient.

Cloudflare Pages have one big advantage vs Github Pages: with Cloudflare Pages you can build your site from a private Github repository. Where as if you want a Github Pages site from a private repo, you need to pay Microsoft.

Setting up Hugo

Cloudflare’s guide covers pretty much everything. Basically:

  1. Install Hugo
  2. Create a new project/site using hugo new site
  3. Turn the project into a git repository (don’t know why hugo new site doesn’t do this automatically)
  4. Do some basic setup for your site
    • Add a theme you like from Hugo Themes
    • Modify your site’s configuration by copying the default configuration for the theme
  5. Create a new Github repository and push the site to it (should also work with Gitlab)

Deploying to Cloudflare Pages

This part is straight forward. You almost don’t need to read the guide, the UI is intuitive enough to setup everything.

  1. From your Cloudflare dashboard, in account home (not site), go to Workers & Pages > Create application > Pages > Connect to Git
  2. Follow the instruction to give permission for Cloudflare to access your repo. I only gave permission to the my site’s private repo.
  3. Back at Cloudflare’s interface, setup the build and deployment configuration.
  4. Click Save and Deploy

After deploying the site, you get a unique *.pages.dev subdomain for your project.

Setting up Custom Domain

This part is also straight forward since I registered my domain with Cloudflare, so I didn’t need to configure nameservers.

Redirect www to domain apex

You need to do this if you also want to access your site with the www subdomain, for example https://www.example.com should also go to your site (https://example.com).

This is the part where I had trouble following the guide, since the guide had some discrepancy with the actual Cloudflare UI. I was also confused since I thought you can do this by creating a CNAME record that points the www subdomain to the apex domain, which I think doesn’t work because you have to use Cloudflare Page’s UI to add the custom domain in order to use custom domains to access your site. According to Cloudflare (link):

To ensure a custom domain is added successfully, you must go through the Add a custom domain process described above. Manually adding a custom CNAME record pointing to your Cloudflare Pages site - without first associating the domain (or subdomains) in the Cloudflare Pages dashboard - will result in your domain failing to resolve at the CNAME record address, and display a 522 error.

Anyways, to redirect www to your domain apex:

First, proxy the DNS record of the www subdomain through Cloudflare, in order to use Cloudflare’s Bulk Redirect (and Single Redirects, however that is not used here) (doc):

  1. Add an A record that points your www subdomain to 192.0.2.1 and set the proxy status to proxied

Next create the Bulk Redirect rules:

  1. Create a new Bulk Redirects list, by clicking Create Bulk Redirect List
  2. Name your redirect list
  3. Click manually add URL redirects
  4. Fill in Source URL and Target URL
    • Source URL: your www subdomain without the https, ex: www.example.com
    • Target URL: your apex domain with the https, ex: https://example.com
  5. Select Edit parameters and select Preserve query string, Subpath matching and Preserve path suffix
  6. Click Next and Next to finish creating the Bulk Redirects list
  7. Next you need to enable the list by creating a Bulk Redirect rule, so click Create Bulk Redirect Rule
  8. Give your rule a name, select the list you created earlier, and click Save and Deploy
  9. Done!

Now you have a working Hugo site hosted with Cloudflare Pages, and you can access it with a custom domain with or with out the www!