Automatic Deploys to SourceHut Pages

2026-02-13

The wruby project recently had a tiny update, which included bumping up the Ruby version to 3.3.8 and setting proper encoding for file reads (to avoid errors on Debian, Ubuntu, Alpine etc.).

While making these changes, I also decided to re-launch to original wruby.site website and host it through SourceHut pages. For anyone else interested in doing the same, I’ve provided a simple guide below:

Initial Setup

Important: Before creating the files below, make sure you have read through the main SourceHut pages instructions (mainly how to set your A and AAAA records if you’re using a custom domain).

The .build.yml file

Save the following .build.yml file in the root directory of your wruby project. I’ve chosen to use Debian (stable), but SourceHut builds offer quite a lot of images to choose from.

image: debian/stable
oauth: pages.sr.ht/PAGES:RW
packages:
- hut
- ruby-full
- ruby-dev
environment:
  repo: YOUR-REPO-NAME
  site: YOUR-DOMAIN-NAME
tasks:
- publish: |
    cd $repo
    mkdir build
    sudo gem install bundler
    sudo bundle install
    ruby wruby.rb
- package-site: |
    cd $repo/build
    tar -cvzh . > ../site.tar.gz
- deploy: |
    hut pages publish -d $site --site-config $repo/siteconfig.json $repo/site.tar.gz
- deploy-www: |
    hut pages publish -d www.$site --site-config $repo/siteconfig.json $repo/site.tar.gz

Note: Make sure you update the repo and site variables under environment to match your own!

This build file will create your site for both your root domain, along with the www variation. If you decide not to support www then simply remove the deploy-www task.

The siteconfig.json file (optional)

wruby comes packaged with a 404 template by default, so you should properly configure your redirects. SourceHut pages allows you to do this with a siteconfig.json being placed in the root directory of your project:

{
  "notFound": "404/index.html"
}

That’s it. Enjoy!