From 98b47cc42b4010216ce4c37ade51d3b1a1794890 Mon Sep 17 00:00:00 2001
From: joseph <nampdn@protonmail.com>
Date: Fri, 28 Aug 2026 16:09:11 +0000
Subject: [PATCH] =?UTF-8?q?Cache=20l=C3=AAn=20volume,=20ghim=20image=20the?=
 =?UTF-8?q?o=20digest,=20xo=C3=A1=20runner.sh=20l=E1=BB=99=20token?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

1) Cache act_runner phải nằm trên volume.
   Mặc định cache.dir rỗng -> act_runner ghi vào $HOME/.cache/actcache, tức
   WRITABLE LAYER của container. Đo thực tế trên ba máy: 278 GB / 95 GB / 32 GB
   nằm ở đó, mất sạch chỉ với một lệnh docker compose up -d.
   Thêm volume runner-cache mount vào /cache và đặt cache.dir="/cache".
   Hai chỗ này phải luôn đổi cùng nhau.

2) Ghim image theo digest thay vì :nightly.
   Tag tự cập nhật nghĩa là compose pull có thể tạo lại container sau lưng, kéo
   theo mất cache. Nâng cấp có chủ đích: đổi digest, commit, rồi mới áp dụng.

3) XOÁ runner.sh.
   Nó lỗi thời (đã thay bằng docker compose) và quan trọng hơn: nó chứa
   GITEA_RUNNER_REGISTRATION_TOKEN dạng plaintext đã commit vào git. Ai có token
   đó đăng ký được runner vào Gitea, tức chạy job tuỳ ý trên hạ tầng này.
   XOÁ FILE LÀ CHƯA ĐỦ - token vẫn nằm trong lịch sử git, BẮT BUỘC phải thu hồi
   và cấp lại token trong Gitea.

4) README: bổ sung bước clone cho máy builder mới, cảnh báo phải kiểm tra job
   đang chạy trước khi tạo lại runner (tạo lại là mồ côi job đang chạy), và
   phần dọn rác trong DinD (image/volume/build cache không tự dọn - một máy đo
   được 515 image thừa và 71 GB build cache).
---
 README.md          | 44 ++++++++++++++++++++++++++++++++++++++++++--
 config.yaml        |  5 ++++-
 docker-compose.yml | 10 +++++++++-
 runner.sh          | 14 --------------
 4 files changed, 55 insertions(+), 18 deletions(-)
 delete mode 100755 runner.sh

diff --git a/README.md b/README.md
index bf61879..194bf63 100644
--- a/README.md
+++ b/README.md
@@ -9,12 +9,17 @@ parallel jobs.
 Requires Docker + Docker Compose.
 
 ```bash
+git clone https://git.vysma.dev/nampdn/act_runner.git && cd act_runner
 cp .env.example .env
 # edit .env: set GITEA_RUNNER_NAME (unique per machine) and a fresh
 # GITEA_RUNNER_REGISTRATION_TOKEN from Gitea -> Actions -> Runners -> Create Runner
 docker compose up -d
 ```
 
+Nothing else to edit — `config.yaml` ships with working defaults. Tweak
+`runner.capacity` per machine if its CPU/RAM differ; that edit will show up as a
+local modification in `git status`, which is expected.
+
 Verify:
 
 ```bash
@@ -26,7 +31,18 @@ docker logs gitea-runner-wsl 2>&1 | tail     # "declare successfully"
 
 - **Parallel jobs**: `config.yaml` -> `runner.capacity` (default 4)
 - **Job images**: `config.yaml` -> `runner.labels` (ubuntu-latest/22.04/24.04)
-- **Cache**: enabled in `config.yaml`; layer cache persists in the `dind-storage` volume
+- **Cache**: `config.yaml` -> `cache.dir: "/cache"`, mounted from the
+  `runner-cache` volume. Docker layer cache persists separately in `dind-storage`.
+
+  > ⚠️ Leaving `cache.dir` empty makes act_runner write to `$HOME/.cache/actcache`
+  > — the container's **writable layer**, not a volume. Measured in production:
+  > 278 GB / 95 GB / 32 GB of cache sitting there across three machines, all of it
+  > destroyed by a single `docker compose up -d`. The two settings
+  > (`cache.dir` and the `runner-cache` mount) must always be changed together.
+
+- **Runner image**: pinned by digest, not `:nightly`. A floating tag means
+  `docker compose pull` can recreate the container behind your back — and with it,
+  wipe the cache. Upgrade deliberately: change the digest, commit, then apply.
 
 ## Rust workflows
 
@@ -39,8 +55,32 @@ It uses `actions-rust-lang/setup-rust-toolchain` which caches `~/.cargo` and
 ```bash
 docker compose up -d      # apply config changes
 docker compose down       # stop (registration persists in volume)
-docker compose pull       # update runner/dind images
 ```
 
+⚠️ **Check for running jobs before recreating the runner.** Recreating it orphans
+any job in flight — Gitea marks them failed and you have to re-run:
+
+```bash
+docker exec gitea-runner-dind docker ps --format '{{.Names}}' | grep -v buildkit
+```
+
+Wait until that prints nothing (`buildx_buildkit_builder-*` is a helper, not a job).
+
+### Housekeeping
+
+Job images, volumes and BuildKit cache pile up inside DinD and are never reaped
+automatically. Measured on one machine: 515 unused images and a 71 GB build cache.
+
+```bash
+docker exec gitea-runner-dind docker image prune -af --filter until=168h
+docker exec gitea-runner-dind docker builder prune -f --keep-storage 20GB
+# volume prune only removes *anonymous* volumes; task volumes are named:
+for v in $(docker exec gitea-runner-dind docker volume ls -q | grep '^GITEA-ACTIONS-TASK'); do
+  docker exec gitea-runner-dind docker volume rm "$v" 2>/dev/null
+done
+```
+
+Keep `act-toolcache` and don't wipe the BuildKit cache outright — cap it instead.
+
 > Each machine needs a unique `GITEA_RUNNER_NAME` and its own registration token.
 > Run `docker compose down -v` to fully reset (drops registration + caches).
diff --git a/config.yaml b/config.yaml
index 1cc4ac6..33d9ae6 100644
--- a/config.yaml
+++ b/config.yaml
@@ -23,7 +23,10 @@ runner:
 cache:
   # Built-in cache server so actions/cache works (Rust deps, target/, etc.)
   enabled: true
-  dir: ""
+  # PHẢI trỏ vào volume. Để rỗng thì act_runner ghi vào $HOME/.cache/actcache
+  # tức writable layer của container -> mất sạch mỗi lần container bị tạo lại.
+  # Phải khớp với mount runner-cache:/cache trong docker-compose.yml.
+  dir: "/cache"
   # Empty host -> auto-detect outbound IP reachable from job containers.
   host: ""
   port: 0
diff --git a/docker-compose.yml b/docker-compose.yml
index a911684..be8d2f0 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -32,7 +32,10 @@ services:
       start_period: 10s
 
   runner:
-    image: docker.io/gitea/act_runner:nightly
+    # Ghim theo digest, KHÔNG dùng :nightly. Tag tự cập nhật + cache nằm trong
+    # writable layer = một lệnh 'compose pull' là mất sạch cache.
+    # Nâng cấp có chủ đích: đổi digest ở đây rồi commit.
+    image: docker.io/gitea/act_runner@sha256:7940221bcfc9df16f3401ddafb2231bf98bba5517bc381224c7a2c504b558974
     container_name: gitea-runner-wsl
     restart: unless-stopped
     depends_on:
@@ -56,6 +59,10 @@ services:
       - runner-data:/data
       # Shared with dind; see the --host comment on the dind service.
       - dind-sock:/dind-sock
+      # Cache của actions/cache. Mặc định act_runner ghi vào
+      # $HOME/.cache/actcache = WRITABLE LAYER của container -> mất sạch mỗi
+      # lần container bị tạo lại. Phải khớp với cache.dir trong config.yaml.
+      - runner-cache:/cache
 
 networks:
   runner:
@@ -64,3 +71,4 @@ volumes:
   dind-storage:
   runner-data:
   dind-sock:
+  runner-cache:
diff --git a/runner.sh b/runner.sh
deleted file mode 100755
index 7dc8d73..0000000
--- a/runner.sh
+++ /dev/null
@@ -1,14 +0,0 @@
-#!/bin/bash
-
-CONTAINER_NAME=gitea-runner-wsl
-docker stop $CONTAINER_NAME 
-docker rm $CONTAINER_NAME
-docker run \
-    -e GITEA_INSTANCE_URL=https://git.vysma.dev \
-    -e GITEA_RUNNER_REGISTRATION_TOKEN=hSaHcqGa82SlehNQ4GvoNmd863xovuBfZGM4jH0P \
-    -e GITEA_RUNNER_NAME=nampdn-wsl \
-    -v /var/run/docker.sock:/var/run/docker.sock \
-    --name $CONTAINER_NAME \
-    -d docker.io/gitea/act_runner:nightly
-
-