From de1c7f47fc30f1aaf7acc533eb9cf4379de6d373 Mon Sep 17 00:00:00 2001
From: aramperes <aram.peres@gmail.com>
Date: Sat, 23 Aug 2025 11:50:09 -0400
Subject: [PATCH] Update README.md

---
 README.md | 124 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 120 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index a7bd7cd..d02c37a 100644
--- a/README.md
+++ b/README.md
@@ -4,10 +4,21 @@ My configurations for running a Forgejo Runner with root-less Podman Quadlets. T
 
 ## Set-up
 
+
 Install podman:
 
 ```sh
-sudo apt install podman
+sudo apt-get update && sudo apt-get install -y podman
+```
+
+Create the data directories (`/data`) for persisting Forgejo runner configurations and cache:
+
+```sh
+sudo mkdir -p /data/.cache /data/.config
+sudo touch /data/.runner
+
+sudo chown -R $UID:$UID /data
+sudo chmod -R 700 /data
 ```
 
 Clone this repository:
@@ -16,6 +27,17 @@ Clone this repository:
 git clone https://git.poire.dev/aramperes/forgejo-runner-quadlet.git
 ```
 
+For the first-time set-up, you will need to stop the Forgejo Runner from starting up so you can configure the token with your Forgejo server.
+
+```diff
+# vim forgejo-runner-quadlet/quadlets/forgejo-runner.container
+
+- Exec=/bin/sh -c "sleep 5; forgejo-runner daemon -c .config/config.yml"
+- # Exec=/bin/sh -c "while : ; do sleep 1 ; done ;"
++ # Exec=/bin/sh -c "sleep 5; forgejo-runner daemon -c .config/config.yml"
++ Exec=/bin/sh -c "while : ; do sleep 1 ; done ;"
+```
+
 Create the directory for the quadlets. SystemD will be looking for the quadlets here, and we can use symbolic links to keep them in sync with this repo.
 
 ```sh
@@ -47,18 +69,112 @@ systemctl --user daemon-reload
 systemctl --user start forgejo-runner.service
 ```
 
-Confirm the containers are running:
+Confirm the containers are running. This might take a few seconds.
 
 ```sh
 podman ps
 
 # CONTAINER ID  IMAGE                              COMMAND               CREATED         STATUS         PORTS       NAMES
-# f060983acae5  quay.io/podman/stable:latest       podman system ser...  38 seconds ago  Up 38 seconds              systemd-podman-runtime
-# 0bd5990960eb  data.forgejo.org/forgejo/runner:9  /bin/sh -c sleep ...  37 seconds ago  Up 37 seconds              systemd-forgejo-runner
+# b2e57b02edea  quay.io/podman/stable:latest       podman system ser...  6 minutes ago   Up 6 minutes               systemd-podman-runtime
+# 7521cab26b80  data.forgejo.org/forgejo/runner:9  /bin/sh -c while ...  14 seconds ago  Up 15 seconds              systemd-forgejo-runner
 ```
 
 To enable automatic start-up on boot, your user needs to have "lingering" enabled in SystemD:
 
 ```sh
 sudo loginctl enable-linger $USER
+```
+
+## Register the Runner
+
+On your Forgejo server's `Site administration` page, go to `Action` then `Runners`. Click `Create a new runner` and copy the token.
+
+Back on your Forgejo Runner host, run:
+
+```sh
+podman exec -it systemd-forgejo-runner /bin/sh
+
+# Run inside the container and follow the instructions:
+# (I recommend setting the label 'docker')
+forgejo-runner register
+
+# Confirm the .runner file has been written to:
+cat .runner
+
+# Write out default configurations:
+forgejo-runner generate-config > .config/config.yml
+
+exit
+```
+
+For building containers, you will need to tweak the runner's configurations to create privileged containers and avoid creating a nested network stack. Don't worry, this is still sandboxed inside the `podman-runtime` container.
+
+```diff
+# sudo vim /data/.config/config.yml
+
+container:
+-  network: ""
++  network: host
+-  privileged: false
++  privileged: true
+```
+
+Revert the runner's quadlet to launch the daemon:
+
+```diff
+# vim forgejo-runner-quadlet/quadlets/forgejo-runner.container
+
+- # Exec=/bin/sh -c "sleep 5; forgejo-runner daemon -c .config/config.yml"
+- Exec=/bin/sh -c "while : ; do sleep 1 ; done ;"
++ Exec=/bin/sh -c "sleep 5; forgejo-runner daemon -c .config/config.yml"
++ # Exec=/bin/sh -c "while : ; do sleep 1 ; done ;"
+```
+
+Reload the quadlet and restart it:
+
+```sh
+systemctl --user daemon-reload
+systemctl --user restart forgejo-runner.service
+```
+
+Now, in the Forgejo server Runners page, you should see your new runner as "Idle".
+
+## Example Action: build and push an image
+
+> Note, `secrets.PACKAGE_TOKEN` is a Forgejo Personal Access Token (PAT) with write-permissions to the Packages function. This has to be created manually because the automatic token `FORGEJO_TOKEN` does not have this permission. Track [this feature request](https://codeberg.org/forgejo/forgejo/issues/6198).
+
+```yaml
+# .forgejo/workflows/image.yaml
+
+on:
+  push:
+    branches:
+      - master
+jobs:
+  build:
+    runs-on: docker
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Extract the tag
+        id: extract_tag
+        run: echo "::set-output name=tag::$(echo ${{ forge.sha }} | cut -c1-10)"
+      - name: Install Buildah and Podman
+        run: apt-get update && apt-get install -y buildah podman
+      - name: Buildah Build
+        id: build-image
+        uses: redhat-actions/buildah-build@v2
+        with:
+          image: aramperes/imagename
+          tags: ${{ steps.extract_tag.outputs.tag }}
+          context: .
+          containerfiles: ./Dockerfile
+      - name: Push to Registry
+        uses: https://github.com/redhat-actions/push-to-registry@v2
+        with:
+          image: ${{ steps.build-image.outputs.image }}
+          tags: ${{ steps.build-image.outputs.tags }}
+          registry: git.poire.dev
+          username: ${{ env.FORGEJO_ACTOR }}
+          password: ${{ secrets.PACKAGE_TOKEN }}
 ```
\ No newline at end of file