The deployment of this website went through several iterations which generally failed for being too complicated or expensive to maintain before landing on this stack explicitly to solve that problem. Since this involved stringing a number of tools together, it seemed prudent to write these efforts for others (including future me) to benefit from. This is not a perfect guide to build any website in any scenario and it doesn’t aim to be; this is how this website was deployed to suit the needs of this website’s maintainers. Some parts (especially those using hugo and inside the theme) shouldcould be done better, but these work.

🤖 Site Generator 🤖

Before looking at hosting, it’s important to have anything to host. This was built with Hugo and, though the design started with the Ananke theme, the shortcomings quickly showed and a fork of that theme is now doing most of the lifting. This generator was selected because I’m quite fond of GoLang and was really just looking for a static site generator which wouldn’t do the same terrible things to CSS inheritance that Jekyl does.

To set up your own git repo as a hugo theme, you can just add it as a submodule to your side builder repo: git submodule add https://github.com/nulvox/gohugo-theme-ananke themes ananke

From there, it should play nicely as long as the submodules are always recursively updated by the tooling. Once some content is in place and the branding matches your desire, build the site and host it locally with hugo server -D then open up 127.0.0.1:1313 in your browser to take a peek.

👾 Github Pages 👾

We are looking to host this thing for free, so let’s see some github pages action. Copy the contents of your hugo build dir’s private dir into a new public repo and push it up. From the repo go to Settings -> Pages. Choose your branch and enter your domain. The webpage will present you a challenge DNS entry, go make that txt rec and let it verify. Next, make 4 A recs pointing @ at 185.199.108.153, 185.199.109.153, 185.199.110.153, and 185.199.111.153 (though these may change and you should check the official docs each time) then a C rec pointing www at <YOUR_github_org>.github.io. Wait a few min and check Enforce HTTPS.

📝 Contact Form 📝

One of the great things about the Ananke theme is how easy it makes a contact form. Sign up at Formspree and drop the link in to the contact page markdown’s form entry. It’s really that simple. If you want more throughput or custom Thank You pages, you can give them $5/month. :shrug: Whatever works for you.

😭 Make it Easy, Though 😭

Okay, so changing the thing, then running hugo, then copying files, then committing all this crap to keep track of it: 🤮 yuck. So let’s just write some yaml to tell github to do it. We already get the page deployed when we commit to main(or whichever branch you chose) because of the pages section above, so let’s add a new file to the hugo repo to define a workflow which will:

• clone both repos (recursively grabbing subrepos for the hugo code)
• setup a version of Hugo that supports our theme
• build the site
• copy the generated pages to the deployment repo
• make a commit showing the history and merge into main

This should start the pages action and deploy the entire site just because we committed to the hugo repo. Fun!

here are the contents of my .github/workflows/main.yml file:

on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.HUGO_PAT }}
          path: main
          submodules: true
          fetch-depth: 0
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: '0.140.2'
          extended: true
      - name: Build
        run: |
          cd main
          hugo mod init github.com/nulvox/gohugo-theme-ananke
          hugo --minify
      - name: Checkout pages
        uses: actions/checkout@v4
        with:
          repository: brokengadgets/brokengadgets.github.io
          token: ${{ secrets.HUGO_PAT }}
          path: pages
      - name: copy and deploy
        run: |
          cd pages
          date > generated.txt
          rm -rf images/*
          cp -pr ../main/public/* .
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add .
          git commit -m "generated by hugo runner for commit $GITHUB_SHA"
          git push

🔑 Creds 🔑

This is fine and dandy, but this action won’t have permissions to commit to the repo (if you set your life up right). If nobody has configured Personal Access Token (PAT) policies for your organization, you will need to load up org settings and define them first (in a way that is at least somewhat permissive to get some token to a user). Once that is up, open your user settings -> Developer Settings -> Personal Access Tokens -> Fine-grained tokens. From here, generate a new token and give it permissions to read and write the repos (you can’t scope these per-repo yet 😔) and generate it. Copy the content it gives you and move on over to org settings again. In the left menu pick Secrets and Variables -> Actions. Next, add a new org secret, give it a name (in our workflow it is HUGO_PAT) and ensure the repos above have access to it (both will need to be public for free hosting).

🦹‍♂️ Observe Your Machinations 🦹‍♂️

With that done, any change to the Hugo repo should redeploy the website. It’s quite satisfying to see the workflows run. To stay in the free tier on all this you can’t run more than:

• 20hrs/month GH Pipeline exec
• 50 form submissions/month Happy hosting!