Complete first version

README.md

@@ -0,0 +1,51 @@
+# Build and Set Up a Github-compatible Forgejo Runner on Proxmox
+
+In order for Forgejo workflows to be usable out-of-the-box with as many
+actions as possible, it is useful to habe a runner that supports the same
+tools as the standard Github runner `ubuntu-latest`. Github does publish the
+code they use to build their runner images at
+https://github.com/actions/runner-images, but that repo cannot be used
+directly to build KVM images for use with Proxmox.
+
+The fork https://github.com/fffonion/runner-images-kvm has the necessary
+changes to enable building such images.
+
+## Building the KVM runner image
+
+The script `build-github-runner-kvm-ubuntu-latest-qcow.sh` installs the
+necessary package dependencies to build a KVM image, Hashicorp Packer (in
+the latest version still licensend under the MPL), and builds the Ubuntu
+image (24.04 at the moment). The resulting image
+`github-runner-image-ubuntu-24.04.qcow2` can then be used in Proxmox, or any
+other KVM based virtualization solution.
+
+## Creating a Proxmox template VM
+
+The script `build-forgejorunner-template.sh` runs on a Proxmox cluster host.
+It runs the build script via SSH on a builder VM (that has nested virtualization
+enabled), in case of CCCHH a Debian 12 install. It then copies the resulting VM to the
+Proxmox host.
+
+It creates a template VM from the image, installing https://code.forgejo.org/forgejo/runner
+and some helper scripts.
+
+## Cloning the Template VM
+
+You can clone the template VM from the GUI, or through `qm clone`. Make the
+necessary changes and boot the VM.
+
+You can clone and register the runner using the script
+`clone-and-register.sh`.
+
+## Registering the Runner
+
+You can run the registration by logging in to the VM either on the console
+or through SSH, by running `forgejo-runner register` as the `forgejo-runner`
+user, or by invoking `/usr/local/bin/register-forgejo-runner`, supplying the
+registration token as the first argument.
+
+You can run the registration from the Proxmox cluster host:
+```
+qm guest exec 150 -- sudo -iu forgejo-runner register-forgejo-runner iwKWPwI3H6h93kRuhXqMPcmCR2OGpgZlDT3mufGb
+qm guest exec 150 -- systemctl restart forgejo-runner
+```

build-forgejorunner-template.sh

@@ -19,20 +19,26 @@ vm_storage="local-zfs"
 #ssh ${builder_host} sudo sh <${builder_script}
 #scp ${builder_host}:${runner_image} .
 
-#wget --output-document=forgejo_runner ${forgejo_runner_url} 
+wget --output-document=forgejo-runner ${forgejo_runner_url} 
 wget -N https://git.hamburg.ccc.de/CCCHH/infrastructure-authorized-keys/raw/branch/trunk/authorized_keys
 
 virt-customize -a ${runner_image} \
 	--update \
+	--run-command 'apt dist-upgrade -y' \
 	--install qemu-guest-agent \
 	--run-command 'systemctl enable fstrim.timer' \
 	--edit '/etc/passwd:$_ = "" if /^forgejo:/' \
 	--edit '/etc/group:$_ = "" if /^forgejo:/' \
-	--run-command 'useradd --groups docker --create-home --shell /bin/bash --uid 2000 --user-group forgejo' \
+	--run-command 'useradd --groups docker --create-home --shell /bin/bash --uid 2000 --user-group forgejo-runner' \
-	--copy-in forgejo_runner:/usr/local/bin \
+	--copy-in forgejo-runner:/usr/local/bin \
-	--run-command 'chown root:bin /usr/local/bin/forgejo_runner' \
+	--run-command 'chown root:bin /usr/local/bin/forgejo-runner' \
-	--run-command 'chmod 0555 /usr/local/bin/forgejo_runner' \
+	--run-command 'chmod 0555 /usr/local/bin/forgejo-runner' \
 	--copy-in forgejo-runner.service:/etc/systemd/system \
+	--copy-in register-forgejo-runner.sh:/usr/local/bin \
+	--run-command "mv /usr/local/bin/register-forgejo-runner.sh /usr/local/bin/register-forgejo-runner" \
+	--run-command "chown root:bin /usr/local/bin/register-forgejo-runner" \
+	--run-command "chmod +x /usr/local/bin/register-forgejo-runner" \
+
 
 qm destroy ${vm_id} || true
 qm create ${vm_id} --name "${vm_name}" --memory 2048 --net0 virtio,bridge=${vm_bridge}

build-github-runner-kvm-ubuntu-latest-qcow.sh

@@ -31,5 +31,5 @@ cd runner-images-kvm/images/ubuntu/templates
 packer init ubuntu-24.04.pkr.hcl
 packer build ubuntu-24.04.pkr.hcl
 cd ${HERE}
-mv runner-images-kvm/images/ubuntu/templates/output-custom_image/ubuntu-24.04 github-runner-image-ubuntu-24.04.qcow
+mv runner-images-kvm/images/ubuntu/templates/output-custom_image/ubuntu-24.04 github-runner-image-ubuntu-24.04.qcow2
 rm -r runner-images-kvm

clone-and-register.sh

@@ -0,0 +1,24 @@
+#!/bin/sh
+
+#
+# Clone the template VM and register the runner with Forgejo
+#
+
+if [ $# -ne 2 ]; then
+	echo "usage: $0 vmid registration-token"
+fi
+
+vm_id="$1"
+token="$2"
+
+qm clone 9042 ${vm_id}
+qm start ${vm_id}
+while :; do
+	qm agent ${vm_id} ping && break
+	echo "waiting for VM ${vm_id} to complete boot..."
+	sleep 10
+done
+
+qm guest exec ${vm_id} -- sudo -iu forgejo-runner register-forgejo-runner "${token}"
+qm guest exec ${vm_id} -- systemctl restart forgejo-runner
+

register-forgejo-runner.sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+
+if [ -z "$1" ]; then
+	echo "usage: $0 <registration token>"
+	exit 64
+fi
+
+rel="$(lsb_release -rs 2>/dev/null)"
+
+forgejo-runner register --no-interactive \
+  --name "ubuntu-${rel}-$(hostname)" \
+  --instance https://git.hamburg.ccc.de/ \
+  --labels ubuntu-latest:host://-self-hosted,ubuntu-${rel}:host://-self-hosted \
+  --token "$1"