Publishing Static Sites on sourcehut pages

[GunnarGrop] - - 4 mins read

Abstract

I mentioned in a previous post that I use Kubernetes to deploy my blog. Since my professional work (and my homelab) consists primarily of managing Kubernetes deployments, this didn’t seem like a bad idea. Albeit a bit overkill. But I had all the infrastructure in place, so I went with it.

I’ve also mentioned that I’ve migrated all my personal git repositories over to sourcehut recently, but it wasn’t until yesterday that my brain registered that sourcehut has another component, pages, that allow you to publish static websites… This is way easier!

Not only is it super easy to use, and integrates well with other sourcehut components (git/hg, builds), but every user even gets their own domain, in the form of username.srht.site. It’s also very easy to use your own custom domains! This can be done at your domain registrar, by pointing you DNS records to the following IPv4 (A record) and IPv6 (AAAA record) addresses.

@ IN A 46.23.81.157

@ IN AAAA 2a03:6000:1813:1337::157

Note: These IP addresses might be subject to changes. Please always refer to the official documentation.

Anyhow, I thought I might do a little write-up on how to use sourcehut pages, and just to tell you that I’ve migrated this blog over to it.

Publishing your Site

You’ll only need a few things for this to work.

You can take a log at the source code for this blog, if you want a reference on what such a git repo might look like: https://git.sr.ht/~gunnargrop/grop.dev.

The name of the git repository should preferably be the name of the site. In my case, the repo is called “grop.dev”. In your case it might be called “username.srht.site”.

After you have your git repository, we just have to create a build manifest. This is done by creating a file called .build in the root of the repository. The file will look something like this:

---
image: alpine/latest

oauth: pages.sr.ht/PAGES:RW

packages:
  - hut
  - hugo

environment:
  site: username.srht.site

tasks:
  - package: |
      cd $site
      hugo
      tar -C public -cvz . > ../site.tar.gz

  - upload: |
      hut pages publish -d $site site.tar.gz

And that’s it! After you’ve created this build manifest, whenever you push changes a commit to your repository, this build manifest will trigger and publish your Hugo site to your sourcehut page. Which you can then visit at https://username.srht.site. 🙂

Of note here is that we’re using a tool called hut, a CLI tool to interact with sourcehut. It authenticates to sourcehut using OAuth2 token, which the build system has a handy keyword for. The oauth keyword takes care of generating a token for us, that the CLI tool will use in our build.

# In this case, we generate a token that grants us read/write
# permissions to the sourcehut pages API
oauth: pages.sr.ht/PAGES:RW

But is this CI good enough? I don’t think so, since I don’t want changes to get published every time I push something to my repo. This can be solved by just not triggering the CI when we push something, like so:

git push --push-option skip-ci

That’s what I do normally, to not unnecessarily waste sourcehut resources, but I also added another part to the build manifest, so it just publishes my page when I push a new git tag to the repo.

---
image: alpine/latest

oauth: pages.sr.ht/PAGES:RW

packages:
  - hut
  - hugo

environment:
  site: grop.dev

tasks:
  - setup: |
      # Exit pipeline if NOT triggered by tag
      if [[ "$GIT_REF" != refs/tags/* ]]; then
          complete-build
      fi

  - package: |
      cd $site
      hugo
      tar -C public -cvz . > ../site.tar.gz

  - upload: |
      hut pages publish -d $site site.tar.gz

Conclusion

As you can see, it’s in fact very easy to publish your own static site to sourcehut pages. I would recommend giving it a go if you want an easy place to host you blog, or whatever else!