Hangar: a Netlify-Style Static Host in One Go Binary

15 min readhomelab

This blog has been built and deployed automatically since 2017. The deployment target changed a few times: a GitLab pipeline copying files to a server, then an S3 bucket behind CloudFront in 2018, which I wrote about in a previous post, and this month a Woodpecker pipeline pushing to Netlify. Netlify did the job well, but it is a far more complex product than what I needed. The two features I actually used were simple ones: every pull request got its own preview URL, and pushing to master made the site live.

In the meantime, almost everything else I run has moved into the Talos cluster in my lab: Forgejo, Woodpecker, Keycloak, the monitoring stack and an S3-compatible object store. Having the build run in that cluster and then hand the result to a third party started to feel odd, especially for a site that only ever changes when I merge something. I also had three other small static sites (the recipe site, the inf3.ch landing page and a wedding site) that each had their own way of being deployed.

So I wrote Hangar: a self-hosted static site host in a single Go binary, with the two features I cared about and not much else. You upload an archive containing the site and a small hangar.yaml, you get a secret preview URL back, and you promote that exact upload to production with a second call. You can run as many nodes as you like behind a load balancer; they share an S3 bucket (or a directory, for development) and never talk to each other.

The question that made this fun to build: can a distributed system be designed with no communication between its nodes at all, and still be eventually consistent? Here the answer is yes, because the only thing that ever changes is one small pointer per site, and the object store arbitrates who gets to change it.

This post goes through what it looks like to use, how the storage layout makes a promotion a single conditional write, how nodes stay in sync without coordination, how untrusted uploads are handled, and how it runs in the cluster behind Woodpecker.

Using it

A site is a directory with a hangar.yaml at its root. For this blog, the file is three lines plus comments: the site name, the domains it will serve once promoted, and the directory Hugo writes to.

yaml
site: blog
domains:
  - thomas.inf3.ch
  - thomas.schwery.me     # redirected to thomas.inf3.ch (static/_redirects)
root: public
not_found: 404.html
clean_urls: true

The CLI packs the directory into a tar.gz and uploads it. Here is a session against a local node with the example site that ships with the repository:

console
$ hangar deploy examples/site
Deploy b7ebeef4b9f5 of site blog uploaded (1234 bytes)
Preview:    http://k7yonzkuhqoyspe4cgpxddwh2a--blog.preview.localhost/ (until 2026-11-11 23:13)

$ hangar deploy examples/site
Deploy b7ebeef4b9f5 of site blog already uploaded (1234 bytes)
Preview:    http://k7yonzkuhqoyspe4cgpxddwh2a--blog.preview.localhost/ (until 2026-11-11 23:13)

$ hangar promote -site blog b7ebeef4b9f5
site blog now serves deploy b7ebeef4b9f5 on blog.example.com, www.blog.example.com

$ hangar deploys -site blog
ID            CREATED           BY  STATE  PREVIEW
b7ebeef4b9f5  2026-10-28 23:13  me  live   http://k7yonzkuhqoyspe4cgpxddwh2a--blog.preview.localhost/

Two things are visible here. The deploy ID is the first twelve hex digits of the archive’s SHA-256, and the CLI packs the directory deterministically, so uploading the same site twice gives the same deploy and nothing is stored a second time. Re-running a pipeline is therefore free. And the preview URL contains a random slug followed by the site name: 128 random bits, so the URL itself is the secret.

The archive can also contain a _redirects and a _headers file in the served directory, using a subset of Netlify’s format. That was a deliberate choice: the blog already had a _redirects file, and I wanted to move the sites without rewriting anything. This blog uses it for one thing, making thomas.schwery.me an alias of thomas.inf3.ch:

https://thomas.schwery.me/*  https://thomas.inf3.ch/:splat  301!

What is not supported (query parameter matching, country or role conditions, proxying to another host) is rejected at upload time with the line number, instead of being silently ignored.

Architecture

flowchart TB
    ci["Woodpecker CI<br/>POST archive · promote"]
    visitors(["Visitors · HTTPS"])

    subgraph k8s["Kubernetes cluster"]
        direction TB
        traefik["Traefik · TLS<br/>hangar.lab.inf3.xyz/api/*<br/>*.preview.lab.inf3.xyz · site domains"]

        subgraph ns["namespace hangar"]
            direction LR
            n1["hangar #1<br/>:8081 API · :8080 sites<br/>local cache"]
            n2["hangar #2<br/>:8081 API · :8080 sites<br/>local cache"]
        end

        rustfs[("RustFS · bucket hangar<br/>deploys/ previews/ production/")]
    end

    ci -- "in-cluster API" --> n1
    visitors --> traefik
    traefik --> n1
    traefik --> n2
    n1 <-- "poll every 15 s<br/>conditional writes" --> rustfs
    n2 <-- "poll every 15 s" --> rustfs

Everything lives in the object store, under four prefixes:

deploys/<site>/<id>/archive      the uploaded archive, immutable (id = first 12 hex of its SHA-256)
deploys/<site>/<id>/meta.json    domains, uploader, size, preview slug
previews/<slug>.json             secret slug → deploy, with an expiry
production/<site>.json           the live deploy + rollback history

Archives and their metadata are written once and never modified. Previews are written once and expire. The only object that changes over the life of a site is its production pointer, a small JSON document:

json
{
  "site": "blog",
  "deploy_id": "b7ebeef4b9f5",
  "sha256": "b7ebeef4b9f5e9dbd566834d37be1557d6a25a08b608e91d0a5c9b015b00edd1",
  "domains": ["blog.example.com", "www.blog.example.com"],
  "promoted_at": "2026-10-28T22:13:52Z",
  "promoted_by": "me",
  "history": []
}

This is the whole trick. There is no database, no leader, no message bus. A node that wants to know what is live lists production/. A promotion is a rewrite of one pointer. A rollback is the same rewrite with the previous ID taken from the history. Unpublishing writes a tombstone pointer, so the site stops being served but keeps its owner and its history.

A promotion is one conditional write

Since several nodes accept API calls, two promotions of the same site can happen at the same time, for example a pipeline re-run and a manual rollback. I did not want to add a lock service for that. S3 has had conditional writes for a while now (If-Match and If-None-Match on PUT), and MinIO and RustFS support them too, so the pointer is written with the ETag that was read:

go
opts := storage.PutOptions{IfNoneMatch: true}   // first promotion: the pointer must not exist
if cur != nil {
    opts = storage.PutOptions{IfMatch: etag}     // otherwise: it must still be the version we read
}
if _, err := storage.PutJSON(ctx, s.o.Store, model.ProductionKey(site), next, opts); err != nil {
    if errors.Is(err, storage.ErrPrecondition) {
        return nil, errf(http.StatusConflict, "concurrent_update",
            "site %s was changed concurrently; retry", site)
    }
    return nil, s.storeErr(err)
}

The loser of a race gets a 409 and can retry with a fresh read. Nothing is re-uploaded during a promotion: the pointer references an archive that is already in the store, so what goes live is byte for byte what was previewed.

Rollback has a subtle version of the same problem. It reads the pointer to find the previous deploy, then writes. If another promotion lands in between, the “previous” deploy it chose is no longer the right one. So the rollback write is conditional on the very ETag it read the history from, not on a second read just before writing.

Not every S3 implementation honours these headers, and some accept them and ignore them, which is worse than refusing them. At startup each node writes a probe object and checks that a PUT with If-None-Match on an existing key and a PUT with a wrong If-Match are both rejected. If they are not, the node logs a warning and falls back to read-before-write, which is correct for a single writer and racy otherwise. On the local directory backend, file locks play the role of the conditions.

The S3 client itself is about four hundred lines with no dependency: a Signature V4 implementation, verified against the reference signatures in AWS’s documentation, and the five operations Hangar needs. The whole module depends on two external packages, the YAML parser and the brotli encoder.

Nodes that share nothing

Each node runs a syncer loop. Every fifteen seconds, with 20 % of jitter so that the replicas do not hit the store together, it lists production/, compares each pointer’s ETag with what it already serves, and only fetches the sites that changed:

go
for _, o := range objs {
    site := model.SiteFromProductionKey(o.Key)
    old := cur.Sites[site]
    if old != nil && old.ETag == o.ETag {
        next[site] = old   // unchanged: keep serving the same release
        continue
    }
    // changed: download the archive, verify its SHA-256, extract,
    // precompress, and add it to the next routing table
}

When a site changed, the node downloads the archive, verifies its SHA-256 against the pointer, extracts it, builds an index of the servable files, precompresses them with gzip and brotli, and finally swaps its routing table atomically. A site whose refresh fails keeps serving its previous release. The node that handled the promotion triggers its own sync immediately, the others follow within one poll interval. There is no push and no acknowledgement, which is the point: the nodes never need to find each other.

The extracted releases and the last routing table stay on local disk. After a restart, a node loads them and starts serving before it has talked to the store at all. In the cluster, the cache is an emptyDir, so a rescheduled pod does download the live sites again, but a pod that merely restarts does not, and a store outage does not take the sites down.

Previews work the other way around, on demand. When a request arrives for <slug>--blog.preview.lab.inf3.xyz, the node reads previews/<slug>.json, checks that it belongs to that site and has not expired, downloads the deploy if it does not have it yet, and caches the result. Previews are therefore available on every node the moment the upload returns, without waiting for a poll. Unknown slugs are cached as misses for a while, and lookups are rate-limited per client IP and globally, so guessing slugs cannot turn into a stream of requests to the store.

Untrusted uploads

Everything in an upload is untrusted, even though only token holders can upload. A site build that pulls a compromised npm package could produce an archive designed to escape the extraction directory or to fill the disk.

The archive package rejects absolute paths, .., backslashes, control characters, symlinks, hard links, devices and duplicate entries. It caps the number of entries, the size of each file and the total size, and it bounds the decompressed stream itself, so a small gzip that expands to gigabytes is stopped early. On top of the name checks, all writes go through Go’s os.Root, which was added in Go 1.24: files are opened relative to a directory handle and the kernel refuses anything that resolves outside of it. Even a bug in my own validation cannot write outside the extraction directory.

Tokens are the other half. The server configuration only contains their SHA-256 digests, and the plaintext is printed once when the token is created:

console
$ hangar token -name blog-ci -scopes deploy -domains 'thomas.inf3.ch'
Token (store it as a CI secret; it is not shown again):

hgr_…

Add to the server configuration (tokens:):

  - name: blog-ci
    sha256: 01ac7eb92ecbc91a1388673d83da68b60de03c34cc8289fe7fdb802068bf4082
    scopes: [deploy]
    domains: ["thomas.inf3.ch"]

A token has scopes (deploy uploads and creates previews, promote makes things live, rolls back and deletes) and a list of domain patterns. The rule is that a token may act on a site only if it covers all the domains the site currently serves and all the domains declared in the archive. A token for the recipe site can neither take over the blog’s site name, nor claim thomas.inf3.ch under another site name, and a promotion is refused when another site already serves one of the domains. Archives also cannot claim the preview domain or anything below it.

Preview URLs are secrets, so they get a few extra measures: a single wildcard certificate for *.preview.lab.inf3.xyz, so they never appear in certificate transparency logs, Referrer-Policy: no-referrer so that a link clicked from a preview does not leak the slug, and X-Robots-Tag: noindex, nofollow.

Serving

The serving side is the boring part, on purpose. Files are served from the local disk with strong ETags, Last-Modified, range requests, and the brotli or gzip variant chosen from Accept-Encoding, precompressed at extraction time so that nothing is compressed on the request path. clean_urls turns /about.html into a 301 to /about, and /about serves about.html:

console
$ curl -sI -H 'Host: blog.example.com' http://127.0.0.1:8080/about.html
HTTP/1.1 301 Moved Permanently
Location: /about

$ curl -sI -H 'Host: blog.example.com' http://127.0.0.1:8080/about
HTTP/1.1 200 OK
Cache-Control: public, max-age=0, must-revalidate
Content-Type: text/html; charset=utf-8
Etag: "31cb4de2ef71bafc0b76"
Vary: Accept-Encoding
X-Content-Type-Options: nosniff
X-Frame-Options: DENY

Only files listed in the index built at extraction time are served. Hidden files, hangar.yaml, _redirects and _headers are never served, with an exception for /.well-known/, which the Matrix delegation on inf3.xyz needs.

Running it in the cluster

The deployment is a Kustomize directory synced by ArgoCD, like the rest of the cluster: two replicas with a rolling update that never takes a pod down before the new one is ready, a read-only root filesystem, the distroless non-root user, and an emptyDir for the cache. The server configuration is a ConfigMap generated from a file, so adding a token changes the ConfigMap hash and rolls the pods.

The store is a bucket on the RustFS instance that already serves Mimir, Loki and Tempo. Hangar gets its own user with a policy limited to listing that bucket and reading, writing and deleting objects in it. It never creates buckets, so the policy does not allow it to.

Traefik terminates TLS and routes by host: hangar.lab.inf3.xyz/api/ goes to the API port, *.preview.lab.inf3.xyz and the site domains go to the sites port. Each production site is one small IngressRoute manifest listing its domains. Subdomains of inf3.ch and schwery.me share one wildcard certificate; apex domains get their own. The health check hits /readyz, which returns 503 until the node has a routing table, so a fresh pod does not receive traffic before it has downloaded the live sites.

The pipeline

Woodpecker runs inside the cluster, so it talks to the API through the service address rather than through the public hostname. That is also deliberate for another reason: all external traffic enters through a single tunnel, so every external client has the same source IP, and the failed authentication rate limit would be shared by all of them.

The blog’s pipeline builds the site, packs it and uploads it. The archive is created with tar --sort=name --mtime=@0 --owner=0 --group=0 and gzip -n, so that the same site always gives the same archive, hence the same deploy ID. Pull requests upload and print the preview URL; pushes to master upload and promote in one call:

yaml
  - name: deploy
    image: *alpine_image
    environment:
      HANGAR_API: *hangar_api
      HANGAR_TOKEN:
        from_secret: hangar_ci_token
    commands:
      - apk add --no-cache -q curl jq
      - |
        curl -sS --fail-with-body -H "Authorization: Bearer $${HANGAR_TOKEN}" \
          --data-binary @site.tar.gz "$${HANGAR_API}?production=true" > .hangar-deploy.json \
          || { cat .hangar-deploy.json; exit 1; }
      - jq . .hangar-deploy.json
    when:
      - event: push
        branch: master

One Hugo detail: on pull requests the site is built with --baseURL /, because the preview host is random and absolute URLs pointing at thomas.inf3.ch would send every click to production. There is also a Woodpecker plugin image (hangar woodpecker) that does the same from settings, but the two curl lines were easier to read in the pipeline, so that is what the sites use for now.

The wedding site has its own token, limited to its own domains, so the secret stored in that repository cannot touch the other sites.

Testing

The end-to-end test starts two nodes on a shared local store and runs the whole life of a site: upload, preview on the other node, promotion, domain hijack attempts with a second token, rollback, deletion, garbage collection, a restart while the store is unreachable, and concurrent promotions. The same scenario runs in CI against real MinIO and RustFS service containers, together with a storage contract test that checks the conditional writes are really enforced. That is what caught the first version of the rollback race, which I had got wrong.

Limitations of the design

These are choices, and I would make them again:

  • Static files only. No functions, no forms, no proxying.
  • Uploads are a single PUT to S3, so archives are limited to 200 MB by default.
  • A promotion reaches the other nodes within one poll interval, with no acknowledgement. For a site that changes a few times a week, this is fine.

Known issues and next steps

These are problems with my deployment, not with the architecture, and I want to fix them:

  • All previews share the preview domain, so they are same-site with each other and with the rest of inf3.xyz. A malicious preview could set cookies for .inf3.xyz. The fix is a separate registrable domain for the previews, which I have not done yet.
  • The store has no backup. Losing the RustFS volume loses the previews and the rollback history. The live sites can be redeployed from CI, and the running pods keep serving from their cache meanwhile.
  • Hangar lives in the same homelab as the CI that feeds it, so if the lab goes dark, my websites go dark with it. I plan to run a node on a VPS against the same bucket. That is only a stopgap: it keeps serving from its local cache for as long as it stays up, but it cannot sync or restart cold while the lab is unreachable. A lasting fix needs a bucket that lives outside the lab.

Conclusion

Hangar replaces an external service that was far more complex than what I needed with one I understand end to end. The benefits are quicker deployments through the pipelines and better control over what goes live and where. The cost is every other Netlify feature that I never used. Four sites now share a single deployment path instead of four different ones.

It was also a good exercise in architecture: decide what the storage has to guarantee, keep everything else out, and let one conditional write carry the consistency. Nodes that never talk to each other turned out to be enough.