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.

  1. Make a key with age-keygen -o ~/.config/sops/age/keys.txt. Back it up. Without it the encrypted file is unrecoverable.

  2. Put the public key from that output in .sops.yaml:

    creation_rules:
      - path_regex: secrets\.enc\.env$
        age: age1...
    
  3. 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.txt
    
  4. Run sops secrets.enc.env and 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"
  }
}
  • name has to match the key in sites. If it doesn’t, wrangler creates a second Worker and your domain keeps serving the empty one.
  • directory is Hugo’s output folder.
  • auto-trailing-slash serves /posts/hello/ from posts/hello/index.html, which is how Hugo lays pages out.
  • 404-page serves Hugo’s 404.html for 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 a publishDate in the future. It’s always this.
  • Old content after a deploy. You didn’t rebuild. Run hugo --gc --minify first.
  • The domain serves an empty Worker. name in wrangler.jsonc doesn’t match the key in sites.
  • 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 init hangs or fails to connect. The state endpoint is unreachable. Mine needs Tailscale to be up.
  • terraform apply is denied. The API token is missing one of the three permissions in step 6.
  • Sass or image errors. You need Hugo extended.
← Back to articles