This is how I host a Hugo blog on Cloudflare for free, with the source in a private GitHub repo. Terraform creates the Worker and attaches the domain. wrangler deploy uploads the built site.
I started on Cloudflare Pages, which builds from a private repo and deploys on push. I never applied that Terraform. Pages needs the Cloudflare GitHub app on your account, and I’d rather Cloudflare never sees the repo. Now I build locally and upload only public/, so drafts and history stay with me. The cost is that deploying is a command I run, not a push.
You need
- Hugo installed locally
- A free Cloudflare account, with the domain’s zone on it
- Terraform 1.10 or later, for
use_lockfile - Node, for
npx wrangler - SOPS and age for the secrets
- An S3-compatible bucket for Terraform state. Mine is RustFS on a homelab cluster.
1. Make the site
hugo new site mysite
cd mysite
git init
git submodule add https://github.com/<owner>/<theme>.git themes/<theme>
echo "theme = '<theme>'" >> hugo.toml
hugo new content posts/hello.md
hugo server -D
New posts start with draft = true, and drafts only build with -D. Set it to false before you deploy, or the live site is empty and you spend ten minutes wondering why. (Yes, I did.)
2. Don’t commit the output
printf 'public/\nresources/_gen/\n.hugo_build.lock\n.wrangler/\n' > .gitignore
public/ is what gets uploaded, but it’s rebuilt every time, so it doesn’t belong in git. .wrangler/ is wrangler’s local cache.
3. Push to a private repo
Create an empty private repo on GitHub. No README and no license, or the histories clash.
git add .
git commit -m "Initial site"
git branch -M main
git remote add origin git@github.com:<you>/mysite.git
git push -u origin main
Cloudflare never reads this repo. It’s only the backup and the history.
4. A separate repo for the Terraform
One Terraform repo covers every static site on the account, so it lives apart from the blog. Mine is infra/:
infra/
├── versions.tf # Terraform and provider versions, state backend
├── variables.tf # account ID and the map of sites
├── main.tf # one module call per site
├── outputs.tf
├── modules/static-site/main.tf
├── terraform.tfvars # real values, gitignored
├── backend.hcl # state endpoint, gitignored
├── secrets.enc.env # SOPS-encrypted, safe to commit
└── .sops.yaml
Add this .gitignore:
.terraform/
*.tfstate*
terraform.tfvars
backend.hcl
I commit .terraform.lock.hcl so provider versions stay pinned across machines.
versions.tf
terraform {
required_version = ">= 1.10"
required_providers {
cloudflare = {
source = "cloudflare/cloudflare"
version = "~> 5.0"
}
}
backend "s3" {
bucket = "tfstate"
key = "cloudflare/sites.tfstate"
region = "us-east-1" # required by the SDK, ignored by RustFS
use_path_style = true
use_lockfile = true # S3-native locking, no DynamoDB
skip_credentials_validation = true
skip_region_validation = true
skip_requesting_account_id = true
skip_metadata_api_check = true
skip_s3_checksum = true
}
}
provider "cloudflare" {
# Reads CLOUDFLARE_API_TOKEN from the environment.
}
The provider is v5, whose resource names and shapes differ from v4, so older examples online won’t work. The skip_* lines stop the S3 backend from making AWS calls, which a non-AWS store can’t answer. use_path_style is there because most self-hosted S3 servers don’t do bucket subdomains.
variables.tf
variable "cloudflare_account_id" {
type = string
description = "Cloudflare account ID"
}
variable "sites" {
description = "Static sites served by Workers static assets. The key must match `name` in the site's wrangler.jsonc."
type = map(object({
zone_id = string
domain = string # e.g. example.com or blog.example.com
}))
default = {}
}
main.tf
module "site" {
source = "./modules/static-site"
for_each = var.sites
account_id = var.cloudflare_account_id
name = each.key
zone_id = each.value.zone_id
domain = each.value.domain
}
Adding a site is one more entry in sites. The map key becomes the Worker’s name, and wrangler.jsonc has to use the same name.
modules/static-site/main.tf
terraform {
required_providers {
cloudflare = {
source = "cloudflare/cloudflare"
}
}
}
variable "account_id" { type = string }
variable "name" { type = string }
variable "zone_id" { type = string }
variable "domain" { type = string }
# The Worker shell. Terraform owns its existence and the domain binding;
# `wrangler deploy` uploads the static assets as new versions of this Worker.
resource "cloudflare_worker" "this" {
account_id = var.account_id
name = var.name
observability = {
enabled = true
}
subdomain = {
enabled = true
previews_enabled = true
}
}
# Creates the proxied DNS record and certificate automatically.
resource "cloudflare_workers_custom_domain" "this" {
account_id = var.account_id
zone_id = var.zone_id
hostname = var.domain
service = cloudflare_worker.this.name
}
output "domain" { value = var.domain }
output "workers_dev_name" { value = cloudflare_worker.this.name }
The split matters. Terraform owns the Worker and the domain binding. It never sees your content, so it never shows a diff when you publish a post. wrangler deploy owns the content. The subdomain block turns on the workers.dev address and its preview URLs, and observability turns on Workers logs.
cloudflare_workers_custom_domain makes the DNS record and the certificate for you. There’s no cloudflare_dns_record to write and no CNAME to manage, but the zone has to be on Cloudflare.
outputs.tf
output "sites" {
value = { for k, m in module.site : k => m.domain }
}
terraform.tfvars
cloudflare_account_id = "your-account-id"
sites = {
blog = {
zone_id = "your-zone-id"
domain = "blog.example.com"
}
}
The account ID is on the dashboard’s account home page. The zone ID is on the domain’s Overview page, lower right. I keep a terraform.tfvars.example in git and the real file out of it.
5. The state bucket
State lives in the RustFS instance on my k3s cluster, which I reach over Tailscale, so the machine running Terraform has to be on the tailnet. Any S3-compatible store works if it supports conditional writes, because use_lockfile depends on them. On AWS this is S3 plus a DynamoDB table for the lock. Terraform 1.10 added use_lockfile, which writes a lock file next to the state, so there’s no table.
The bucket has to exist before terraform init, so create tfstate by hand and make an access key for it. Then write backend.hcl:
endpoints = {
s3 = "https://rustfs.example.com" # your S3 endpoint
}
The bucket and key are already in versions.tf. The endpoint is per machine, so it’s in this file, which is gitignored.
State can hold secrets in plain text, which is another reason it stays out of git. The store has no rollback, so before a risky apply I run terraform state pull > backup.tfstate. If an apply gets killed and leaves a stale lock, terraform force-unlock <id> clears it.
6. Secrets with SOPS
Three secrets: the Cloudflare API token, and the access key pair for the state bucket. They go in an encrypted file I can commit, instead of in my shell history.
Make a key with
age-keygen -o ~/.config/sops/age/keys.txt. Back it up. Without it the encrypted file is unrecoverable.Put the public key from that output in
.sops.yaml:creation_rules: - path_regex: secrets\.enc\.env$ age: age1...Tell SOPS where the key is. macOS looks somewhere else by default, so add this to
~/.zshrc:export SOPS_AGE_KEY_FILE=~/.config/sops/age/keys.txtRun
sops secrets.enc.envand fill in the file:CLOUDFLARE_API_TOKEN=... AWS_ACCESS_KEY_ID=... # the state bucket's key, not an AWS one AWS_SECRET_ACCESS_KEY=...
To run any command with those loaded, use sops exec-env secrets.enc.env '<command>'.
The API token (My Profile, API Tokens) needs three permissions:
- Account, Workers, Edit
- Zone, DNS, Edit
- Zone, Zone, Read
The same token drives wrangler deploy later.
7. Apply
sops exec-env secrets.enc.env 'terraform init -backend-config=backend.hcl && terraform apply'
This creates the Worker and attaches the domain. The site is empty until you upload something.
8. Point the blog at the Worker
The blog repo gets a wrangler.jsonc:
{
// Worker and custom domain are managed by Terraform in ~/code/infra.
// The name must match the key in that repo's `sites` map.
"name": "blog",
"compatibility_date": "2026-10-01",
"assets": {
"directory": "./public",
"html_handling": "auto-trailing-slash",
"not_found_handling": "404-page"
}
}
namehas to match the key insites. If it doesn’t, wrangler creates a second Worker and your domain keeps serving the empty one.directoryis Hugo’s output folder.auto-trailing-slashserves/posts/hello/fromposts/hello/index.html, which is how Hugo lays pages out.404-pageserves Hugo’s404.htmlfor missing paths.
9. Set the base URL
Hugo puts baseURL into feeds, canonical tags and the sitemap, so it has to match the real address.
baseURL = 'https://blog.example.com/'
10. Deploy
hugo --gc --minify
sops exec-env ~/code/infra/secrets.enc.env "npx wrangler deploy"
Run both from the blog repo. The secrets file stays in the infra repo, so the second command points at it by path.
The two steps are separate on purpose. wrangler deploy uploads whatever is in public/, so if you skip the build it publishes the last one.
When it breaks
- Blank site or missing posts.
draft = true, or apublishDatein the future. It’s always this. - Old content after a deploy. You didn’t rebuild. Run
hugo --gc --minifyfirst. - The domain serves an empty Worker.
nameinwrangler.jsoncdoesn’t match the key insites. - Unstyled or broken layout. Wrong
baseURL. Check where the assets are loading from. - Theme missing on a fresh clone. The theme is a submodule. Run
git submodule update --init. terraform inithangs or fails to connect. The state endpoint is unreachable. Mine needs Tailscale to be up.terraform applyis denied. The API token is missing one of the three permissions in step 6.- Sass or image errors. You need Hugo extended.