How To Host A Website on Sourcehut Pages (With a Custom Domain)


Sourcehut pages, similar to GitHub pages, is a service where you can host a static website.

Deploying a website to Sourcehut pages utilizes two of Sourcehut's services - git and builds respectively.

Understanding Sourcehut Builds

builds, as you might expect, is a build service. It essentially runs tasks for you, such as building and deploying a website. This is what you'll use to deploy your website.

To use the builds service, you need to create a build manifest. This is a YAML file which describes some information about your website to be used with sourcehut builds.

Inside of your git repository, create a file called .build.yml which will form your build manifest.

By placing a .build.yml file in a git repository (that is also using sourcehut’s git service), your build will be submitted everytime you push.

This is great because it means every time that you update your website, the build will publish the new version automatically for you.

Creating a Build Manifest

A build manifest takes some properties, such as image and tasks and runs them accordingly.

Inside of your .build.yml file, you can start adding the following properties.

image: alpine/edge
  - hut
  - zola
  - build: |
      cd personal-website
      zola build
  - package: |
      cd personal-website
      tar -C public -cvz . > ../site.tar.gz
  - upload: |
      hut pages publish -d $site site.tar.gz

What each property in the build manifest does:

In the example above, I build the website with zola build, then tarball the public directory where the website output is created. Tarballing it just compresses it so you’re sending it zipped to users browsers, so smaller files to to be sent.

Uploading uses the hut cli tool installed earlier, and passes the domain you want to deploy to with -d flag with the $site environment variable. You can use a custom domain here or use your Sourcehut username followed by e.g.

To use a custom domain, in your domain settings (wherever you purchased the domain) you need to set up a new A record, with the name @ and the value .

Deploying Your Website

Once you have the .build.yml created and in your git repository, every time you push to Sourcehut it will deploy your website.

I hope you enjoyed!