CI/CD - huntrsoftware.com

huntrsoftware.com uses Forgejo Actions workflows to automatically build and deploy the site and project documentation to the production server. This document details how that's set up.

Overview

The workflow triggers when site tags get pushed to the repository on Codeberg. A private home server runs forgejo-runner in a VM to check the Codeberg repository for an available job. When a job is available, the runner starts a fresh Docker container that follows the steps to build the site. Once built, the site is deployed to the production host (DigitalOcean Droplet).

The Releases share mentioned above has not been set up yet. For now, releases are uploaded by hand.

Self-hosted runner

The private home server runs an Ubuntu Server 24.04 VM (4 vCPU, 8 GB RAM) with Docker and forgejo-runner (pinned to 13.2.0, signature checked) running as a systemd service under its own runner user. Only the site repo can use it.

The runner account can control Docker, which effectively makes it root on whatever machine it runs on. The VM isolates that control from the rest of the home server.

The runner polls Codeberg for jobs, so nothing on the home network is exposed to the Internet. The polling interval is set to 30 seconds to use less of Codeberg's donated infrastructure.

The workflow

The deploy workflow is in the site repo under .forgejo/workflows/deploy.yaml. It's triggered when X.Y.Z site tags get pushed or via a manual dispatch. The manual method deploys whichever branch is picked (main preferred). The container is the official ubuntu:24.04 image (pinned by digest).

The workflow follows the instructions of the build guide to clone the projects to a layout matching the site's Docuriser configuration. Docuriser itself is pinned to the desired release tag, and only the docuriser-cli is built.

Every included tagged version for every project is rebuilt each time the workflow runs. Untagged projects are built as 0.0 previews; when they are tagged, their tags won't build until 0.0 --working-tree is removed from the project's line.

Deploying to production

On the production host, an SSH-only deploy user owns the webroot. The key is locked down in authorized_keys with command="rrsync -wo <webroot>",restrict, so the key gets no shell, can only write (upload and delete), and only into the webroot folder.

The deploy key (private SSH key for deploy user) and the production host key are stored as secrets for the site repo on Codeberg. With StrictHostKeyChecking=yes set, the job refuses any other host.

Limitations

• Releases are packaged by hand (Linux and Windows); there are no macOS builds yet.
• Releases are uploaded by hand until the Releases share is set up.
• A project release doesn't trigger a site deploy yet.
• Every run is a full rebuild with no caching.