I finally got tired of not knowing whether anyone reads this thing, so I spent a Saturday afternoon standing up Umami in the homelab. The install was the easy part; the instructions are dead simple.

Then I got to the bit where you expose it to the internet. I went along with the advice everyone gives, stopped halfway and decided it wasn’t good enough for me. So, I did what I normally do and stubbornly wandered off to my own path.

Quick bit of context for anyone who hasn’t gone down this particular hole. Umami is a self-hosted analytics platform: a small Node app with a PostgreSQL database to maintain persistence sans the cookies and third parties slurping up all the data. It’s as simple as dropping one script tag on your site. It posts a little blob of JSON on each page view and you get a dashboard. My install runs in an LXC on a member node of my homelab’s Proxmox cluster.

I landed on it for the “normal” reasons. Cloudflare’s Analytics are free but limited. They don’t give me precisely what I’m looking for and they’re a bit too slow for my liking. And, I’m not even going to give Google a single thought; they have enough of my data already.

Which leaves the question: how does a script tag on a public website safely and securely reach a container in my house without punching a hole in my router?

The answer everyone gives you.#

The standard answer is a Cloudflare Tunnel. A small daemon, cloudflared, runs next to your service and dials out to Cloudflare. No dicking around with port forwarding, firewall rules or opening up your router to the world. Traffic arrives at Cloudflare, goes down the pipe your daemon already opened and lands on your service. It’s genuinely lovely and it costs nothing. And since I already use Cloudflare to currently host my static websites and domains it was just the pragmatic option.

I think it’s worth noting there is a real trade off here. A tunnel means Cloudflare terminates your TLS. Since they decrypt at the edge, they could inspect whatever they like and they re-encrypt on the way down the pipe. For page view pings carrying a URL and a screen size, I genuinely do not care. For anything with secrets in the payload I would care enormously and so should you.

Anyway, Umami has an admin interface. An admin interface typically has a login page. So, most guides you’ll find after searching around will tell you to put something like Cloudflare Access in front of it. Access is an authentication layer at the edge. Basically, someone hits your hostname, Cloudflare intercepts, they sign in against an identity provider and only then does the request continue to your box.

I was about to wire it to my IDP when I actually stopped to read my own ingress config a bit more closely.

Tunnels match on path.#

The important little detail I almost skimmed past was that a tunnel’s ingress rules do not just match on hostname, but on path.

I had written this, which is what everyone starts with:

ingress = [
  {
    hostname = "analytics.nightcity.network"
    service  = "http://umami:3000"
  },
  {
    service = "http_status:404"
  },
]

You write a single hostname and everything on it goes straight to the app while anything else gets a 404. Ok.

But my analytics service only needs to expose two things to the public internet; the tracker script and the collect endpoint. Nobody on the internet needs to see /login or the dashboard, the settings, the user management or the API the dashboard talks to. So, why was I publishing everything and then buying into another service to place in front of it?

ingress = [
  {
    hostname = "analytics.nightcity.network"
    path     = "^/bundle\\.js$"
    service  = "http://nginx:80"
  },
  {
    hostname = "analytics.nightcity.network"
    path     = "^/api/v1/data$"
    service  = "http://nginx:80"
  },
  {
    service = "http_status:404"
  },
]

I only need precisely two paths out while everything else gets met with a lovely 404.

My admin interface still exists, of course ( I am not typing SQL to read my own page views ). It sits on my home network behind my own reverse proxy, reachable from the couch or over my established VPN.

Drawn out, the whole arrangement is two seperate paths that happen to share a name:

cloudflared decides what gets through and it’s only aware of two paths. My side of the picture never touches Cloudflare, or the rest of the internet, at all. That shared fork at the top is possible with split horizon DNS and which route your request takes depends on how you get to that point. I’ll explain a bit further down.

Why I think this is the better trade.#

I want to be fair to Access here, because it’s a great product and there are plenty of setups where it’s the right call. If you genuinely need to reach an admin panel from anywhere on a machine you don’t control, without a VPN, Access is exactly the kind of tool that’ll get you there.

But if you don’t need that, consider what you’re actually buying in to.

With Access, /login is on the internet. It returns a challenge instead of a form, which is much better than nothing, but the attack surface is still there. There’s an auth flow to configure, an IDP to keep working and an additional sign-in every time. Umami doesn’t consume the Access token, so you authenticate to Cloudflare and then authenticate again to Umami. Nobody has time for that nonsense.

With path scoping, /login returns a 404. There is no flow to misconfigure because there is no flow. There is nothing to leave accidentally open when you change something else eighteen months from now.

The thing I keep coming back to: an attack surface you removed cannot be misconfigured later. A control you added can. This is all about shrinking the attack surface, which is an idea that’s far older than me. We’re not doing anything new here. But a standard installation path is built to get the typical user up and running quickly. However, quick doesn’t necessarily mean appropriate for something like this.

Worth being precise about which of these is which, though. The 404 on /login is absence. There is nothing behind it to find no matter how hard you look. Umami does allow you to rename its default tracker paths as well, but that’s plainly obscurity and it buys me nothing against anyone who actually takes the time to read my page source. Outside of that, renaming dodges a blocklist that matches on names and known patterns.

Does it work though?#

The nice part about this setup is that you can test the public path without leaving the house. Using curl --resolve lets you skip your own DNS and dial the Cloudflare edge directly, while still sending the right hostname, so the request takes the same road a real visitor does.

curl -sI \
  --resolve analytics.nightcity.network:443:104.21.x.x \
  https://analytics.nightcity.network/login | head -1

Run that against a handful of paths and you get:

/                  404
/login             404
/bundle.js         200
/script.js         404
/api/v1/data       405
/api/send          404

That 405 is the collect endpoint telling me it only accepts POST, which is exactly what I want to see from a GET. It does admit the endpoint exists, where a 404 would not, but that one has to be findable anyway. Everything else gets a polite middle finger.

Meanwhile, from inside the house, the same hostname gives me the full dashboard. The same two path as before and the split falls out of the DNS I already run for network-wide adblock via a Technitium cluster.

Something worth pointing out.#

I updated the ingress config, re-ran my checks and /script.js came back with a 200. Which was alarming, because I had just watched it 404.

It was cached. Umami serves its tracker with a 24-hour cache header. My earlier testing had pulled it through the edge and Cloudflare was dutifully serving me the copy it already had. Which, to be fair, is exactly what it should normally be doing. A request with a junk query string came back 404 immediately confirming the origin was doing its job.

Worth knowing if you ever unpublish something: the edge does not find out until its copy expires. Cache invalidation strikes again!

Hark! A plot twist!#

Just after I shipped the script tag and confirmed real traffic was hitting Umami, Firefox showed me this:

Sir, this is my own site from my machine on my home network. How dare you?

As I mentioned earlier, I run split horizon DNS. Inside my network, analytics.nightcity.network resolves to a private address on my LAN so I get the dashboard directly. Outside, where you better be reading from, the same name resolves to Cloudflare and goes down the tunnel. That’s what makes the two-path thing work. I also mentioned this before in my previous article My Blog Now Ships From My Homelab! and it’s one of my favourite aspects about my setup.

But when I load my public blog from my own house, the browser sees a page served from a public origin trying to load a subresource from 10.x.x.x. Browsers have started treating that as exactly the attack it usually is: a website on the internet quietly poking at your router, your printer or your NAS. Firefox calls it Local Network Access and blocks it by default. Chrome is heading the same way.

So the one place on earth where my analytics silently do not work is the chair I’m sitting in which is precisely how it should work. If it ever bothers me, the fix is to give the tracker its own hostname in a domain my internal resolver doesn’t answer for, so it goes out to the edge from everywhere including my lounge room. I won’t be doing that as I’m all too happy skipping my own page views.

The one thing path scoping does not fix.#

Moving the admin interface off the internet does nothing for the collect endpoint. That endpoint has to accept anonymous POSTs from every visitor’s browser, or it isn’t an analytics endpoint. Umami rejects requests carrying a website ID it doesn’t recognise, which stops idle nonsense, but my real website ID is sitting in the page source of every page on this site and Plant🌱Smart. Literally anyone can read it.

So the only real control is applying some kind of rate limit. Cloudflare’s free tier, which I’m currently on because I’m cheap and actually trying to reduce my subscription costs, permits one rule at a ten second window and it insists on counting per data centre rather than globally. It’ll stop something stupid. But, it will not stop something determined.

Basically, path scoping shrinks the surface area enormously and then stops. What’s left is the stuff that’s supposed to be open. Though, the worst that can happen if the service gets hammered is fill my disk with garbage data points. Which would no-shit make me laugh.

… so, naturally I put Nginx in front of it.#

I told myself this was about the rate limit which was a lie. It took a few hours for two better reasons to turn up.

The origin is blind.#

A tunnel terminates the connection at the edge and opens a fresh one to your box, so every request arrives from the connector sitting next to your service. Umami sees 172.16.x.x, the Docker address of cloudflared, for the entire internet. That’s also why the usual advice of “just put fail2ban on it” doesn’t really apply. Fail2ban blocks source addresses with a firewall rule and no packet ever arrives from the address you’d want to block.

Cloudflare does pass the real client along in a CF-Connecting-IP header. Nginx can promote that header back into being the actual client address, which makes both the logging and the limiting mean something:

set_real_ip_from 172.16.0.0/12;
real_ip_header   CF-Connecting-IP;

limit_req_zone $binary_remote_addr zone=collect:10m rate=5r/s;

The set_real_ip_from range tells Nginx only the connector may assert that header. Nginx answers cloudflared and nothing else here and my internal route goes straight to Umami without passing through it. Meaning nothing on my LAN can forge a client address at me.

Umami logs nothing at all. Zilch.#

Its own logs are four lines of startup and then a blank stare into the void. Which means that until I put a proxy in front of it, the only record of what hit my analytics endpoint was… my analytics.

Nginx gave me an access log within about ten seconds of starting and the very first thing it told me was that I had no idea what my traffic was.

In which I am humbled by a robot.#

I had been suprised with my initial visitor numbers. Then I looked properly and roughly ~90% of it was a single machine in Singapore hammering one tiny post:

browser  os      device  screen      country  hits  sessions
chrome   Mac OS  laptop  1366x1366   SG       53    51

There are a few tells here. Not only is the screen size a perfect square, 50ish sessions with just as many hits from the same region with the same browser settings smells like a bot crawl. It was Kagi, near as I can tell, rendering the page to build a preview for Kagi Small Web. I have no real objection to that. It reaches my tracker at all because it runs the JavaScript, which an ordinary crawler never would. This is exactly the sort of thing that pollutes a dataset while you sit there feeling popular.

I don’t care about the bots. The point is that I only found it because I’d added logging. I only added logging because I was chasing a rate limit I probably didn’t need.

The small detail I liked most.#

Nginx has a default location block and mine looks like this:

location / {
    return 444;
}

444 is an Nginx special. It doesn’t return a status, but closes the connection quietly.

That rule is doing the same job as the catch-all 404 in my tunnel ingress. It holds exactly the same line only hop further in. Two independent things now have to be wrong at once before anything reaches my admin interface.

So, the tunnel is Cloudflare’s. The edge rate limit is Cloudflare’s. The Nginx config is a text file that’s mine and it doesn’t care in the slightest what is in front of it. Which matters, because I’m not 100% sold on keeping Cloudflare around longer-term.

None of the idea is Cloudflare-specific either. Any reverse proxy has a path-scoped location block and any tunnel worth the name matches on more than a hostname. Tailscale, Pangolin, NetBird or even vanilla WireGuard will get you there. I picked Tunnels as a convenient stop-gap until I move on to something a bit more “self-hosty”. The vendor is incidental. Publish only what has to be public.

In closing …#

None of this is novel. Tunnels have matched on path since forever, it’s in the docs and I’m certain plenty of people are already doing exactly this. I just hadn’t thought about it properly, because the well-trodden advice is “put an auth layer in front of it” and this kind of consensus is usually good enough that you stop thinking.

But “protect the admin panel” and “publish the admin panel and then protect it” are not the same sentence and you should be aware of the difference.

If you’re running anything through a tunnel right now, it’s worth five minutes with your ingress config. Ask yourself which paths actually need to leave your network. For a lot of self-hosted things the honest answer is “fewer than all of them”. The best answer is “none”. And if you’d rather find out than wonder, that curl --resolve trick works against any hostname, including yours. Start with /login and see what comes back.

And if you’re about to tell me the browser permission dialog is a bug, it isn’t. It’s three correct systems arguing and I’ve decided that’s a feature.

Would you like to know more?#

I kept the theory light in the post, because it kind of goes against the vibe of the site and my own casual style of writing. But the ideas underneath this are old and much better argued elsewhere, so here’s where I’d start.

• The Protection of Information in Computer Systems, Saltzer and Schroeder, 1975. The source of fail-safe defaults ( deny by default, allow by exception, which is exactly what that catch-all 404 rule is ) and economy of mechanism ( fewer moving parts means fewer parts to get wrong ). It’s a fifty year old paper and it reads like one, but section I is short and it has aged as disgracefully as I have.
• Attack Surface Analysis, OWASP. The plain-English version of the whole post, minus my nonsense. Useful if you want a structured way to ask “what am I actually exposing” about something larger than a script tag.
• Tunnel configuration file, Cloudflare. The ingress rules reference. This is the page I had skimmed past twice before noticing that path was sitting right there next to hostname.
• Local Network Access, WICG. The spec behind the permission dialog that made me raise an eyebrow. If you’d rather have prose than a spec, Chrome’s New permission prompt for Local Network Access covers the same ground and explains why browsers decided this needed fixing.

If you only read one, make it Saltzer and Schroeder. Almost everything I thought I worked out on that Saturday turns out to be in there, but described better by people who got to it first and who are far smarter than me.

So, having been bitten several times by intermittent outages and service disruptions, I figured a small personal win would be to migrate the repository for this site to the homelab. Now, it lives on my own Forgejo forge and the builds run on my own Woodpecker cluster. The only things that leave the network are static build artefacts that get pushed up to Cloudflare Pages.

The switch was surprisingly straightforward and took less than 30 minutes overall.

Before anyone reaches for the comment box, no, you don’t need a homelab for any of this. Forgejo and a Woodpecker cluster ( server and at least one agent ) will happily run on a spare mini PC, an old laptop, that Raspberry Pi you bought with the best of intentions or even as a single Docker Compose file running on the machine you use every day.

How complex can this possibly be?#

The first useful thing I did was ask myself what GitHub was actually doing for me when it comes to managing this site. After some mulling about, I could only really list the following:

• Hosting a git repository.
• Hosting the comment threads, via giscus Discussions.

That’s pretty much it. I don’t use Actions and GitHub alone never built this site. Cloudflare Pages watched the main branch and did the building itself. This is something I covered back in My Blog Publishing Setup. GitHub’s one job was holding a bunch of markdown files.

That’s a strange thing to accept as a single point of failure.

The new shape of things.#

The replacement looks like this:

• I push to Forgejo, which lives inside my homelab network.
• Forgejo fires off a message to the Woodpecker Server over a webhook. Also inside the network.
• The Woodpecker Server assigns the job to an available Woodpecker Agent, which clones the repo, builds the site with Hugo and pushes the result to Cloudflare Pages with wrangler.
• Cloudflare serves the files at the edge, exactly as before.

I just added support for mermaid diagrams, so of course I’m not going to let the opportunity to show it off slide:

The part I want you to notice is the direction of travel. Under the old setup, Cloudflare reached into GitHub to pull my source. Under the new one, nothing reaches in at all. The forge and the CI server accept no traffic from the internet. The only packet that crosses the network boundary is an outbound upload of compiled static assets.

That reversal is the entire security model which was pretty much the point. What looks like “the old way but more steps” allows me to control every aspect of the pipeline up to just before we ship the build artefacts. A push-based deploy means self-hosting your forge requires exposing exactly nothing. No reverse proxy gymnastics, no VPN for the webhook and no port forwarding required.

If my homelab bursts into flames mid-afternoon ( a real possibility as I do live in Queensland, Australia ) Cloudflare keeps serving the last deploy and nobody visiting the site would ever know. That being said, nobody actually does visit this site, so…

A small intermission.#

A short aside, because it’s a question I’d ask. My internal services hang off a domain I genuinely own, but resolving it depends on where you’re standing. Inside the network a locally hosted 3-node Technitium cluster runs the hosted zone and the router sends all DNS requests through it. Initially, I used this for network-wide adblock, which works an absolute treat. It also means the forge and the CI cluster resolve to their internal addresses. Outside the network, the public zone points at a landing page hosted elsewhere.

Same hostname and two completely different worlds depending on which side of the wall you’re on. Split-horizon DNS is nothing new, but it’s what lets me use real TLS-friendly hostnames for internal services without those services ever being reachable from the internet.

If I did decide to open some services to the outside world, like my Navidrome server, I could use an overlay network like Netbird to provide friends and family access via a familiar naming convention without ever opening a port on the router.

The part Cloudflare doesn’t clearly advertise.#

A Pages project is either connected to a git provider or it accepts direct uploads. Never both. As long as your project is wired to GitHub, wrangler pages deploy will be rejected and you will get screamed at.

Disconnect the git integration in the project settings and the project quietly converts to “Direct Upload” mode. It keeps its name, its custom domain and its whole deployment history. It just stops watching a repository and starts waiting for you to hand it those delicious files. While you’re in there, make sure the production branch is properly specified: main in my case. This matters because Wrangler tags each upload with a branch name. An upload whose branch matches the production branch goes live on the site. An upload under any other name becomes a preview deployment with its own URL instead.

After that, the deploy is one command requiring two secrets:

• An API token scoped to Cloudflare Pages: Edit
• Your Cloudflare account ID.

Both go into the Woodpecker Server as repository secrets.

Finally, our favourite! YAML.#

The whole thing is just one file named .woodpecker.yml that squats in the repository root.

when:
  - event: [push, manual]
    branch: main

clone:
  git:
    image: woodpeckerci/plugin-git
    settings:
      partial: false
      tags: true

steps:
  diagrams:
    image: minlag/mermaid-cli:11.16.1
    commands:
      - ./bin/render-diagrams

  build:
    image: hugomods/hugo:debian-git-0.163.3
    environment:
      HUGO_ENV: production
      HUGO_ENVIRONMENT: production
    commands:
      - git config --global --add safe.directory '*'
      - ./bin/changelog
      - hugo --gc

  deploy:
    image: node:22-slim
    environment:
      CLOUDFLARE_API_TOKEN:
        from_secret: cloudflare_api_token
      CLOUDFLARE_ACCOUNT_ID:
        from_secret: cloudflare_account_id
    commands:
      - >-
        npx --yes wrangler@4 pages deploy public
        --project-name=wilhelm-codes
        --branch=main
        --commit-hash="${CI_COMMIT_SHA}"
    when:
      - event: push

Only build off main.#

I test design changes and new entries locally, so a push to any other branch doesn’t start a pipeline.

We want a full clone, not a shallow one.#

This site’s changelog page renders the git log and Hugo’s enableGitInfo reads commit dates for every page. This is something I wrote about in A Changelog That Builds Itself. CI systems love shallow clones and a shallow clone here means I can’t convey the full historical picture on the page. Worse, enableGitInfo derives every article’s dates from that same truncated log, so they all come out wrong besides. Setting partial: false makes Woodpecker fetch the entire history.

Diagrams render before anything else.#

Articles on this site can embed Mermaid diagrams, like the sequence diagram further up the page. They render to static SVG at build time, not in your browser, so the site ships zero diagram JavaScript. A small script hashes each diagram’s source, renders anything that has no matching SVG yet and prunes any SVG nothing references any more. I run it locally and commit the SVGs alongside the content, which means on a clean commit this step does precisely nothing. It exists as a safety net for the day I inevitably forget.

So when I said the diagram was rendered by the pipeline it describes, I meant it literally. If I ever edit that diagram and forget to render it, this step is what quietly saves the deploy.

The build step is a stock Hugo image.#

Nothing is installed on the agent itself unless you count Docker image pulls. The image pins the exact Hugo version, ships the extended edition and includes git and bash. Both of which the changelog script that generates the data requires. The safe.directory line exists because the cloned workspace is owned by a different user than the one inside the container and git these days refuses to read a repository it thinks you stole.

The deploy step is a stock Node image.#

npx pulls Wrangler at run time. Wrangler then reads the two secrets from the environment and pushes public/ up to Pages and that’s pretty much it. Dependencies are snagged and cached at build time, which means nothing to maintain on the agents. Either step’s version gets bumped by editing one line.

Complete parity with what Cloudflare’s own build pipeline was doing, except now I can read every line of it and make it do whatever I need.

I did run into some speed bumps along the way.#

For the record, it took only three tries to get the pipeline to a “green” state.

In order of discovery:

• The plain version tags of the Hugo image are the extended edition. The reg- prefix means regular and none of them include git unless the tag says git. The tag you guess first ( exts-<version> ) doesn’t exist. It’s an odd convention, which is why it threw me off.
• Woodpecker substitutes ${VAR} expressions in the YAML before the shell ever runs. Anything it doesn’t know becomes an empty string. My safe.directory "${CI_WORKSPACE}" quietly became safe.directory "". Hence the asterisk / glob in the YAML.
• The changelog script opens with #!/usr/bin/env bash and the default Hugo images are Alpine. env: can't execute 'bash' is the whole error message you get, so I just went with the Debian variants instead which include bash out of the box.

None of these are hard problems, but worth pointing out.

I’m not deleting the old repository… completely.#

The GitHub repository still exists if only to provide a place for the giscus integration to store comments. It offloads most of this functionality to GitHub’s Discussions feature. Delete the repo and every comment ever left on this site goes with it; all 2 of them.

It no longer needed the full source history to do that job either. It was ported on over to my local forge with Forgejo’s native GitHub repository migration feature. So, I force-pushed the whole history into a black hole, leaving a single commit containing only a README. The remaining husk also has a second job coming; it’ll eventually host the companion code for tutorial content, so readers can clone examples without ever touching my forge.

Each service kept exactly the job it’s uniquely good at. Cloudflare serves files from the edge better than my house ever could and no fucking way am I publicly opening ports on a router. I’d rather lick the rim of a pub toilet. GitHub Discussions gives commenters an identity they already have. Everything else now lives at home.

In closing …#

Was any of this necessary? For a static blog that deploys in under a minute, probably not. The old setup worked fine and if yours does too, keep it. I’m not here to convince anyone.

There’s a special kind of satisfaction in watching a pipeline run end to end on hardware you can physically point at, knowing the only cloud dependency left is the one actually earning its keep. The next GitHub outage can happen without me. At least for this project anyway.

First, a Small Rant#

Before you call me a Luddite, let’s be clear here, I don’t have an issue with the technology itself. I’m an engineer. I think it all has its uses, but force-feeding it into almost every aspect of our lives with no regard to any social and environmental impacts with frequently no chance of being able to easily opt-out does not sit right with me one bit.

We’ve seen this happen over the last decade with touchscreens, IoT, blockchain, NFTs, Web3 the list goes on. All promoted by the endless parade of interchangeable, nameless faceless talentless hacks and disingenuous grifters who only care about making “BIG LINE GO UP”.

It’s all so tiring, so perhaps you can understand why I’d immediately recoil in disgust and go my own way with an alternative I can control.

Or, to put it in even simpler terms:

The “Stack”#

I suppose it’s technically a “stack”, but it seems a bit funny to use the term when referencing a blog setup. Just as with my Plant🌱Smart project, the goal is to automate as much as possible while keeping maintenance requirements and hard- and soft-dollar costs as low as possible. For this, I need only use a handful of tools to keep this space operational.

As far as the question over “cost”, outside of time spent, it’s about ~$100 AUD per year for the domain name. This blog is a very small and inconsequential part of this domain, so the overall cost is absorbed by “other stuff”.

So, the greatest cost is… time? I guess 🤷

Obsidian#

While I won’t be going into what Obsidian is and how it works, I will say it’s been a personal boon in how I keep notes and track of ideas. I have a lot of fleeting / ephemeral thoughts I that would otherwise lose instantly if I didn’t immediately jot them down using this app.

So, it makes perfect sense for me to use my personal vault to store all my blog content. The fact Obsidian content nothing more than Markdown files makes working with them using other bits of tech that much easier.

Oh, it’s free btw.

Hugo#

This is probably one of the more popular options when it comes to static site generators. It’s easy to install, is incredibly extensible and has loads of documentation to help you along. The template syntax sits upon Golang’s templating engine, so if you have a strong background as a Go developer like myself, you’ll be right at home.

However, knowing Go isn’t a hard requirement though it will make getting on top of things quite a bit easier.

What I enjoyed while learning about this project was I got to control every aspect of how I wanted my blog to look and function. Building the current design from the ground up with Hugo was incredibly fun.

Also, free. Very cool.

Cloudflare#

I already used Cloudflare to manage this domain’s DNS settings, so it only made sense to publish my static site to Cloudflare Pages over, say, Vercel or Github Pages. There’s nothing spectacular going on here outside of me just wanting to keep these two things in the same place.

That being said, I have no issues with migrating else where if the need should ever arise. Though, I doubt this blog will hit the 20k file limit of Cloudflare Pages any time soon.

Again, free for the purposes of this article. If you don’t have a dedicated personal domain, you will be provided a subdomain attached to the pages.dev apex.

The Good Stuff#

How is this all put together for day-to-day usage? Luckily, the Cloudflare stuff runs on auto-pilot, so it’s pretty much set-and-forget. I suppose you could say the same about the other components, but they’re the parts I touch the most.

I have a single vault in Obsidian. It’s where all my thoughts go. Stored within is a top-level Blog/ directory. Care to hazard a guess as to what it may contain?

Hugo has the concept of page bundles where you can group all resources associated with your blog articles within a single directory. You’ll notice above all directories mirror the blog posts hosted on this site. In my case, we can consider the directory names to be the human-friendly slugs you see in your address bar that point to the associated content. Within these directories, you’d see any other resource I may link to; source code, images, etc… The best thing about this is I only have to perform a relative reference to these resources. If I want to link to image-1.png, I only have to reference it as ![](/blog/my-blog-publishing-setup/image-1.png) without worrying about specifying an absolute path; very nice.

When I want to write a new article, I first create a new directory here. I may already have the title of the article in mind, but it can be in flux until I decide to publish it. In the new directory, I create a file called index.md. This file contains all the content of the associated article written using Markdown.

I then use an Obsidian template dedicated to new blog posts and apply it to the new file. This ensures I have all front matter properties ready to go. This makes configuring my posts in the editor that much easier.

All that’s left is writing my articles! Well, not really. I need a way to synchronise these files with my local Hugo instance. As you can see here, the content mirrors what I have stored in my Obsidian vault.

This can be easily addressed with 2 small apps:

1. fswatch which monitors a specified directory for changes and allows you to trigger subsequent commands for specific file system events. Basically, I want to watch for any changes in my Obsidian vaults Blog/ directory.
2. rsync to dynamically keep the target Hugo directory in sync with the Obsidian source directory.

I, of course, have this placed in a script that I have running in the background while I write. This is a great help during the drafting phase as I have Hugo dynamically processing and displaying these changes locally. This allows me to easily proof my work visually as I carry on writing.

Here’s the full script:

#!/usr/bin/env bash

SOURCE=${SOURCE:="${1}"}
export SOURCE

DESTINATION=${DESTINATION:="${2}"}
export DESTINATION

fswatch -o "${SOURCE}" | while read -r event; do 
    rsync -av --delete "${SOURCE}" "${DESTINATION}";
done

I keep this running whenever I’m writing a new article. Obsidian saves in almost realtime, so as I type the changes almost immediately sync across to the local Hugo server so I can review my changes.

You effectively run it as:

$ ./sync.sh /path/to/obsidian/blog/ /path/to/hugo/content/

For rsync to work as intended and keep the destination directory completely in sync with the source directory, remember to add a trailing slash to both directory arguments.

No Auto-Commit?#

Nope. Not here. There are a few other peeps with blogs out there that “commit on change”, but I prefer to have a bit more control over what actually gets published. For that, I simply use plain-old git commands to publish my new article:

$ git add -A
$ git commit -m 'some banal new bullshit screed'
$ git push origin main

Cloudflare monitors the associated repository, picks up the change and the auto-magic-ally builds and pushes everything to the public eye.

With this flow, I can see my changes locally in near realtime and push to “production” only when I’m happy with the results.

In Closing …#

I’m stoked to have my very own place again that I have complete control over. I’ve thoroughly enjoyed creating this new blog design and I may even open-source it one day.

That said, I’ve made a very loose commitment to post a new article every week this year of our lord 2025 and I’m hoping this will make things heaps simpler. I only want to worry about what I’m going to write and just get the content out there.

I sincerely hope I can keep this self-imposed weekly commitment. 😬👍